tjs-lang 0.8.0 → 0.8.2

package/dist/src/lang/core.d.ts

@@ -8,7 +8,7 @@ import type { SeqNode } from '../builder';
 import type { TranspileOptions, TranspileResult, FunctionSignature } from './types';
 import { type TJSTranspileResult, type TJSTranspileOptions } from './emitters/js';
 export * from './types';
-export { parse, preprocess, extractTDoc, validateSingleFunction, } from './parser';
+export { parse, preprocess, extractTDoc, validateSingleFunction, extractFunctions, } from './parser';
 export { transformFunction } from './emitters/ast';
 /**
  * Transpile JavaScript source code to Agent99 AST

package/dist/src/lang/dialect.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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';
+/**
+ * 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 declare function sourceKindForFilename(filename: string): SourceKind;
+/**
+ * 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 declare function dialectForFilename(filename: string): Dialect;

package/dist/src/lang/emitters/ast.d.ts

@@ -9,7 +9,7 @@ import type { TransformContext, TranspileOptions, FunctionSignature, TranspileWa
 /**
  * Transform a function declaration into Agent99 AST
  */
-export declare function transformFunction(func: FunctionDeclaration, source: string, returnTypeAnnotation: string | undefined, options?: TranspileOptions, requiredParamsFromPreprocess?: Set<string>): {
+export declare function transformFunction(func: FunctionDeclaration, source: string, returnTypeAnnotation: string | undefined, options?: TranspileOptions, requiredParamsFromPreprocess?: Set<string>, helpers?: Map<string, FunctionDeclaration>): {
     ast: BaseNode;
     signature: FunctionSignature;
     warnings: TranspileWarning[];

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

@@ -13,6 +13,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) */

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

@@ -1,7 +1,11 @@
 /**
  * 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 type { WasmBlock } from '../parser';
 export declare function generateWasmBootstrap(blocks: WasmBlock[]): {

package/dist/src/lang/emitters/js.d.ts

@@ -54,6 +54,18 @@ export interface TJSTranspileOptions {
     sourceMap?: boolean;
     /** Mode: 'dev' | 'strict' | 'production' */
     mode?: 'dev' | 'strict' | 'production';
+    /**
+     * Source dialect — what kind of source this string is:
+     * - `'tjs'` (default for a bare string): native TJS, footgun-removal modes ON
+     *   (structural `==`, `TjsStandard`, etc.).
+     * - `'js'`: plain JavaScript — modes OFF, `safety: 'none'`; the source's own
+     *   semantics are preserved (no `==`→`Eq`, no truthiness rewrite, no input
+     *   validation). Use this when feeding tjs() a vanilla `.js` string so it
+     *   transpiles without changing meaning. See PRINCIPLES.md (TJS ⊇ JS).
+     *
+     * For TypeScript, use the `fromTS` entry point (TS → TJS → JS).
+     */
+    dialect?: 'js' | 'tjs';
     /**
      * Test execution mode:
      * - true (default): run tests at transpile time, throw on failure
@@ -74,6 +86,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 */
 export type { TestResult } from './js-tests';

package/dist/src/lang/index.d.ts

@@ -23,7 +23,8 @@
 import type { SeqNode } from '../builder';
 import type { TranspileOptions, TranspileResult, FunctionSignature } from './types';
 export * from './types';
-export { parse, preprocess, extractTDoc } from './parser';
+export { parse, preprocess, extractTDoc, validateSingleFunction, extractFunctions, } from './parser';
+export { dialectForFilename, sourceKindForFilename, type Dialect, type SourceKind, } from './dialect';
 export { transformFunction } from './emitters/ast';
 export { transpileToJS, stripModuleSyntax, stripTjsPreamble, type TJSTranspileOptions, type TJSTranspileResult, type TJSTypeInfo, } from './emitters/js';
 export { generateDTS, typeDescriptorToTS, type GenerateDTSOptions, } from './emitters/dts';
@@ -34,6 +35,7 @@ export { typeDescriptorToJSONSchema, exampleToJSONSchema, functionMetaToJSONSche
 export { MetadataCache, getGlobalCache, setGlobalCache } from './metadata-cache';
 export { lint, type LintResult, type LintDiagnostic, type LintOptions, } from './linter';
 export { generateDocs, generateDocsMarkdown, type DocResult, type DocItem, 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, expectFunction, testUtils, type ExtractedTest, type ExtractedMock, type TestExtractionResult, } from './tests';
 export { runtime, installRuntime, isError, error, typeOf, checkType, validateArgs, wrap, emitRuntimeWrapper, TJS_VERSION, type TJSError, } from './runtime';
 export { compileToWasm, instantiateWasm, registerWasmBlock, compileWasmBlocks, type WasmCompileResult, } from './wasm';

package/dist/src/lang/module-loader.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Transpile-time module loader.
+ *
+ * Until now the transpiler has preserved import statements verbatim — runtime
+ * resolvers (the bun plugin, the playground service worker, the browser ESM
+ * loader) handle them on demand. That's the right default for regular JS
+ * interop, but Phase 3 of the wasm-library plan needs *static* visibility into
+ * imported sources: given `import { dot } from 'tjs-lang/linalg'`, we have to
+ * read linalg's source at transpile time so cross-file `wasm function`
+ * declarations can be composed into the consumer's wasm module.
+ *
+ * This loader is the foundation for that work. It's also useful as a building
+ * block for any future cross-file static analysis (type flow, dead code, etc.)
+ * — hence the name "module loader" rather than "wasm import resolver."
+ *
+ * Usage:
+ *   const loader = new ModuleLoader({ baseDir: '/path/to/project' })
+ *   const mod = loader.load('./math.tjs', '/path/to/project/app.tjs')
+ *   if (mod) { console.log(mod.exports) }
+ *
+ * Resolution rules (in order):
+ *   - URL specifiers (http://, https://, data:):   not loadable, returns null
+ *   - Relative paths (./foo, ../bar):               resolved against importer's dir
+ *   - Absolute paths (/foo/bar):                    used as-is
+ *   - Bare specifiers (foo, foo/bar):               walk up importer looking for
+ *                                                   node_modules/<spec>; also
+ *                                                   try bareSpecifierRoots
+ *
+ * For each candidate, we try extensions in order: `.tjs`, `.ts`, `.js`.
+ * (Index files: `<dir>/index.<ext>`.)
+ *
+ * The loader does NOT mutate transpiler behavior. It's an additive capability;
+ * Phase 3 (cross-file wasm composition) is the first caller.
+ */
+import { parse as parseTjs } from './parser';
+/** Pluggable filesystem hook. Default uses node:fs. */
+export interface FileSystem {
+    /** Return source text for an absolute path, or null if it doesn't exist. */
+    readFile(path: string): string | null;
+    /** Return true if the path exists and is a file. */
+    exists(path: string): boolean;
+}
+export interface ModuleLoaderOptions {
+    /** Filesystem hook (default: node:fs based) */
+    fs?: FileSystem;
+    /** Where to resolve bare specifiers from when no importer is given. */
+    baseDir?: string;
+    /**
+     * Extra roots tried for bare specifiers BEFORE the standard node_modules
+     * walk. Useful for monorepos or tests that want to point at a virtual
+     * package directory. Each root is treated as if it were a `node_modules/`.
+     */
+    bareSpecifierRoots?: string[];
+    /** Cache size cap. 0 disables caching. (default 256) */
+    cacheLimit?: number;
+}
+/** A single import / re-export specifier extracted from the AST */
+export interface ImportEntry {
+    /** Original module specifier (e.g. './math.tjs', 'tjs-lang/linalg') */
+    specifier: string;
+    /** Local name in the importing module */
+    local: string;
+    /** Imported name in the source module ('default' for default imports) */
+    imported: string;
+    /** True if this came from `import * as X` */
+    namespace: boolean;
+}
+/** A top-level export from a module */
+export interface ExportEntry {
+    /** Exported name (or 'default' for default exports) */
+    name: string;
+    /** Kind of declaration being exported */
+    kind: 'function' | 'class' | 'variable' | 're-export' | 'unknown';
+    /** For re-exports, the source specifier */
+    fromSpecifier?: string;
+}
+export interface LoadedModule {
+    /** Resolved absolute path */
+    path: string;
+    /** Original source text */
+    source: string;
+    /** AST + tjs preprocessing output (lazy — only computed once per module) */
+    parseResult: ReturnType<typeof parseTjs>;
+    /** Imports declared by this module */
+    imports: ImportEntry[];
+    /** Top-level exports */
+    exports: ExportEntry[];
+}
+export declare class ModuleLoader {
+    private cache;
+    private fs;
+    private baseDir;
+    private bareSpecifierRoots;
+    private cacheLimit;
+    constructor(options?: ModuleLoaderOptions);
+    /**
+     * Resolve a specifier to an absolute path. Returns null when the specifier
+     * is not loadable as a local TJS/TS/JS file (URLs, missing files, unknown
+     * bare specifiers all return null — the caller falls back to verbatim
+     * import preservation).
+     */
+    resolve(specifier: string, importerPath?: string): string | null;
+    /**
+     * Load a module by specifier. Returns null if not resolvable (caller treats
+     * this as "leave the import statement alone").
+     *
+     * Repeated calls with the same specifier+importer combination hit the cache.
+     */
+    load(specifier: string, importerPath?: string): LoadedModule | null;
+    /** Drop all cached modules. */
+    clearCache(): void;
+    /** Try each supported extension; return the first existing path or null. */
+    private tryExtensions;
+    /**
+     * Resolve a bare specifier (e.g. `tjs-lang/linalg`, `lodash`) by walking
+     * up the importer's directory tree looking for `node_modules/<spec>`.
+     * Also checks each configured `bareSpecifierRoots` entry first.
+     */
+    private resolveBare;
+}
+/**
+ * Helper for tests / advanced use: build a FileSystem from a plain
+ * `Map<string, string>`. Keys must be absolute paths.
+ */
+export declare function inMemoryFileSystem(files: Map<string, string> | Record<string, string>): FileSystem;

package/dist/src/lang/parser-transforms.d.ts

@@ -32,6 +32,85 @@ export declare function extractWasmBlocks(source: string): {
     source: string;
     blocks: WasmBlock[];
 };
+/**
+ * Extract top-level `wasm function NAME(params): RetType { body }` declarations.
+ *
+ * Unlike `extractWasmBlocks` (which finds `wasm { ... }` blocks nested inside
+ * regular tjs functions with auto-captured variables), this extractor finds
+ * top-level wasm function declarations with explicit parameters and an
+ * optional return type. The body is the wasm-subset source.
+ *
+ * Each declaration becomes a `WasmBlock` whose `captures` array holds the
+ * function's parameters with their type annotations (e.g. `['a: Float32Array',
+ * 'b: Float32Array', 'n: i32']`). The block ID is derived from the function
+ * name (`__tjs_wasm_<name>`), so the JS-side wrapper can reference it.
+ *
+ * The declaration is replaced in source with a regular JS function that
+ * forwards its args to the wasm export, preserving the `export` modifier
+ * if present:
+ *
+ *   (export)? wasm function dot(a: Float32Array, b: Float32Array, n: f64): f64 {
+ *     <wasm-source>
+ *   }
+ *
+ *   becomes:
+ *
+ *   (export)? function dot(a, b, n) { return globalThis.__tjs_wasm_dot(a, b, n) }
+ *
+ * This runs BEFORE `extractWasmBlocks` so its output (a regular JS function
+ * wrapper) isn't disturbed by the inline-block scanner.
+ *
+ * Return-type note: the underlying wasm bytecode builder currently emits f64
+ * or void return types only. The declared `: RetType` annotation is parsed
+ * and preserved on the block, but not yet validated against the backend's
+ * capabilities — `: f64` and omitted-return work today; other types (`: i32`,
+ * `: f32`, `: v128`) will be supported when the bytecode builder grows
+ * per-function return-type encoding.
+ */
+export declare function extractWasmFunctions(source: string): {
+    source: string;
+    blocks: WasmBlock[];
+};
+/**
+ * Phase 3: cross-file wasm-function composition.
+ *
+ * Scans the consumer's source for `import { name1, name2, ... } from 'spec'`
+ * statements. For each, resolves the spec via the supplied ModuleLoader; if
+ * the imported file is tjs/ts and one of the imported names corresponds to a
+ * `wasm function` declared there, the function's WasmBlock is pulled into the
+ * consumer's compilation and replaced in source by a local JS wrapper. The
+ * import statement is rewritten to remove the satisfied names (or removed
+ * entirely if every imported name was wasm-composed).
+ *
+ * This is the heart of the cross-file composition story: imported wasm
+ * functions become local functions in the consumer's single WebAssembly.Module
+ * (via the Phase 0.5 consolidated-module path). The library's transpiled .js
+ * is NOT involved — the source is consumed at transpile time.
+ *
+ * Caller is responsible for providing a configured ModuleLoader. When no
+ * loader is supplied (the common case before Phase 3 is fully wired up), this
+ * function returns the source unchanged with an empty blocks array.
+ *
+ * @param source the consumer's source (after extractWasmFunctions on its own
+ *               wasm functions, before transformParenExpressions)
+ * @param options.loader the ModuleLoader to resolve imports through
+ * @param options.importerPath the path of the file being transpiled (used as
+ *               the resolver's importer context); optional
+ * @returns updated source + the list of imported wasm function blocks
+ */
+export declare function composeImportedWasmFunctions(source: string, options: {
+    loader?: {
+        load(specifier: string, importerPath?: string): {
+            parseResult: {
+                wasmBlocks: WasmBlock[];
+            };
+        } | null;
+    };
+    importerPath?: string;
+}): {
+    source: string;
+    blocks: WasmBlock[];
+};
 /**
  * Transform Is/IsNot infix operators to function calls
  *

package/dist/src/lang/parser-types.d.ts

@@ -14,6 +14,28 @@ export interface ParseOptions {
      * When true, skips == to Is() transformation since the VM handles == correctly.
      */
     vmTarget?: boolean;
+    /**
+     * Source dialect — tells the transpiler what kind of source this string is:
+     * - `'tjs'`: native TJS, all footgun-removal modes ON (structural `==`,
+     *   `TjsStandard`, etc.). This is the default for a bare string.
+     * - `'js'`: plain JavaScript — modes OFF and `safety: 'none'`, so the source's
+     *   own semantics are preserved (no `==`→`Eq`, no truthiness rewrite, etc.).
+     *
+     * Authoritative when set; otherwise the dialect is inferred (the fromTS
+     * annotation and `vmTarget` ⇒ JS-compatible). See PRINCIPLES.md (TJS ⊇ JS).
+     */
+    dialect?: 'js' | 'tjs';
+    /**
+     * Optional ModuleLoader for cross-file `wasm function` composition (Phase 3).
+     * When provided, imports are resolved at transpile time and matching wasm
+     * functions are composed into the consumer's WebAssembly.Module. When
+     * omitted, imports are preserved verbatim (the default — runtime resolves
+     * them as before).
+     *
+     * Type is left as `any` here to avoid a circular import with module-loader.ts;
+     * callers should pass a `ModuleLoader` instance.
+     */
+    moduleLoader?: any;
 }
 /**
  * A WASM block extracted from source
@@ -35,6 +57,21 @@ export interface ParseOptions {
 export interface WasmBlock {
     /** Unique ID for this block */
     id: string;
+    /**
+     * Declared function name (only set for top-level `wasm function NAME(...)`
+     * declarations — Phase 1+). Used by Phase 3 cross-file composition to
+     * match an imported symbol against a wasm function declaration. Inline
+     * `wasm {}` blocks have no name and don't participate in composition.
+     */
+    name?: string;
+    /**
+     * Declared return-type annotation, e.g. `'f64'`. Only set for top-level
+     * `wasm function NAME(...): RetType` declarations; presence/absence is
+     * used to determine `hasReturn` BEFORE the body is compiled, so the
+     * function index map can be built up-front for wasm-to-wasm calls.
+     * Inline blocks have no declared return type.
+     */
+    returnType?: string;
     /** The body (JS subset that compiles to WASM, also used as fallback) */
     body: string;
     /** Explicit fallback body (only if different from body) */
@@ -79,6 +116,19 @@ export interface PreprocessOptions {
      * Default: false (transform == to Is() for TJS code running in regular JS)
      */
     vmTarget?: boolean;
+    /**
+     * Source dialect: `'js'` ⇒ modes OFF / `safety: 'none'` (preserve plain-JS
+     * semantics); `'tjs'` ⇒ native modes ON. Authoritative when set; otherwise
+     * inferred from the fromTS annotation / `vmTarget`. See ParseOptions.dialect.
+     */
+    dialect?: 'js' | 'tjs';
+    /**
+     * Optional ModuleLoader for cross-file `wasm function` composition (Phase 3).
+     * See ParseOptions.moduleLoader for details.
+     */
+    moduleLoader?: any;
+    /** Path of the file being preprocessed (used as importer context). */
+    filename?: string;
 }
 /**
  * Tokenizer state for tracking context during source transformation

package/dist/src/lang/parser.d.ts

@@ -53,6 +53,24 @@ export declare function parse(source: string, options?: ParseOptions): {
  * Validate that the source contains exactly one function declaration
  */
 export declare function validateSingleFunction(ast: Program, filename?: string): FunctionDeclaration;
+/**
+ * Extract top-level function declarations from the parsed program.
+ *
+ * Returns `{ entry, helpers }` where:
+ *   - `entry` is the last function declaration (the agent's entry point)
+ *   - `helpers` are all preceding function declarations, looked up by name
+ *
+ * This matches the natural "helpers first, agent last" pattern, including
+ * the TOOL_LIBRARY use case where helper async wrappers are prepended
+ * before the user-supplied agent function.
+ *
+ * Same top-level construct restrictions as `validateSingleFunction`:
+ * imports, exports, and classes are rejected.
+ */
+export declare function extractFunctions(ast: Program, filename?: string): {
+    entry: FunctionDeclaration;
+    helpers: Map<string, FunctionDeclaration>;
+};
 /**
  * Extract TDoc comment from before a function
  *

package/dist/src/lang/transpiler.d.ts

@@ -11,6 +11,7 @@
  */
 export { transpile, ajs, tjs, createAgent, getToolDefinitions } from './core';
 export { parse, preprocess, extractTDoc } from './parser';
+export { dialectForFilename, sourceKindForFilename, type Dialect, type SourceKind, } from './dialect';
 export { transformFunction } from './emitters/ast';
 export { transpileToJS } from './emitters/js';
 export type { TJSTranspileOptions, TJSTranspileResult, TJSTypeInfo, } from './emitters/js';

package/dist/src/lang/types.d.ts

@@ -143,6 +143,24 @@ export interface TransformContext {
     filename: string;
     /** Options */
     options: TranspileOptions;
+    /**
+     * Helper functions (top-level functions declared before the entry function).
+     * Calls to these names emit `callLocal` instead of treating them as atom calls.
+     */
+    helpers?: Map<string, any>;
+    /**
+     * Cache of transformed helper bodies. Lazily populated as helpers are
+     * referenced from the entry function (or from other helpers).
+     */
+    helperSteps?: Map<string, {
+        steps: any[];
+        paramNames: string[];
+    }>;
+    /**
+     * Names of helpers currently being transformed. Used to detect direct or
+     * transitive recursion.
+     */
+    helperTransforming?: Set<string>;
 }
 /** Create a child context for nested scopes */
 export declare function createChildContext(parent: TransformContext): TransformContext;

package/dist/src/lang/wasm.d.ts

@@ -15,6 +15,29 @@
  * audio processing, image manipulation, and physics simulations.
  */
 import type { WasmBlock } from './parser';
+/** TJS type that maps to WASM */
+type WasmValueType = 'i32' | 'i64' | 'f32' | 'f64' | 'v128';
+/** Parameter with type annotation */
+interface TypedParam {
+    name: string;
+    type: WasmValueType;
+    isArray?: boolean;
+    arrayType?: string;
+}
+/**
+ * Signature of a wasm function in the current module. Used to resolve
+ * cross-function calls (wasm-to-wasm `call <index>` instructions) without
+ * routing through JS. Populated by compileBlocksToModule before compiling
+ * any individual body, so forward references and mutual recursion work.
+ */
+export interface ModuleFunctionSig {
+    /** Function index in the composed module */
+    index: number;
+    /** Parameter types (used for arg-type checking + auto-conversion) */
+    params: TypedParam[];
+    /** Whether this function returns a value (f64) or is void */
+    hasReturn: boolean;
+}
 /** Compile result */
 export interface WasmCompileResult {
     /** The compiled WebAssembly module bytes */
@@ -31,9 +54,51 @@ export interface WasmCompileResult {
     wat?: string;
 }
 /**
- * Compile a WASM block to WebAssembly
+ * Compile a single WASM block to a complete WebAssembly module.
+ * The module exports a single function named `compute`.
  */
 export declare function compileToWasm(block: WasmBlock): WasmCompileResult;
+/** Per-export metadata produced by compileBlocksToModule */
+export interface BlockExport {
+    /** Original block ID (assigned by the parser) */
+    id: string;
+    /** Export name in the composed module (e.g. 'compute_0') */
+    exportName: string;
+    /** Capture annotations (preserved for runtime wrapper) */
+    captures: string[];
+    /** Whether this function reads/writes memory */
+    needsMemory: boolean;
+    /** WAT disassembly */
+    wat: string;
+}
+/** Result of composing multiple blocks into one module */
+export interface MultiBlockCompileResult {
+    /** The composed module bytes, or empty if all blocks failed */
+    bytes: Uint8Array;
+    /** Per-block compile status (preserves input order) */
+    results: {
+        id: string;
+        success: boolean;
+        error?: string;
+        /** Index into `exports` (only when success === true) */
+        exportIndex?: number;
+    }[];
+    /** Successfully-compiled exports (in module-index order) */
+    exports: BlockExport[];
+    /** True if any included function needs memory */
+    needsMemory: boolean;
+    /** Aggregated warnings from all blocks */
+    warnings: string[];
+}
+/**
+ * Compile N WASM blocks into a single WebAssembly module with N exports.
+ * Failed blocks are skipped (their slot in `results` records the error)
+ * but do not abort compilation of the rest.
+ *
+ * Exports are named `compute_0`, `compute_1`, ... in input order, skipping
+ * indices that correspond to failed blocks.
+ */
+export declare function compileBlocksToModule(blocks: WasmBlock[]): MultiBlockCompileResult;
 /**
  * Instantiate a compiled WASM module
  */
@@ -81,3 +146,4 @@ export declare function compileWasmBlocksForIframe(blocks: WasmBlock[]): Promise
  * This code should be injected into the iframe's script
  */
 export declare function generateWasmInstantiationCode(compiledBlocks: CompiledWasmData[]): string;
+export {};

package/dist/src/vm/runtime.d.ts

@@ -60,6 +60,8 @@ export interface TraceEvent {
 }
 /** Cost override: static number or dynamic function */
 export type CostOverride = number | ((input: any, ctx: RuntimeContext) => number);
+/** Timeout override: static number (ms) or dynamic function. 0 disables. */
+export type TimeoutOverride = number | ((input: any, ctx: RuntimeContext) => number);
 export interface RuntimeContext {
     fuel: {
         current: number;
@@ -76,8 +78,15 @@ export interface RuntimeContext {
     warnings?: string[];
     signal?: AbortSignal;
     costOverrides?: Record<string, CostOverride>;
+    timeoutOverrides?: Record<string, TimeoutOverride>;
     context?: Record<string, any>;
     runCodeDepth?: number;
+    localCall?: boolean;
+    helpers?: Record<string, {
+        steps: any[];
+        paramNames: string[];
+    }>;
+    callDepth?: number;
 }
 export type AtomExec = (step: any, ctx: RuntimeContext) => Promise<void>;
 export interface AtomDef {
@@ -218,6 +227,14 @@ export declare const varsImport: Atom<Record<string, any>, void>;
 export declare const varsLet: Atom<Record<string, any>, void>;
 export declare const varsExport: Atom<Record<string, any>, Record<string, any>>;
 export declare const scope: Atom<Record<string, any>, void>;
+/**
+ * Maximum helper-call nesting depth. Fuel + timeout bound the total *work* a
+ * recursive helper can do, but deeply-nested `await seq.exec` would overflow
+ * the host JS stack (an uncatchable RangeError) before fuel runs out. This cap
+ * converts runaway recursion into a clean monadic error instead.
+ */
+export declare const MAX_CALL_DEPTH = 256;
+export declare const callLocal: Atom<Record<string, any>, any>;
 export declare const map: Atom<Record<string, any>, any[]>;
 export declare const filter: Atom<Record<string, any>, any[]>;
 export declare const reduce: Atom<Record<string, any>, any>;
@@ -281,6 +298,7 @@ export declare const coreAtoms: {
     varsLet: Atom<Record<string, any>, void>;
     varsExport: Atom<Record<string, any>, Record<string, any>>;
     scope: Atom<Record<string, any>, void>;
+    callLocal: Atom<Record<string, any>, any>;
     map: Atom<Record<string, any>, any[]>;
     filter: Atom<Record<string, any>, any[]>;
     reduce: Atom<Record<string, any>, any>;

package/dist/src/vm/vm.d.ts

@@ -1,8 +1,21 @@
-import { type Atom, type Capabilities, type RunResult, type CostOverride, coreAtoms } from './runtime';
+import { type Atom, type Capabilities, type RunResult, type CostOverride, type TimeoutOverride, coreAtoms } from './runtime';
 import { type BaseNode, type BuilderType } from '../builder';
 export declare class AgentVM<M extends Record<string, Atom<any, any>>> {
     readonly atoms: typeof coreAtoms & M;
+    private _defaultRunTimeout?;
     constructor(customAtoms?: M);
+    /**
+     * Default run-level wall-clock timeout when `run()` is given no explicit
+     * `timeoutMs`. Derived as `max(per-atom timeoutMs) × 2` over the registered
+     * atoms (with headroom for an agent that chains a couple of slow calls), so
+     * the run-level backstop can never be shorter than the slowest single atom's
+     * own budget — otherwise that per-atom budget would be dead config (e.g.
+     * `llmVision`/`llmPredictBattery` are 120s; a fixed 60s run default would kill
+     * them mid-call). Atoms with `timeoutMs: 0` (no timeout, e.g. `seq`) are
+     * excluded; the result is floored at {@link MIN_DEFAULT_RUN_TIMEOUT_MS}.
+     * Self-adjusting: registering a slower custom atom raises the default.
+     */
+    get defaultRunTimeout(): number;
     get builder(): BuilderType<typeof coreAtoms & M>;
     get Agent(): BuilderType<typeof coreAtoms & M>;
     /** @deprecated Use `Agent` instead */
@@ -23,6 +36,7 @@ export declare class AgentVM<M extends Record<string, Atom<any, any>>> {
         timeoutMs?: number;
         signal?: AbortSignal;
         costOverrides?: Record<string, CostOverride>;
+        timeoutOverrides?: Record<string, TimeoutOverride>;
         context?: Record<string, any>;
     }): Promise<RunResult>;
 }