numbl 0.3.3 → 0.4.1

package/dist-lib/numbl-core/jit/numbl/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Single intra-repo bridge module for everything the vendored JIT
+ * (`src/numbl-core/jit/*`) consumes from the rest of numbl-core. Every
+ * `numbl-core/*` (and `graphics/*`) path the JIT depends on appears here
+ * exactly once, so:
+ *
+ * - a numbl rename / move surfaces as a single tsc error in this file
+ *   rather than scattering across the vendored compiler's call sites;
+ * - the surface area between the JIT and the rest of numbl is visible at
+ *   a glance.
+ *
+ * Historically this was mtoc2's cross-repo bridge (resolving the sibling
+ * `../../../numbl/` checkout); after vendoring it resolves the same
+ * symbols through local `numbl-core` relative paths. `parser/index.ts`
+ * re-exports through this module so the vendored files' import shapes
+ * stay unchanged.
+ */
+export { parseMFile, SyntaxError, BinaryOperation, UnaryOperation, } from "../../parser/index.js";
+export type { Span, Expr, Stmt, LValue, AbstractSyntaxTree, } from "../../parser/index.js";
+export { LoweringContext } from "../../lowering/loweringContext.js";
+export { resolveFunction } from "../../functionResolve.js";
+export type { CallSite } from "../../runtime/runtimeHelpers.js";
+export type { ItemType } from "../../lowering/itemTypes.js";
+export type { ClassInfo } from "../../lowering/classInfo.js";
+export { PLOT_ALL_NAMES } from "../../runtime/plotBuiltinDispatch.js";
+export { dispatchPlotBuiltin, type PlotDispatchState, } from "../../runtime/plotBuiltinDispatch.js";
+export type { PlotInstruction } from "../../../graphics/types.js";
+export { allocFloat64Array } from "../../runtime/alloc.js";
+export { RTV } from "../../runtime/constructors.js";
+export type { RuntimeValue } from "../../runtime/types.js";

package/dist-lib/numbl-core/jit/parser/astUtils.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Small AST helpers consumed by both the lowerer and the interpreter.
+ * Pure functions over the numbl AST shape — no dependency on the
+ * lowering / runtime layers.
+ */
+import type { Expr, LValue } from "./index.js";
+/** Walk a member-chain rooted in an `Ident` and return the dotted
+ *  identifier (`pkg.fn`, `pkg.sub.fn`, `ClassName.staticMethod`).
+ *  Returns null if the chain bottoms out at something that isn't a
+ *  plain identifier (e.g. a function call result, a tensor literal).
+ *
+ *  Used to disambiguate package calls (`pkg.foo(x)` — dotted lookup)
+ *  from instance-method calls (`obj.method(x)` — receiver dispatch):
+ *  the qualified name is only meaningful when every segment in the
+ *  chain is a plain ident.
+ *
+ *  This helper says nothing about whether the dotted name *resolves*
+ *  to anything — that's the caller's job (consult the env / workspace
+ *  / class registry). It only structurally extracts the dotted form. */
+export declare function tryExtractDottedName(e: Expr): string | null;
+/** Walk a `Member`-chain Expr down to its root Ident. Returns
+ *  `{ root, fields }` (fields in outermost-to-innermost order) or
+ *  null when the chain ends at anything other than a bare Ident.
+ *
+ *  Shared by Member-rooted lvalue and index-base walkers so the
+ *  same loop isn't repeated across the lowerer / interpreter. */
+export declare function unwindMemberChain(e: Expr): {
+    root: Extract<Expr, {
+        type: "Ident";
+    }>;
+    fields: string[];
+} | null;
+/** LValue counterpart of `unwindMemberChain`: walk a `Member`
+ *  LValue chain down to its root Ident, returning the root name and
+ *  the full field path (including the outer Member's `name`). Returns
+ *  null when the chain ends at anything other than a bare Ident.
+ *
+ *  `LValue.Member` carries no span (unlike `Expr.Member`), so this
+ *  helper takes the LValue shape directly. */
+export declare function unwindMemberLvalue(lv: LValue): {
+    rootName: string;
+    fields: string[];
+} | null;

package/dist-lib/numbl-core/jit/parser/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parser re-exports for mtoc2 consumers. The actual cross-import to
+ * the sibling numbl checkout lives in `src/numbl/index.ts` — this
+ * module is the historic stable path used by ~25 call sites and
+ * preserves their import shape unchanged.
+ *
+ * Structural AST drift is caught at `tsc` time; semantic drift is
+ * caught by the cross-runner. The pinned numbl SHA lives in
+ * `NUMBL_VERSION`, which CI checks out against.
+ */
+export { parseMFile, SyntaxError, BinaryOperation, UnaryOperation, } from "../numbl/index.js";
+export type { Span, Expr, Stmt, LValue, AbstractSyntaxTree, } from "../numbl/index.js";

package/dist-lib/numbl-core/jit/parser/sourceLoc.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Source location helpers used by the parser. Inlined from numbl's
+ * runtime/error.ts so the parser has no cross-module dependencies.
+ */
+/** Compute 1-based line number from a character offset in source text. */
+export declare function offsetToLine(source: string, offset: number): number;
+/** Compute 1-based {line, column} from a character offset in source text.
+ *  Column counts UTF-16 code units, which matches what Monaco expects. */
+export declare function offsetToLineCol(source: string, offset: number): {
+    line: number;
+    column: number;
+};

package/dist-lib/numbl-core/jit/runtime/context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Host bag passed to `Builtin.call` for the interpreter backend.
+ *
+ * Mirrors nexl's `RuntimeContext`. Side-effecty builtins (`disp`,
+ * `fprintf`, `error`, plot dispatch, …) consult `helpers.write` to
+ * emit text. Pure builtins ignore the bag.
+ *
+ * `write` is the JS analogue of C's `printf`. The CLI provides one
+ * backed by `process.stdout.write`; the browser provides one that
+ * pushes lines to the console panel; future test runners provide
+ * one that captures into a buffer for byte-for-byte comparison.
+ *
+ * As the interpreter grows, additional hooks (`time`, `plot`,
+ * `error`, …) will join this bag. Adding a hook here is the
+ * single source of truth — every host supplies it.
+ */
+export interface RuntimeHelpers {
+    /** Append text to stdout. No implicit newline. */
+    write(s: string): void;
+}
+export interface RuntimeContext {
+    helpers: RuntimeHelpers;
+}

package/dist-lib/numbl-core/jit/runtime/inferType.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Map a runtime value back into a Type. Used by the interpreter to
+ * feed `argTypes` into a builtin's `transfer` (for validation) and
+ * `call` (for type-dispatched implementations) — so that the three
+ * hooks (`emitC`, `emitJs`, `call`) all branch on the same `argTypes`
+ * shape rather than reinventing dispatch per-backend.
+ */
+import { type Type } from "../lowering/types.js";
+import { type RuntimeValue } from "./value.js";
+export declare function inferTypeFromValue(v: RuntimeValue): Type;

package/dist-lib/numbl-core/jit/runtime/value.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Runtime value carrier for the interpreter backend. Mirrors nexl's
+ * `RuntimeValue` design: a discriminated-via-typeof union for the
+ * common cases plus tagged-object wrappers for the kinds JS can't
+ * distinguish natively.
+ *
+ * MVP scope (Phase 3): real-double scalars, booleans (logical),
+ * strings (double-quoted), chars (single-quoted), real-double tensors.
+ * Complex / structs / classes / handles / void / cells follow as the
+ * type lattice and interpreter coverage expand.
+ *
+ * Builtin `call` implementations narrow via `typeof` / `isTensor` /
+ * `isChar` and dispatch through the same `argTypes` shape that
+ * `emitC` / `emitJs` consume — keeping the three backends parallel.
+ */
+export type RuntimeValue = number | boolean | string | RuntimeTensor | RuntimeChar | RuntimeComplex | RuntimeStruct | RuntimeHandle;
+/** Function handle. Named handles (`@foo`) keep the source name and
+ *  dispatch via the interpreter's normal call-site resolution at the
+ *  call point. Anonymous handles (`@(p1, ...) body`) capture every
+ *  visible binding by value at the @-site and run `body` in a fresh
+ *  env when invoked. */
+export type RuntimeHandle = {
+    readonly mtoc2Handle: true;
+    readonly kind: "named";
+    readonly name: string;
+} | {
+    readonly mtoc2Handle: true;
+    readonly kind: "anon";
+    readonly params: ReadonlyArray<string>;
+    readonly body: unknown;
+    readonly captures: Readonly<Record<string, RuntimeValue>>;
+};
+/** Narrow a RuntimeValue to a function handle. */
+export declare function isHandleValue(v: RuntimeValue): v is RuntimeHandle;
+/** Struct/object — plain JS object whose keys are field names. The
+ *  c-aot path emits a typedef'd C struct; the JS path just uses a
+ *  bare object. Recurses through field values that may themselves be
+ *  any RuntimeValue (including nested structs). */
+export type RuntimeStruct = {
+    readonly [field: string]: RuntimeValue;
+};
+/** Real or complex double tensor. `data` is the real lane,
+ *  column-major to match numbl's `RuntimeTensor.data`. `imag` is the
+ *  imaginary lane (same length and orientation as `data`); absent for
+ *  real-only tensors. Mirrors the C representation's split-buffer
+ *  layout — codegen / interpreter dispatch on `imag !== undefined`
+ *  the way the C side dispatches on `imag != NULL`. The shape array
+ *  is owned by the value; do not mutate.
+ *
+ *  `isLogical` flags this tensor as the result of a logical operation
+ *  (`~`, `<`, `==`, `&&`, …) so downstream index-slot resolution can
+ *  treat it as a mask instead of an IndexVec — same role as numbl's
+ *  `_isLogical` on its RuntimeTensor. The flag is one-way (once set,
+ *  stays set across copies via the helper) and absent on numeric
+ *  tensors; helper sites that don't care leave it undefined. */
+export interface RuntimeTensor {
+    readonly mtoc2Tag: "tensor";
+    readonly shape: number[];
+    readonly data: Float64Array;
+    readonly imag?: Float64Array;
+    readonly isLogical?: boolean;
+}
+/** Single-quoted char-array (`'foo'`). Distinct from `"foo"` strings
+ *  because numbl treats them differently: `length('foo') === 3` but
+ *  `length("foo") === 1`. */
+export interface RuntimeChar {
+    readonly mtoc2Tag: "char";
+    readonly value: string;
+}
+/** Scalar complex value — JS-side analogue of the `mtoc2_complex_t`
+ *  struct in `cscalar.h`. The cscalar runtime helpers
+ *  (`mtoc2_cmake`, `mtoc2_creal`, etc.) consume and produce this
+ *  shape. We DON'T tag it the way tensor / char are tagged because
+ *  emitJs literals (`{re: 0, im: 1}`) and runtime calls produce the
+ *  bare object form — adding a tag would force every helper to
+ *  re-wrap. Use `isComplexValue` for narrowing. */
+export interface RuntimeComplex {
+    readonly re: number;
+    readonly im: number;
+}
+/** Narrow a RuntimeValue to a complex scalar. Matches the cscalar
+ *  helpers' `{re, im}` shape. */
+export declare function isComplexValue(v: RuntimeValue): v is RuntimeComplex;
+export declare function makeTensor(shape: number[], data: Float64Array): RuntimeTensor;
+/** Complex tensor with both lanes. `data` is the real lane, `imag`
+ *  the imaginary lane; both must have the same length and match the
+ *  product of `shape`. */
+export declare function makeComplexTensor(shape: number[], data: Float64Array, imag: Float64Array): RuntimeTensor;
+/** True iff this tensor carries an imaginary lane. */
+export declare function isComplexTensor(v: RuntimeTensor): boolean;
+export declare function makeChar(value: string): RuntimeChar;
+export declare function isTensor(v: RuntimeValue): v is RuntimeTensor;
+export declare function isChar(v: RuntimeValue): v is RuntimeChar;
+/** Materialize a scalar value as a plain JS number. Used by builtins
+ *  that need to treat scalar tensors and scalar numbers uniformly. */
+export declare function toScalarNumber(v: RuntimeValue): number;
+/** MATLAB-style truthiness — for `if` / `while` / `&&` / `||`.
+ *  Scalar non-zero, all-elements-non-zero for tensors, nonempty
+ *  text. The interpreter uses this; codegen relies on the matching
+ *  C-side `__nonzero` helpers. */
+export declare function isTruthy(v: RuntimeValue): boolean;

package/dist-lib/numbl-core/jit/workspace/driverPrologue.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Driver-script prologue extractor.
+ *
+ * mtoc2 accepts `addpath(<literal>, ...)` only as a leading sequence
+ * of top-level statements in the driver script. Each call is parsed
+ * into a list of directory arguments (literal strings only) plus an
+ * optional trailing `-begin` / `-end` flag.
+ *
+ * Two call sites:
+ *  - The CLI invokes the extractor before scanning the filesystem so
+ *    it knows which directories to fold into the workspace search
+ *    path.
+ *  - `translateProject` / the interpreter run path invoke it purely
+ *    to drop the prologue statements from the driver AST before
+ *    lowering / execution begins. The dirs are ignored there.
+ *
+ * The two calls are idempotent: same input AST → same dirs and
+ * remaining body, so it doesn't matter that they parse twice.
+ *
+ * Any `addpath` left in the AST (anywhere outside the leading prefix)
+ * still hits the `addpath` builtin's `transfer`, which errors with a
+ * span-attributed message. `rmpath` / `savepath` are always rejected
+ * by their own `transfer` hooks; the extractor never accepts them.
+ *
+ * Function-file auto-invoke: a driver whose body (after the prologue)
+ * contains only function/classdef definitions and no top-level
+ * statements is a "function file" — running it means calling its
+ * first function with zero arguments. The extractor appends a
+ * synthesized 0-arg call so every execution path (interpreter,
+ * js-aot, c-aot) treats it the same way. Mirrors numbl's
+ * `Interpreter.run` (interpreter.ts).
+ */
+import type { AbstractSyntaxTree, Stmt, Span } from "../parser/index.js";
+export interface AddPathDir {
+    /** Directory string as the user wrote it. Relative paths are NOT
+     *  resolved here; callers resolve against `process.cwd()`. */
+    dir: string;
+    /** Whether the directory inserts at the front of the addpath block
+     *  (default / `-begin`) or after the CLI `--path` dirs at the end
+     *  (`-end`). */
+    position: "begin" | "end";
+    /** Span of the originating `addpath(...)` call. */
+    span: Span;
+}
+export interface DriverPrologueOpts {
+    /** Set to `true` when a filesystem is available to resolve dirs
+     *  against (CLI). When `false` or omitted (web IDE, in-memory
+     *  translate, vitest), any leading `addpath` call is itself an
+     *  `UnsupportedConstruct`. */
+    allowAddpath?: boolean;
+}
+export interface DriverPrologueResult {
+    addpaths: AddPathDir[];
+    /** Top-level statements after the prologue. Suitable for direct
+     *  use with `Lowerer.lowerProgram` (via a shallow AST copy with
+     *  this `body`) or `Interpreter.runProgram`. */
+    remainingBody: Stmt[];
+}
+export declare function extractDriverPrologue(ast: AbstractSyntaxTree, opts?: DriverPrologueOpts): DriverPrologueResult;

package/dist-lib/numbl-core/jit/workspace/mtoc2UserFunctionLoader.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Loader for `.mtoc2.js` user functions.
+ *
+ * A `.mtoc2.js` file is plain JavaScript with no mtoc2 dependency.
+ * The loader evaluates it as a CommonJS-style module (`exports` and
+ * `module.exports` are the only injected names) and reads four
+ * exports to assemble a workspace-scoped `Builtin`:
+ *
+ *   exports.name      — string, must match the file's basename.
+ *   exports.transfer  — (argTypes, nargout) -> Type[]. Raw mtoc2 Type
+ *                       objects in, raw Type objects out. Throws
+ *                       `Error` on bad input.
+ *   exports.emit      — ({argsC, prefix, ...}) -> string. C expression
+ *                       for the call. Use `prefix` to name any private
+ *                       C helpers (kept collision-free across files).
+ *   exports.cBody     — ({prefix}) -> string. C source (helper
+ *                       function definitions) injected once per
+ *                       translation unit. Use the same `prefix` as
+ *                       `emit`.
+ *   exports.cHeaders? — string[] of additional `#include` lines to
+ *                       activate (optional).
+ *
+ * Prefix shape: `mtoc2_user_<safe_funcname>__<8hex>__` where the hex
+ * is the FNV-1a hash of the workspace-relative file path. Including
+ * the path in the hash makes the prefix unique across all `.mtoc2.js`
+ * files in the workspace, even if two files happen to define
+ * functions with overlapping internal names.
+ */
+import type { Builtin } from "../builtins/registry.js";
+/** Resolved sibling file: the relative path (used by the build to
+ *  pick a unique on-disk name) plus the file's text. */
+export interface ResolvedCSource {
+    /** Path as written by the user in `exports.cSources` (e.g.
+     *  `"impl.c"` or `"sub/helpers.h"`). */
+    relPath: string;
+    /** File text the build will write to disk. */
+    source: string;
+}
+/** Loader output: the assembled `Builtin` plus the user-supplied C
+ *  sibling files the framework needs to thread through to the build
+ *  pipeline. */
+export interface LoadedUserFunction {
+    builtin: Builtin;
+    cSources: ResolvedCSource[];
+}
+/** Evaluate a `.mtoc2.js` file and return its assembled `Builtin`
+ *  plus the user-supplied sibling C files (`cSources`).
+ *
+ *  - `fileName` — the .mtoc2.js's full path (used for diagnostics and
+ *    to resolve sibling paths).
+ *  - `expectedName` — what numbl's workspace registered the file
+ *    under (derived from the file's basename / package path); we
+ *    validate the user's `exports.name` matches so a typo / rename
+ *    surfaces here rather than at the first call site.
+ *  - `relPath` — workspace-relative path used for the prefix hash.
+ *  - `readSibling(p)` — given a path-key relative to the .mtoc2.js's
+ *    directory, return the sibling file's source text. Used to pull
+ *    `cSources` entries out of the workspace's file map (which is
+ *    the same regardless of CLI vs web IDE). Returns `undefined` if
+ *    the file is not in the workspace; the loader throws a clear
+ *    error pointing at the missing path. */
+export declare function loadMtoc2UserFunction(fileName: string, source: string, expectedName: string, relPath: string, readSibling: (siblingRelPath: string) => string | undefined): LoadedUserFunction;

package/dist-lib/numbl-core/jit/workspace/workspace.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Workspace + cross-file function dispatch.
+ *
+ * Thin adapter over numbl's vendored `LoweringContext` (see
+ * [../parser/index.ts](../parser/index.ts) for how mtoc2 imports
+ * numbl directly via sibling-relative paths). Numbl's
+ * `resolveFunction` is the source of truth for "which function does
+ * `foo(...)` refer to from this call site"; it implements MATLAB's
+ * precedence rules (local > workspace > builtin, plus class-method
+ * dispatch on `obj.method(args)` and `ClassName.method(args)`).
+ * mtoc2 translates the result back into its own narrow
+ * `ResolvedTarget` shape and fences off everything outside v1
+ * (private/, +pkg/ namespaces, .numbl.js, imports) with a clean
+ * `UnsupportedConstruct`.
+ *
+ * mtoc2's `MType → ItemType` adapter is intentionally lossy: the
+ * resolver inspects `kind === "ClassInstance"` (and only the
+ * `className` there); every other shape collapses to `Unknown`.
+ * That's all the resolver needs to apply class-method precedence.
+ */
+import type { AbstractSyntaxTree, Stmt, Span } from "../parser/index.js";
+import { LoweringContext, type CallSite, type ItemType } from "../numbl/index.js";
+import { UnsupportedConstruct } from "../lowering/errors.js";
+import type { Type } from "../lowering/types.js";
+import { type ClassRegistration } from "../lowering/classDefs.js";
+import type { Builtin } from "../builtins/registry.js";
+type FuncStmt = Extract<Stmt, {
+    type: "Function";
+}>;
+type ClassDefStmt = Extract<Stmt, {
+    type: "ClassDef";
+}>;
+export interface WorkspaceFile {
+    /** Absolute (or web-IDE-flat) file name used in error attribution
+     *  and in numbl's resolver. Numbl uses `fileToFuncName` to derive
+     *  bare workspace-function names from this. */
+    name: string;
+    source: string;
+    /** Pre-parsed AST. Set by `Workspace.addFile`; callers populate
+     *  it via `parseMFile` before registration. */
+    ast?: AbstractSyntaxTree;
+}
+/** Narrow shape mtoc2 cares about. The resolver may return additional
+ *  kinds (private, JS user functions, ...) — those are fenced off
+ *  here with `UnsupportedConstruct` so the diagnostic gets a span at
+ *  the call site. */
+export type ResolvedTarget = {
+    kind: "userFunction";
+    /** Source-level name (as written at the call site). */
+    name: string;
+    /** AST of the function definition. */
+    ast: FuncStmt;
+    /** Source file the function lives in. Used to salt
+     *  specialization mangling so two files defining a subfunction
+     *  with the same name get distinct C names. */
+    file: string;
+} | {
+    /** Numbl says this name resolves to a builtin. mtoc2 still
+     *  validates it against its own builtin registry. */
+    kind: "builtin";
+    name: string;
+} | {
+    /** A `.mtoc2.js` user function discovered in the workspace.
+     *  The evaluated `Builtin` lives in `Workspace.userBuiltins` —
+     *  fetch via `getUserBuiltin(name)` for both lowering and
+     *  codegen. The resolved-target carries the source-level name
+     *  (which the lowerer also uses as the emitted C call name). */
+    kind: "mtoc2UserFunction";
+    name: string;
+    file: string;
+} | {
+    /** `Foo(args)` — class constructor call. The class is looked
+     *  up in `Workspace.classes`. */
+    kind: "classConstructor";
+    className: string;
+} | {
+    /** Class method dispatch — covers `obj.method(args)`,
+     *  `method(obj, args)`, and `ClassName.staticMethod(args)`. */
+    kind: "classMethod";
+    className: string;
+    methodName: string;
+    /** When true the receiver is NOT passed as a C arg (a static
+     *  method called via `ClassName.method(args)` or via instance-
+     *  style `obj.staticMethod(args)`). When false the receiver is
+     *  the implicit first C arg. */
+    stripInstance: boolean;
+};
+export declare class Workspace {
+    /** File source + AST, keyed by file name. The AST cache is also
+     *  mirrored into the vendored LoweringContext, but this side map
+     *  keeps `source` retrievable for diagnostics
+     *  (`offsetToLineCol`). */
+    readonly files: Map<string, WorkspaceFile>;
+    /** The entry file (active file) — bare-name calls from sibling
+     *  files don't see its local functions. */
+    readonly mainFile: string;
+    /** Search paths used by the vendored resolver to compute relative
+     *  paths (and hence workspace-function names). For the CLI,
+     *  `[dirname(absoluteEntry)]`. For the web IDE (flat file names),
+     *  empty — the resolver treats every name as already-relative. */
+    readonly searchPaths: ReadonlyArray<string>;
+    /** Numbl resolution context. Holds the workspace registry
+     *  (`filesByFuncName`, `classesByName`, `localClassesByName`) and
+     *  the `FunctionIndex` used by `resolveFunction`. Settable so the
+     *  `fromExistingContext` JIT factory can replace the constructor-
+     *  built default with a caller-owned context. */
+    ctx: LoweringContext;
+    /** Resolved class registry — populated by `finalize()` by walking
+     *  every classdef numbl knows about (workspace + local) and
+     *  applying mtoc2's validation/property-type inference. */
+    classes: Map<string, ClassRegistration>;
+    /** Classes that numbl knows about but mtoc2's `registerClassDef`
+     *  rejected (e.g. inheritance, unsupported attributes). Only
+     *  populated in `fromExistingContext` (JIT bridge) mode — the
+     *  standalone path still fails finalize() on the first bad class.
+     *
+     *  `isClass(name)` returns `true` for these so call-site dispatch
+     *  doesn't get steered into a wrong code path (treating a class
+     *  reference as a function call). `requireClass(name)` re-throws
+     *  the saved `UnsupportedConstruct` at the actual use site, which
+     *  the JIT bridge catches as a decline and falls back to the
+     *  interpreter for that call. */
+    failedClassValidations: Map<string, UnsupportedConstruct>;
+    /** Workspace-scoped `Builtin` objects loaded from `.mtoc2.js` files.
+     *  Keyed by source-level function name (matches numbl's
+     *  `mtoc2UserFunctionsByName` keys). Populated lazily by `finalize`. */
+    private userBuiltins;
+    /** Sibling C/H files pulled in by `.mtoc2.js` user functions via
+     *  `exports.cSources`. Each entry carries the originating
+     *  `.mtoc2.js` function name (for namespacing in the build dir),
+     *  the file's relative path (as the user wrote it), and the file
+     *  text. Populated lazily by `finalize`; exposed via
+     *  `getUserCSources()` for the build pipeline. */
+    private userCSources;
+    private finalized;
+    /** Set by `fromExistingContext` to indicate that `this.ctx` was
+     *  populated by the caller (numbl's interpreter, in the JIT case)
+     *  and re-registering its local functions / classes / workspace
+     *  files in `finalize()` would duplicate work and possibly error.
+     *  The mtoc2-side phases (class registry, `.mtoc2.js` loader) still
+     *  run regardless — those are mtoc2-only bookkeeping. */
+    private skipCtxRegistration;
+    constructor(mainFile: string, searchPaths?: ReadonlyArray<string>);
+    /** Build a Workspace that wraps an existing `LoweringContext`. The
+     *  caller's `ctx` must already have file ASTs cached, local
+     *  functions and classes for the main file registered, workspace
+     *  files registered, and the function index built — typically
+     *  because a host runtime (e.g. numbl's interpreter) has been
+     *  driving the same context. Mtoc2 still runs its own class-registry
+     *  + `.mtoc2.js` loader bookkeeping on top.
+     *
+     *  Used by the numbl JIT bridge so a single `LoweringContext` is
+     *  shared between numbl's interpreter and mtoc2's JIT compile path
+     *  per session. */
+    static fromExistingContext(ctx: LoweringContext, mainFile: string, files: Iterable<WorkspaceFile>): Workspace;
+    /** Register a file by name.
+     *
+     *  - `.m` files require a pre-parsed `ast` (from `parseMFile`) so
+     *    numbl's resolver and mtoc2's lowerer share one cached AST per
+     *    file.
+     *  - `.mtoc2.js` files carry source text only; the workspace passes
+     *    the source to numbl's registry under the function's basename
+     *    and (later) evaluates the JS via `loadMtoc2UserFunctions`. No
+     *    AST is required. */
+    addFile(file: WorkspaceFile): void;
+    /** Build the function index + class registry. Call once after
+     *  every file has been added. Subsequent calls are no-ops. */
+    finalize(): void;
+    /** Compute the workspace-relative path for `absPath`. Used to hash
+     *  per-file C-namespace prefixes for `.mtoc2.js` user functions so
+     *  the same hash falls out regardless of where the project lives
+     *  on disk. Falls back to the bare basename when no search path
+     *  contains the file (web IDE, ad-hoc absolute path outside the
+     *  entry's directory). */
+    private workspaceRelativePath;
+    /** Look up an evaluated `.mtoc2.js` user function by source-level
+     *  name. Returns `undefined` if no such workspace user function
+     *  exists. Both the lowerer and codegen consult this — the former
+     *  to call `transfer`, the latter to call `emit`. */
+    getUserBuiltin(name: string): Builtin | undefined;
+    /** Sibling C/H files supplied by `.mtoc2.js` user functions via
+     *  `exports.cSources`. The build pipeline writes each file to a
+     *  per-owner subdirectory under the build root and adds `-I` for
+     *  that subdir; `.c` entries are compiled along with the main C,
+     *  `.h` entries just sit in the include path. Each entry's
+     *  `ownerHash` is the same FNV-1a hash that names the owner's
+     *  C-symbol prefix, so per-user-function subdirs stay collision-
+     *  free even if two files share a basename. */
+    getUserCSources(): ReadonlyArray<{
+        ownerFunc: string;
+        ownerHash: string;
+        relPath: string;
+        source: string;
+    }>;
+    /** Pull the primary Function AST from each `@ClassName/<methodName>.m`
+     *  external method file that numbl registered for `info`. Any other
+     *  top-level functions in the file are per-method-file local helpers
+     *  (numbl scopes them via `withMethodScope`); mtoc2 surfaces them
+     *  through the resolve path via `target.source.from === "classFile"`,
+     *  so we don't need to collect them here — only the primary needs to
+     *  join the class's method registry. Returns `undefined` when the
+     *  class has no external methods. */
+    private collectExternalMethods;
+    private spanFromClassFile;
+    /** Is `name` a registered class (workspace or local)? Used by the
+     *  lowerer to route `Foo(args)` to the constructor path and to
+     *  detect `ClassName.staticMethod(args)` against an Ident base. */
+    isClass(name: string): boolean;
+    /** Like `classes.get(name)`, but re-throws the saved
+     *  `UnsupportedConstruct` if the class was registered in
+     *  `failedClassValidations` (JIT bridge mode). Use this at sites
+     *  that would otherwise do `classes.get(name)!` and dereference
+     *  `undefined`. */
+    requireClass(name: string): ClassRegistration | undefined;
+    /** Resolve a call site to a single target. Wraps numbl's
+     *  `resolveFunction`, applies mtoc2-narrow validation, and routes
+     *  classMethod verdicts (instance + static) through one shape. */
+    resolve(name: string, argTypes: ReadonlyArray<Type>, callSite: CallSite, span: Span): ResolvedTarget | null;
+    /** Look up the source text of a file by its name. Used by the
+     *  lowerer's `printtype` directive to map a span offset to a
+     *  line/column in the right file. */
+    sourceOf(file: string): string | undefined;
+}
+/** Pre-parse a list of source files into `WorkspaceFile`s.
+ *
+ *  The `mainName` file's parse errors are propagated; for every other
+ *  file, parse errors are reported via `onWarn` and the file is
+ *  dropped from the result. This matches numbl, which warns and
+ *  skips workspace siblings that fail to parse so that a single bad
+ *  file in an `addpath`'d tree doesn't poison the whole run.
+ *
+ *  Files ending in `.mtoc2.js` skip MATLAB parsing — they're plain
+ *  JavaScript text that the workspace will hand to the mtoc2 user-
+ *  function loader later. Their `ast` field stays undefined. */
+export declare function parseFiles(files: ReadonlyArray<{
+    name: string;
+    source: string;
+}>, mainName?: string, onWarn?: (msg: string) => void): WorkspaceFile[];
+/** Adapter from mtoc2's `Type` to numbl's `ItemType`. The resolver
+ *  only reads `kind === "ClassInstance"` and `className` from there;
+ *  every other shape collapses to `Unknown`. */
+export declare function mtypeToItemType(t: Type): ItemType;
+export type { ClassDefStmt };