tjs-lang 0.7.7 → 0.8.0

package/src/lang/emitters/dts.ts

@@ -81,6 +81,15 @@ export function typeDescriptorToTS(td: TypeDescriptor): string {
       }
       base = 'any'
       break
+    case 'function': {
+      const params = td.params ?? []
+      const returns = td.returns ? typeDescriptorToTS(td.returns) : 'any'
+      const args = params
+        .map((p) => `${p.name}: ${typeDescriptorToTS(p.type)}`)
+        .join(', ')
+      base = `(${args}) => ${returns}`
+      break
+    }
     default:
       base = 'any'
   }

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

@@ -876,6 +876,13 @@ export function runAllTests(
     // 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.
     for (const test of tests) {
       results.push({
         description: test.description,
@@ -883,7 +890,6 @@ export function runAllTests(
         error: isUnresolvedRef
           ? undefined
           : `Module execution failed: ${e.message}`,
-        line: test.line,
       })
     }
     for (const info of syncSigTestInfos) {
@@ -897,7 +903,6 @@ export function runAllTests(
           ? undefined
           : `Module execution failed: ${e.message}`,
         isSignatureTest: true,
-        line: info.line,
       })
     }
   }
@@ -949,7 +954,7 @@ function runTestBlocks(
       const tjsStub = `
         const __saved_tjs = globalThis.__tjs;
         class __MonadicError extends Error { constructor(m,p,e,a,c){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c;} }
-        const __stub_tjs = { version: '0.0.0', MonadicError: __MonadicError, pushStack: () => {}, popStack: () => {}, getStack: () => [], typeError: (path, expected, value) => new __MonadicError(\`Type error at \${path}: expected \${expected}\`, path, expected, typeof value), createRuntime: function() { return this; } };
+        const __stub_tjs = { version: '0.0.0', MonadicError: __MonadicError, pushStack: () => {}, popStack: () => {}, getStack: () => [], typeError: (path, expected, value) => new __MonadicError(\`Type error at \${path}: expected \${expected}\`, path, expected, typeof value), toBool: (v) => (v instanceof Boolean || v instanceof Number || v instanceof String) ? Boolean(v.valueOf()) : Boolean(v), createRuntime: function() { return this; } };
         globalThis.__tjs = __stub_tjs;
       `
       const tjsRestore = `globalThis.__tjs = __saved_tjs;`
@@ -1308,7 +1313,7 @@ function runSignatureTest(
     const tjsStub = `
       const __saved_tjs = globalThis.__tjs;
       class __MonadicError extends Error { constructor(m,p,e,a,c){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c;} }
-      const __stub_tjs = { version: '0.0.0', MonadicError: __MonadicError, pushStack: () => {}, popStack: () => {}, getStack: () => [], typeError: (path, expected, value) => new __MonadicError(\`Type error at \${path}: expected \${expected}\`, path, expected, typeof value), createRuntime: function() { return this; } };
+      const __stub_tjs = { version: '0.0.0', MonadicError: __MonadicError, pushStack: () => {}, popStack: () => {}, getStack: () => [], typeError: (path, expected, value) => new __MonadicError(\`Type error at \${path}: expected \${expected}\`, path, expected, typeof value), toBool: (v) => (v instanceof Boolean || v instanceof Number || v instanceof String) ? Boolean(v.valueOf()) : Boolean(v), createRuntime: function() { return this; } };
       globalThis.__tjs = __stub_tjs;
     `
     const tjsRestore = `globalThis.__tjs = __saved_tjs;`

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

@@ -1,10 +1,14 @@
 /**
  * TJS WASM Bootstrap Generation
  *
- * Compiles inline WASM blocks and generates JavaScript bootstrap code.
+ * Compiles the file's WASM blocks into a single WebAssembly.Module with
+ * one exported function per block, then emits JavaScript that compiles
+ * and instantiates the module once at startup. This is the foundation
+ * for cross-file wasm composition (see wasm-library-plan.md, Phase 3) —
+ * once everything's in one module, intra-module calls cost nothing.
  */
 
-import { compileToWasm } from '../wasm'
+import { compileBlocksToModule } from '../wasm'
 import type { WasmBlock } from '../parser'
 
 export function generateWasmBootstrap(blocks: WasmBlock[]): {
@@ -16,75 +20,61 @@ export function generateWasmBootstrap(blocks: WasmBlock[]): {
     byteLength?: number
   }[]
 } {
-  const results: {
-    id: string
-    success: boolean
-    error?: string
-    byteLength?: number
-  }[] = []
-  const compiledBlocks: {
-    id: string
-    base64: string
-    captures: string[]
-    needsMemory: boolean
-    wat: string
-  }[] = []
+  const compiled = compileBlocksToModule(blocks)
 
-  for (const block of blocks) {
-    const result = compileToWasm(block)
-    if (result.success) {
-      // Convert bytes to base64 for embedding
-      const base64 = btoa(String.fromCharCode(...result.bytes))
-      compiledBlocks.push({
-        id: block.id,
-        base64,
-        captures: block.captures,
-        needsMemory: result.needsMemory ?? false,
-        wat: result.wat ?? '',
-      })
-      results.push({
-        id: block.id,
-        success: true,
-        byteLength: result.bytes.length,
-      })
-    } else {
-      results.push({
-        id: block.id,
-        success: false,
-        error: result.error,
-      })
+  // Map per-block status to the public result shape (preserves input order)
+  const exportById = new Map(compiled.exports.map((e) => [e.id, e]))
+  const results = compiled.results.map((r) => {
+    if (!r.success) {
+      return { id: r.id, success: false, error: r.error }
     }
-  }
+    const exp = exportById.get(r.id)!
+    return {
+      id: r.id,
+      success: true,
+      byteLength: compiled.bytes.length,
+      // Per-export byte length isn't meaningful in the consolidated module;
+      // we report the total module size for every successful block.
+      _exportName: exp.exportName,
+    }
+  })
 
-  if (compiledBlocks.length === 0) {
+  if (compiled.exports.length === 0) {
     return { code: '', results }
   }
 
-  // Generate WAT comments for each block
-  const watComments = compiledBlocks
-    .map((b) => {
-      const watLines = b.wat.split('\n').map((line) => ` * ${line}`)
-      return `/**\n * WASM: ${b.id}\n${watLines.join('\n')}\n */`
+  // WAT comment block — one section per included function
+  const watComments = compiled.exports
+    .map((e) => {
+      const watLines = e.wat.split('\n').map((line) => ` * ${line}`)
+      return `/**\n * WASM: ${e.id} (export: ${e.exportName})\n${watLines.join(
+        '\n'
+      )}\n */`
     })
     .join('\n')
 
-  // Generate self-contained bootstrap code
-  // This runs immediately and sets up globalThis.__tjs_wasm_N functions
-  const blockData = compiledBlocks
+  // Per-export metadata embedded in the bootstrap.
+  //   id   = original block id (becomes globalThis[id])
+  //   n    = export name in the composed module (instance.exports[n])
+  //   c    = capture annotations for type-aware wrapping
+  //   m    = whether this export uses memory (must be true if any other
+  //          export uses it, since memory is shared at module level)
+  const exportData = compiled.exports
     .map(
-      (b) =>
-        `{id:${JSON.stringify(b.id)},b64:${JSON.stringify(
-          b.base64
-        )},c:${JSON.stringify(b.captures)},m:${b.needsMemory}}`
+      (e) =>
+        `{id:${JSON.stringify(e.id)},n:${JSON.stringify(
+          e.exportName
+        )},c:${JSON.stringify(e.captures)},m:${e.needsMemory}}`
     )
     .join(',')
 
-  // Check if any block needs memory (shared across all blocks)
-  const anyNeedsMemory = compiledBlocks.some((b) => b.needsMemory)
+  const moduleBase64 = btoa(String.fromCharCode(...compiled.bytes))
+  const anyNeedsMemory = compiled.needsMemory
 
   const code = `${watComments}
 ;(async()=>{
-const __wasmBlocks=[${blockData}];
+const __wasmExports=[${exportData}];
+const __wasmModuleB64=${JSON.stringify(moduleBase64)};
 const __b64ToBytes=s=>{const b=atob(s),a=new Uint8Array(b.length);for(let i=0;i<b.length;i++)a[i]=b.charCodeAt(i);return a};
 const __parseType=c=>{const m=c.match(/^(\\w+)\\s*:\\s*(\\w+)$/);if(!m)return{n:c,t:'f64',a:false};const[,n,ts]=m;const at={Float32Array:'f32',Float64Array:'f64',Int32Array:'i32',Uint8Array:'i32'};if(at[ts])return{n,t:'i32',a:true,at:ts};return{n,t:'f64',a:false}};
 ${
@@ -94,30 +84,32 @@ let __woff=0;
 globalThis.wasmBuffer=function(Ctor,len){const bytes=len*Ctor.BYTES_PER_ELEMENT;const align=Math.max(Ctor.BYTES_PER_ELEMENT,16);__woff=(__woff+align-1)&~(align-1);const arr=new Ctor(__wasmMem.buffer,__woff,len);__woff+=bytes;return arr};`
     : ''
 }
-for(const{id,b64,c,m}of __wasmBlocks){
-  const bytes=__b64ToBytes(b64);
+const __wasmInst=await WebAssembly.instantiate(await WebAssembly.compile(__b64ToBytes(__wasmModuleB64)),${
+    anyNeedsMemory ? '{env:{memory:__wasmMem}}' : '{}'
+  });
+for(const{id,n,c,m}of __wasmExports){
+  const compute=__wasmInst.exports[n];
   const params=c.map(__parseType);
   const hasArrays=params.some(p=>p.a);
-  const mem=m?__wasmMem:null;
-  const imp=mem?{env:{memory:mem}}:{};
-  const inst=await WebAssembly.instantiate(await WebAssembly.compile(bytes),imp);
-  const compute=inst.exports.compute;
   if(!hasArrays){globalThis[id]=compute;continue}
   globalThis[id]=function(...args){
-    const mv=new Uint8Array(mem.buffer);let off=__woff;const ptrs=[];
+    const mv=new Uint8Array(__wasmMem.buffer);let off=__woff;const ptrs=[];
     for(let i=0;i<params.length;i++){const p=params[i],a=args[i];
       if(p.a&&a?.buffer){
-        if(a.buffer===mem.buffer){ptrs.push(a.byteOffset)}
+        if(a.buffer===__wasmMem.buffer){ptrs.push(a.byteOffset)}
         else{const ab=new Uint8Array(a.buffer,a.byteOffset,a.byteLength);off=(off+15)&~15;mv.set(ab,off);ptrs.push(off);off+=ab.length}
       } else ptrs.push(a)}
     const r=compute(...ptrs);off=__woff;
     for(let i=0;i<params.length;i++){const p=params[i],a=args[i];
       if(p.a&&a?.buffer){
-        if(a.buffer===mem.buffer) continue;
+        if(a.buffer===__wasmMem.buffer) continue;
         const ab=new Uint8Array(a.buffer,a.byteOffset,a.byteLength);off=(off+15)&~15;ab.set(mv.slice(off,off+ab.length));off+=ab.length}}
     return r};
 }})();
 `.trim()
 
-  return { code, results }
+  // Strip the temporary _exportName field before returning to caller.
+  const publicResults = results.map(({ _exportName: _, ...rest }) => rest)
+
+  return { code, results: publicResults }
 }

package/src/lang/emitters/js.ts

@@ -69,6 +69,10 @@ import {
 } from './js-tests'
 export { stripModuleSyntax, stripTjsPreamble } from './js-tests'
 import { generateWasmBootstrap } from './js-wasm'
+import {
+  rewriteBoolCoercion,
+  rewriteBoolCoercionInSource,
+} from '../bool-coercion'
 
 export interface TJSTranspileOptions {
   /** Filename for error messages */
@@ -97,6 +101,15 @@ export interface TJSTranspileOptions {
    * Used when tests depend on imported modules.
    */
   resolvedImports?: Record<string, string>
+  /**
+   * Optional ModuleLoader for cross-file `wasm function` composition (Phase 3
+   * of the wasm-library plan). When provided, `import { dot } from
+   * 'tjs-lang/linalg'`-style imports are resolved at transpile time and any
+   * matching `wasm function` declarations are composed into this file's
+   * consolidated WebAssembly.Module. When omitted, imports are preserved
+   * verbatim (default behavior — runtime resolves them).
+   */
+  moduleLoader?: any
 }
 
 /** Result of running tests at transpile time */
@@ -419,6 +432,19 @@ function generateInlineValidationCode(
   // 2. Type checks with proper error emission
   for (const [paramName, param] of params) {
     const path = `${pathPrefix}${funcName}.${paramName}`
+
+    // For array params: if the array contains a MonadicError, propagate
+    // the first one we find instead of failing the type check with
+    // "expected array, got X". This is the "errors propagate, not
+    // accumulate" rule — a function receiving an array of values where
+    // one is an error should surface that error, not say the array's
+    // shape is wrong.
+    if (param.type.kind === 'array') {
+      lines.push(
+        `if (Array.isArray(${paramName})) { for (const __i of ${paramName}) { if (__i instanceof Error && __i.path !== undefined) return __i } }`
+      )
+    }
+
     const typeCheck = generateTypeCheckExpr(paramName, param.type)
 
     if (typeCheck) {
@@ -436,6 +462,19 @@ function generateInlineValidationCode(
         )
       }
     }
+
+    // If the param is a function with declared shape (e.g. `fn = (x: 0) => 0`),
+    // wrap it so its arguments and return value are validated on every call.
+    // Skipped when shape is unspecified or contains non-simple kinds.
+    if (param.type.kind === 'function') {
+      const shapeCheck = generateFunctionShapeCheck(paramName, param.type, path)
+      if (shapeCheck) {
+        lines.push(shapeCheck)
+        // checkFnShape returns either the function unchanged or a
+        // MonadicError. Re-check Error propagation after the assignment.
+        lines.push(`if (${paramName} instanceof Error) return ${paramName};`)
+      }
+    }
   }
 
   if (lines.length === 0) return null
@@ -601,13 +640,19 @@ export function transpileToJS(
   } = parse(cleanSource, {
     filename,
     colonShorthand: true,
+    moduleLoader: options.moduleLoader,
   })
 
   // Find ALL functions in the program
   const functions = findAllFunctions(program)
 
   // Preprocess source (handles TJS syntax transformations)
-  const preprocessed = preprocess(cleanSource)
+  // Pass through the moduleLoader so Phase 3 cross-file wasm composition
+  // sees imported `wasm function` declarations.
+  const preprocessed = preprocess(cleanSource, {
+    moduleLoader: options.moduleLoader,
+    filename,
+  })
 
   // Apply the same source-level equality transforms to extracted test/mock
   // bodies so they observe the module's TJS semantics (e.g. structural ==).
@@ -618,12 +663,18 @@ export function transpileToJS(
     if (preprocessed.tjsModes.tjsEquals) {
       t.body = transformEqualityToStructural(t.body)
     }
+    if (preprocessed.tjsModes.tjsStandard) {
+      t.body = rewriteBoolCoercionInSource(t.body)
+    }
   }
   for (const m of mocks) {
     m.body = transformIsOperators(m.body)
     if (preprocessed.tjsModes.tjsEquals) {
       m.body = transformEqualityToStructural(m.body)
     }
+    if (preprocessed.tjsModes.tjsStandard) {
+      m.body = rewriteBoolCoercionInSource(m.body)
+    }
   }
 
   // Build types map for all functions
@@ -671,6 +722,41 @@ export function transpileToJS(
     warnings.push(...funcWarnings)
     allTypes[funcName] = types
 
+    // Cross-reference inference: when a parameter default is a bare
+    // identifier referring to a previously-declared TJS function, use that
+    // function's signature as the parameter's type. So
+    //
+    //   function strLength(s: ''): 0 { ... }
+    //   function map(arr: [''], counter = strLength) { ... }
+    //
+    // makes `counter`'s type `(s: string) => integer` (instead of `any`),
+    // which means the checkFnShape pass-time check fires when a wrong-
+    // shape callback is passed at the call site.
+    for (const param of func.params) {
+      if (
+        param.type === 'AssignmentPattern' &&
+        param.left.type === 'Identifier' &&
+        param.right.type === 'Identifier'
+      ) {
+        const localName = param.left.name
+        const refName = (param.right as any).name as string
+        const refInfo = allTypes[refName]
+        if (refInfo && types.params[localName]) {
+          const fnParams = Object.entries(refInfo.params).map(([n, p]) => ({
+            name: n,
+            type: p.type,
+          }))
+          const fnReturns =
+            (refInfo as any).returns ?? ({ kind: 'any' } as TypeDescriptor)
+          types.params[localName].type = {
+            kind: 'function',
+            params: fnParams,
+            returns: fnReturns,
+          }
+        }
+      }
+    }
+
     // Clean up param defaults in the emitted JS.
     // After colon→equals transform, `x: false | undefined` becomes
     // `x = false | undefined` in the parsed source.
@@ -780,6 +866,18 @@ export function transpileToJS(
     }
   }
 
+  // Boolean coercion rewrite (TjsStandard). Rewrites every truthiness
+  // context (`if`, `while`, `for`, `do/while`, `!`, `&&`, `||`, `?:`,
+  // and `Boolean(x)` calls) to call `__tjs.toBool` so boxed primitives
+  // unwrap before coercion. See src/lang/bool-coercion.ts.
+  if (preprocessed.tjsModes.tjsStandard) {
+    const boolPatches = rewriteBoolCoercion(program, preprocessed.source)
+    for (const p of boolPatches) {
+      deletions.push({ start: p.start, end: p.end })
+      insertions.push({ position: p.start, text: p.newText })
+    }
+  }
+
   // Apply deletions first (reverse order to maintain offsets), then insertions.
   // Deletions strip | union suffixes from param defaults in the output JS.
   deletions.sort((a, b) => b.start - a.start)
@@ -821,6 +919,8 @@ export function transpileToJS(
   const needsEnum = /\bEnum\(/.test(code)
   const needsUnion = /\bUnion\(/.test(code)
   const needsBang = code.includes('__tjs.bang(')
+  const needsToBool = code.includes('__tjs.toBool(')
+  const needsCheckFnShape = code.includes('__tjs.checkFnShape(')
   const needsSafeEval = preprocessed.tjsModes.tjsSafeEval
 
   const needsRuntime =
@@ -837,6 +937,8 @@ export function transpileToJS(
     needsEnum ||
     needsUnion ||
     needsBang ||
+    needsToBool ||
+    needsCheckFnShape ||
     needsSafeEval
 
   if (needsRuntime) {
@@ -913,6 +1015,28 @@ export function transpileToJS(
         `function Union(d,...v){const vals=v.flat();return{description:d,check:x=>vals.includes(x),values:vals,__runtimeType:true}}`
       )
     }
+    // toBool — honest truthiness (unwraps boxed primitives)
+    if (needsToBool) {
+      inlineParts.push(
+        `function toBool(v){if(v instanceof Boolean||v instanceof Number||v instanceof String)return Boolean(v.valueOf());return Boolean(v)}`
+      )
+    }
+
+    // checkFnShape — pass-time shape check for function-typed params
+    if (needsCheckFnShape) {
+      // checkFnShape depends on MonadicError; ensure it's inlined
+      if (!needsTypeError) {
+        inlineParts.push(
+          `class MonadicError extends Error{constructor(m,p,e,a,c,r){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c;this.reason=r}}`,
+          `function typeError(p,e,v,r){const a=v===null?'null':typeof v;const m=r?'Expected '+e+" for '"+p+"': "+r:'Expected '+e+" for '"+p+"', got "+a;const err=new MonadicError(m,p,e,a,undefined,r);const c=globalThis.__tjs?.getConfig?.();if(c?.logTypeErrors)console.error('[TJS TypeError] '+err.message);if(c?.throwTypeErrors)throw err;return err}`,
+          `function isMonadicError(v){return v instanceof Error&&v.name==='MonadicError'&&'path' in v}`
+        )
+      }
+      inlineParts.push(
+        `function checkFnShape(fn,expectedParams,expectedReturn,path){if(typeof fn!=='function')return fn;const meta=fn.__tjs;if(!meta||!meta.params)return fn;const entries=Object.entries(meta.params);for(let i=0;i<expectedParams.length;i++){const e=expectedParams[i];if(e==='any')continue;const a=entries[i];if(!a)continue;const ak=a[1]&&a[1].type&&a[1].type.kind;if(!ak||ak==='any')continue;if(ak!==e)return new MonadicError("Expected (...arg"+i+": "+e+", ...) for '"+path+"', but callback declares arg"+i+" as "+ak,path+"(arg"+i+")",e,ak)}if(expectedReturn!=='any'&&meta.returns){const ar=(meta.returns.type&&meta.returns.type.kind)||meta.returns.kind;if(ar&&ar!=='any'&&ar!==expectedReturn)return new MonadicError("Expected callback returning "+expectedReturn+" for '"+path+"', but callback returns "+ar,path+"(return)",expectedReturn,ar)}return fn}`
+      )
+    }
+
     // Bang access (!.) — asserted non-null member access
     if (needsBang) {
       // bang depends on typeError and isMonadicError — ensure they're inlined
@@ -947,6 +1071,11 @@ export function transpileToJS(
     if (needsFunctionPredicate) fallbackEntries.push('FunctionPredicate')
     if (needsEnum) fallbackEntries.push('Enum')
     if (needsUnion) fallbackEntries.push('Union')
+    if (needsToBool) fallbackEntries.push('toBool')
+    if (needsCheckFnShape) {
+      fallbackEntries.push('checkFnShape')
+      if (!needsTypeError) fallbackEntries.push('typeError', 'isMonadicError')
+    }
     if (needsBang) {
       fallbackEntries.push('bang')
       // Ensure typeError/isMonadicError are in fallback even if not otherwise needed
@@ -1289,13 +1418,33 @@ function generateTypeCheckExpr(
       return `${fieldPath} !== null` // nullable doesn't apply to null itself
     case 'undefined':
       return `${fieldPath} !== undefined`
-    case 'array':
-      check = `!Array.isArray(${fieldPath})`
+    case 'array': {
+      // Always require an Array. If item type is known and non-trivial,
+      // also validate every item — `arr: [0]` means "array of integers",
+      // not "any array". Without this, a function returning
+      // `[MonadicError, MonadicError]` would pass the `: [0]` return-
+      // type check (it's an array) and surface a confusing array-of-
+      // errors to the caller.
+      const itemCheck =
+        type.items && type.items.kind !== 'any'
+          ? generateTypeCheckExpr('__a', type.items)
+          : null
+      if (itemCheck) {
+        check = `(!Array.isArray(${fieldPath}) || ${fieldPath}.some(__a => ${itemCheck}))`
+      } else {
+        check = `!Array.isArray(${fieldPath})`
+      }
       break
+    }
     case 'object':
       // For nested objects, just check it's an object (deep validation is separate)
       check = `(typeof ${fieldPath} !== 'object' || ${fieldPath} === null || Array.isArray(${fieldPath}))`
       break
+    case 'function':
+      // Shape isn't validated at call time (we don't introspect arity or
+      // call the function with probes) — just check it IS callable.
+      check = `typeof ${fieldPath} !== 'function'`
+      break
     case 'union': {
       const checks = (type as any).members
         .map((m: TypeDescriptor) => generateTypeCheckExpr(fieldPath, m))
@@ -1321,6 +1470,52 @@ function generateTypeCheckExpr(
 // Alias for backward compatibility with other functions that use this
 const generateTypeCheck = generateTypeCheckExpr
 
+/** Kinds checkType can validate by string name (no RuntimeType needed). */
+const SIMPLE_KINDS = new Set([
+  'string',
+  'number',
+  'integer',
+  'non-negative-integer',
+  'boolean',
+  'function',
+  'any',
+  'undefined',
+  'null',
+  'object', // checkType handles this via typeof
+])
+
+/**
+ * Generate a `__tjs.checkFnShape(...)` call that validates a passed-in
+ * function's declared shape against the expected shape ONCE at pass time.
+ * On mismatch the param is reassigned to a MonadicError; the existing
+ * `if (param instanceof Error) return param` check above handles
+ * propagation. On match the param is unchanged. Untyped functions
+ * (no `__tjs` metadata — anonymous arrows) pass through unchanged.
+ *
+ * Returns null when the expected shape can't be represented as simple
+ * TypeSpec strings, or when there's nothing useful to check (all-`any`).
+ */
+function generateFunctionShapeCheck(
+  paramName: string,
+  type: TypeDescriptor,
+  path: string
+): string | null {
+  const fnParams = (type.params ?? []) as Array<{
+    name: string
+    type: TypeDescriptor
+  }>
+  const fnReturns = type.returns ?? { kind: 'any' as const }
+  const paramKinds = fnParams.map((p) => p.type?.kind)
+  const allSimple =
+    paramKinds.every((k) => k && SIMPLE_KINDS.has(k)) &&
+    SIMPLE_KINDS.has(fnReturns.kind)
+  const hasUsefulCheck =
+    paramKinds.some((k) => k !== 'any') || fnReturns.kind !== 'any'
+  if (!allSimple || !hasUsefulCheck) return null
+  const paramTypesJson = JSON.stringify(paramKinds)
+  return `if (typeof ${paramName} === 'function') ${paramName} = __tjs.checkFnShape(${paramName}, ${paramTypesJson}, '${fnReturns.kind}', '${path}');`
+}
+
 /**
  * Generate the complete function wrapper with inline validation
  *

package/src/lang/features.test.ts

@@ -1524,9 +1524,10 @@ function double(x: 0, y: 0) {
     expect(result.wasmCompiled?.[0].success).toBe(true)
     expect(result.wasmCompiled?.[0].byteLength).toBeGreaterThan(0)
 
-    // Output should contain base64-encoded WASM
-    expect(result.code).toContain('__wasmBlocks')
-    expect(result.code).toContain('b64:')
+    // Output should contain base64-encoded WASM. After Phase 0.5 consolidation
+    // the emitter ships one module per file and a per-export metadata table.
+    expect(result.code).toContain('__wasmExports')
+    expect(result.code).toContain('__wasmModuleB64')
 
     // Execute with async function to allow WASM instantiation
     const fn = new Function(

package/src/lang/index.ts

@@ -74,6 +74,15 @@ export {
   type FunctionTypeInfo,
   type ParamTypeInfo,
 } from './docs'
+export {
+  ModuleLoader,
+  inMemoryFileSystem,
+  type ModuleLoaderOptions,
+  type FileSystem,
+  type LoadedModule,
+  type ImportEntry,
+  type ExportEntry,
+} from './module-loader'
 export {
   extractTests,
   assertFunction,

package/src/lang/inference.ts

@@ -137,6 +137,31 @@ export function inferTypeFromValue(node: Expression): TypeDescriptor {
       return { kind: 'any' }
     }
 
+    case 'ArrowFunctionExpression':
+    case 'FunctionExpression': {
+      // Function example value (e.g. `fn = (x) => x` or `cb = function() {}`).
+      // Capture parameter names + types and (for concise arrow bodies)
+      // infer the return type from the body expression.
+      const fn = node as any
+      const params: Array<{ name: string; type: TypeDescriptor }> =
+        fn.params.map((p: any) => paramShape(p))
+
+      // Concise arrow body: body IS the return expression, so we can
+      // infer its type. Block bodies (function expressions, multi-line
+      // arrows) stay `any` — scanning return statements is a separate
+      // can of worms.
+      let returns: TypeDescriptor = { kind: 'any' }
+      if (
+        fn.type === 'ArrowFunctionExpression' &&
+        fn.body &&
+        fn.body.type !== 'BlockStatement'
+      ) {
+        returns = inferTypeFromValue(fn.body)
+      }
+
+      return { kind: 'function', params, returns }
+    }
+
     case 'UnaryExpression': {
       const op = (node as any).operator
       const arg = (node as any).argument
@@ -168,6 +193,35 @@ export function inferTypeFromValue(node: Expression): TypeDescriptor {
   }
 }
 
+/**
+ * Extract a function-parameter shape from a Pattern AST node. Used when
+ * we encounter a function/arrow EXAMPLE value and want to record what
+ * its declared parameters look like for documentation and .d.ts emit.
+ *
+ * Plain identifier (`x`)              → { name: 'x', type: any }
+ * Default value (`x = 0`)             → { name: 'x', type: integer }
+ * Rest (`...args`)                    → { name: '...args', type: array }
+ * Destructuring (`{a}`, `[x]`)        → name: '?', type: any (we'd need
+ *                                       to mirror parseParameter to do
+ *                                       this properly; not worth the
+ *                                       complexity for example values)
+ */
+function paramShape(p: any): { name: string; type: TypeDescriptor } {
+  if (p.type === 'Identifier') {
+    return { name: p.name, type: { kind: 'any' } }
+  }
+  if (p.type === 'AssignmentPattern' && p.left?.type === 'Identifier') {
+    return { name: p.left.name, type: inferTypeFromValue(p.right) }
+  }
+  if (p.type === 'RestElement' && p.argument?.type === 'Identifier') {
+    return {
+      name: `...${p.argument.name}`,
+      type: { kind: 'array', items: { kind: 'any' } },
+    }
+  }
+  return { name: '?', type: { kind: 'any' } }
+}
+
 /**
  * Parse a parameter and extract its type and default value
  *