numbl 0.4.21 → 0.4.22

package/dist-lib/numbl-core/jit/lowering/definiteAssign.d.ts

@@ -36,7 +36,9 @@ import type { IRFunc } from "./ir.js";
  * lists the loop variable (and other loop-body locals) as pseudo-outputs
  * that are legitimately unassigned when the loop runs zero times, so the
  * check would over-decline every loop.
+ *
+ * Returns the names definitely assigned on the fall-through path.
  */
 export declare function assertDefiniteAssignment(fn: IRFunc, opts?: {
     checkOutputs: boolean;
-}): void;
+}): ReadonlySet<string>;

package/dist-lib/numbl-core/jit/lowering/errors.d.ts

@@ -1,5 +1,5 @@
 /**
- * mtoc2 lowering errors.
+ * JIT lowering errors.
  *
  * Most errors carry a `Span` so the CLI can point at the offending
  * source location. Builtin authors (whose `transfer`/`emit` hooks
@@ -15,21 +15,9 @@ export declare class TypeError extends Error {
     span?: Span;
     constructor(message: string, span?: Span);
 }
-/** Raised for ordinary user-facing runtime errors — things like
- *  "Undefined function or variable", "Too many output arguments", or
- *  "Output argument 'x' not assigned". Distinct from
- *  `UnsupportedConstruct` (which means "this language feature isn't
- *  implemented in mtoc2 yet"); using one for the other muddles the
- *  user-vs-tool signal. Mirrors numbl's `RuntimeError` so error class
- *  matches across the two runners. */
-export declare class RuntimeError extends Error {
-    span?: Span;
-    constructor(message: string, span?: Span);
-}
-/** Run `fn` and, if it throws an `UnsupportedConstruct`, `TypeError`,
- *  or `RuntimeError` with no span attached, backfill `span`. Used at
+/** Run `fn` and, if it throws an `UnsupportedConstruct` or `TypeError`
+ *  with no span attached, backfill `span`. Used at
  *  framework→builtin call boundaries so builtin authors can throw
  *  without carrying a span around in every signature. Pre-existing
  *  spans (from nested framework calls) are preserved. */
 export declare function withSpan<T>(span: Span, fn: () => T): T;
-export declare function formatError(e: UnsupportedConstruct | TypeError | RuntimeError, source: string): string;

package/dist-lib/numbl-core/jit/lowering/ir.d.ts

@@ -577,8 +577,6 @@ export interface IRFunc {
     span: Span;
 }
 export interface IRProgram {
-    /** Script-level top-level statements. */
-    topLevelStmts: IRStmt[];
     /** All specialized function definitions, keyed by their mangled cName. */
     functions: Map<string, IRFunc>;
 }

package/dist-lib/numbl-core/jit/lowering/lower.d.ts

@@ -31,19 +31,12 @@
  * vendored resolver. Anything outside that throws
  * `UnsupportedConstruct` with a span.
  */
-import type { AbstractSyntaxTree, Expr, Stmt, Span } from "../parser/index.js";
+import type { Expr, Stmt, Span } from "../parser/index.js";
 import { type Type, type NumericType } from "./types.js";
 import type { ClassRegistration } from "./classDefs.js";
 import type { Workspace } from "../workspace/workspace.js";
 import type { CallSite } from "../numbl/index.js";
-/** Hook for the `%!numbl:printtype` directive's compile-time output.
- *  Defaults to `console.error` (so emitted lines go to stderr and
- *  don't mix with the cross-runner's stdout comparison). Tests
- *  replace this with a capturing function. */
-export declare let printTypeSink: (line: string) => void;
-export declare function setPrintTypeSink(sink: (line: string) => void): void;
-export declare function resetPrintTypeSink(): void;
-import { type Assign, type IRExpr, type IRStmt, type IRFunc, type IRProgram } from "./ir.js";
+import { type Assign, type IRExpr, type IRStmt, type IRFunc } from "./ir.js";
 export interface EnvEntry {
     cName: string;
     ty: Type;
@@ -151,7 +144,6 @@ export declare class Lowerer {
      *  bridge's `fromExistingContext` mode — surfacing the error at
      *  the first actual use rather than at workspace finalize. */
     classReg(name: string): ClassRegistration | undefined;
-    lowerProgram(ast: AbstractSyntaxTree): IRProgram;
     lowerStmts(stmts: Stmt[]): IRStmt[];
     private lowerStmt;
     private lowerStmtInner;
@@ -172,8 +164,8 @@ export declare class Lowerer {
      *    once per function specialization. No IR node, no codegen
      *    interaction.
      *
-     *  Numbl ignores all three directives, so cross-runner output is
-     *  unaffected. */
+     *  The interpreter ignores all three directives, so program output
+     *  is unaffected. */
     private lowerDirective;
     /** Look up each name in `args` in the current env, snapshotting its
      *  `cName` and current `Type`. Throws `UnsupportedConstruct` with

package/dist-lib/numbl-core/jit/lowering/types.d.ts

@@ -290,8 +290,8 @@ export declare function cellUniform(dims: DimInfo[], elem: Type): CellType;
 /** The canonical "empty `[]` double tensor" slot type — what numbl
  *  initialises every fresh slot in `cell(n, m)` to
  *  (see `numbl/.../type-constructors.ts:442-469`). Shape is `[0, 0]`,
- *  no exact data, sign unknown. Mtoc2 reuses this exact representation
- *  so cross-runner displays of an unwritten slot match byte-for-byte. */
+ *  no exact data, sign unknown. The JIT reuses this exact representation
+ *  so displays of an unwritten slot match the interpreter byte-for-byte. */
 export declare function emptyDoubleTensorType(): NumericType;
 export declare function isNumeric(t: Type): t is NumericType;
 export declare function isVoid(t: Type): t is VoidType;
@@ -423,10 +423,6 @@ export declare function typeToString(t: Type): string;
 /** Stable string key used for the specialization-key hash. Includes
  *  exact when set, so each unique exact-value gets its own spec. */
 export declare function canonicalizeType(t: Type): string;
-/** True iff two types have the same canonical form. Convenience
- *  wrapper around `canonicalizeType` for callers that don't need the
- *  string key. */
-export declare function canonicalEq(a: Type, b: Type): boolean;
 /** Storage compatibility: do two types occupy the same C-level slot?
  *  This is COARSER than canonical equality — every multi-element
  *  tensor shares the same `mtoc2_tensor_t` storage regardless of
@@ -441,7 +437,6 @@ export declare function canonicalEq(a: Type, b: Type): boolean;
 export declare function storageEquivalent(a: Type, b: Type): boolean;
 /** FNV-1a 32-bit; matches the mangling scheme used in current mtoc. */
 export declare function hashType(s: string): string;
-export declare function specializationKey(argTypes: Type[]): string;
 /** Mangled C typedef name for a handle's capture shape. All no-capture
  *  handles share `mtoc2_handle_empty_t` regardless of target identity
  *  (the function dispatch is static — the struct is just a carrier).

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

@@ -1,7 +1,7 @@
 /**
  * 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
+ * `numbl-core/*` path the JIT depends on appears here
  * exactly once, so:
  *
  * - a numbl rename / move surfaces as a single tsc error in this file
@@ -9,22 +9,13 @@
  * - 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.
+ * `parser/index.ts` re-exports through this module.
  */
-export { parseMFile, SyntaxError, BinaryOperation, UnaryOperation, } from "../../parser/index.js";
+export { BinaryOperation, UnaryOperation } from "../../parser/index.js";
 export type { Span, Expr, Stmt, LValue, AbstractSyntaxTree, } from "../../parser/index.js";
-export { LoweringContext } from "../../lowering/loweringContext.js";
+export type { 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";
+export { PLOT_ALL_NAMES } from "../../plotting/dispatch.js";

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

@@ -1,12 +1,7 @@
 /**
- * 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.
+ * Parser re-exports for JIT consumers. The actual import from numbl
+ * lives in `../numbl/index.ts`; this module is the stable path the
+ * JIT's call sites import from.
  */
-export { parseMFile, SyntaxError, BinaryOperation, UnaryOperation, } from "../numbl/index.js";
+export { BinaryOperation, UnaryOperation } from "../numbl/index.js";
 export type { Span, Expr, Stmt, LValue, AbstractSyntaxTree, } from "../numbl/index.js";

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

@@ -1,43 +1,36 @@
 /**
  * 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
+ * Thin adapter over numbl's `LoweringContext`, shared with the
+ * interpreter. 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)`). The JIT translates the result back into
+ * its own narrow `ResolvedTarget` shape and fences off everything it
+ * doesn't support (private/, .numbl.js, ...) 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.
+ * The `Type → 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 { type LoweringContext, type CallSite } 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. */
+    /** Pre-parsed AST (shared with numbl's `fileASTCache`). */
     ast?: AbstractSyntaxTree;
 }
 /** Narrow shape mtoc2 cares about. The resolver may return additional
@@ -59,15 +52,6 @@ export type ResolvedTarget = {
      *  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`. */
@@ -86,112 +70,43 @@ export type ResolvedTarget = {
     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`). */
+    /** File source + AST, keyed by file name. This side map keeps
+     *  `source` retrievable for diagnostics (`offsetToLineCol`) and the
+     *  main file's AST for local-function resolution. */
     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;
+    /** Numbl resolution context, owned by the interpreter. Holds the
+     *  workspace registry (`filesByFuncName`, `classesByName`,
+     *  `localClassesByName`) and the `FunctionIndex` used by
+     *  `resolveFunction`. */
+    readonly 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. */
+     *  applying the JIT'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.
+    /** Classes that numbl knows about but `registerClassDef` rejected
+     *  (e.g. inheritance, unsupported attributes).
      *
      *  `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
+     *  the executor 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>);
+    private constructor();
     /** 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. */
+     *  files registered, and the function index built — because numbl's
+     *  interpreter has been driving the same context. The JIT runs its
+     *  own class-registry bookkeeping on top. */
     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. */
+    /** Build the class registry. 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
@@ -221,23 +136,4 @@ export declare class Workspace {
      *  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 };
+export {};

package/dist-lib/numbl-core/jitDeclineDiagnostics.d.ts

@@ -21,7 +21,7 @@ export interface JitDecline {
     message: string;
     /** Error class name: "UnsupportedConstruct" | "JitTypeError". */
     kind: string;
-    /** Which executor declined: "jit-top-level" | "jit-call" | "jit-loop". */
+    /** Which executor declined, e.g. "jit-loop" or "cjit-call". */
     where: string;
     /** Source position of the offending construct, when the thrown error
      *  carried one. Only used for diagnostics. */

package/dist-lib/numbl-core/jsUserFunctions.d.ts

@@ -1,8 +1,11 @@
 /**
  * Loader for .numbl.js user functions.
  *
- * Evaluates .numbl.js files that define IBuiltins via
- *   register({ resolve }).
+ * Evaluates .numbl.js files that define a function via
+ *   register(function (args, nargout) { ... })
+ * or register({ apply, help }). The older register({ resolve }) form, whose
+ * resolve(argTypes, nargout) returns { outputTypes, apply }, is still
+ * accepted.
  * Supports optional WASM and native shared library bindings via directives:
  *   // wasm: <name>
  *   // native: <name>
@@ -31,24 +34,19 @@ export interface LoadedJsUserFunction {
     name: string;
     fileName: string;
     builtin: IBuiltin;
+    /** Help text from `register({ help })`, printed by `help name`. */
+    help?: string;
 }
 /** Returns true if the file is a numbl JS user function file (`*.numbl.js`). */
 export declare function isNumblJsFile(fileName: string): boolean;
-/** Returns true if the file is an mtoc2-only user function file (`*.mtoc2.js`).
- *  Numbl recognizes the extension for workspace discovery + function-name
- *  resolution, but never executes the body — mtoc2's loader does that. */
-export declare function isMtoc2JsFile(fileName: string): boolean;
-/** Derive a function name from a `.mtoc2.js` workspace file path.
- *    "myadd.mtoc2.js"            → "myadd"
- *    "/path/to/myadd.mtoc2.js"   → "myadd" */
-export declare function funcNameFromMtoc2JsFile(fileName: string): string;
+export declare function setJsGpuHelper(helper: unknown): void;
 /**
  * Load .numbl.js user function files and return them as LoadedJsUserFunction
  * records. Each loaded record carries the function name, source file name,
  * and the IBuiltin object built from the file's `register()` call.
  *
- * Each .numbl.js file calls register({ resolve }) to define an
- * IBuiltin. resolve(argTypes, nargout) returns { outputTypes, apply } or null.
+ * Each .numbl.js file calls register() once; see builtinFromSpec for the
+ * accepted forms.
  *
  * A .numbl.js file can specify bindings via directives at the top of the file:
  *   // wasm: <name>    — load a WASM module (looked up by name in wasmFiles)

package/dist-lib/numbl-core/lowering/classInfo.d.ts

@@ -2,6 +2,8 @@
  * Class information types and extraction utilities.
  */
 import { type Expr, type Stmt } from "../parser/index.js";
+/** Built-in base classes that confer handle (reference) semantics. */
+export declare const HANDLE_BASE_CLASSES: Set<string>;
 /**
  * Metadata about a class definition.
  * The ctx field is typed as 'unknown' to avoid circular dependencies with LoweringContext.
@@ -12,7 +14,8 @@ export interface ClassInfo {
     qualifiedName: string;
     fileName: string;
     source: string;
-    superClass: string | null;
+    /** Direct superclasses in declaration order (`classdef A < B & C`). */
+    superClasses: string[];
     propertyNames: string[];
     propertyDefaults: Map<string, Expr>;
     methodNames: Set<string>;

package/dist-lib/numbl-core/lowering/loweringContext.d.ts

@@ -22,13 +22,7 @@ interface WorkspaceRegistry {
     jsUserFunctionsByName: Map<string, {
         fileName: string;
         builtin: IBuiltin;
-    }>;
-    /** mtoc2-only user functions (.mtoc2.js): functionName → { fileName, source }.
-     *  Numbl never executes these — the source text is stored for mtoc2's loader
-     *  to consume. Numbl's interpreter rejects calls to them with a clear error. */
-    mtoc2UserFunctionsByName: Map<string, {
-        fileName: string;
-        source: string;
+        help?: string;
     }>;
     /** Per-workspace-file lowering contexts (created on demand) */
     fileContexts: Map<string, LoweringContext>;
@@ -75,10 +69,6 @@ export interface FunctionIndex {
     workspaceFunctions: Set<string>;
     /** JS user functions (resolved at workspace-function priority, not builtin) */
     jsUserFunctions: Set<string>;
-    /** mtoc2-only user functions (.mtoc2.js). Resolved at workspace-function
-     *  priority, like jsUserFunctions. Numbl's interpreter rejects calls to
-     *  these; mtoc2 routes them through its own loader. */
-    mtoc2UserFunctions: Set<string>;
     /** Workspace classes (classdef files) */
     workspaceClasses: Set<string>;
     /** Local subfunctions per workspace file: primaryFuncName → Set<subfuncName> */
@@ -152,10 +142,7 @@ export declare class LoweringContext {
      * Also handles @ClassName class folders.
      *
      * `.m` files register as workspace functions / classes / private functions
-     * (the regular MATLAB-style discovery). `.mtoc2.js` files register as
-     * mtoc2-only user functions: numbl tracks the name so resolution sees
-     * them, but the body stays unparsed — mtoc2's loader evaluates them.
-     * `.mtoc2.js` files in `@ClassName/` are not yet supported.
+     * (the regular MATLAB-style discovery).
      */
     registerWorkspaceFiles(files: WorkspaceFile[]): void;
     isWorkspaceFunction(name: string): boolean;
@@ -165,14 +152,7 @@ export declare class LoweringContext {
      * Register a JS user function (.numbl.js) in the workspace registry.
      * Uses first-wins semantics so search-path priority is honored.
      */
-    registerJsUserFunction(funcName: string, fileName: string, builtin: IBuiltin): void;
-    /**
-     * Register an mtoc2-only user function (.mtoc2.js) in the workspace
-     * registry. Numbl stores the source text verbatim; mtoc2's loader
-     * evaluates it. Uses first-wins semantics so search-path priority is
-     * honored — same as `.numbl.js`.
-     */
-    registerMtoc2UserFunction(funcName: string, fileName: string, source: string): void;
+    registerJsUserFunction(funcName: string, fileName: string, builtin: IBuiltin, help?: string): void;
     /**
      * Get the effective directory for this context's file, used for
      * private function resolution. If the file is inside a private/ folder,
@@ -209,6 +189,18 @@ export declare class LoweringContext {
     isLocalClass(name: string): boolean;
     isClass(name: string): boolean;
     getClassInfo(name: string): ClassInfo | null;
+    /** Ancestors of a class in method-resolution order: depth-first, left to
+     *  right through each `<` list, each name once. Built-in bases such as
+     *  `handle` are included even though they have no ClassInfo; a built-in
+     *  handle mixin (e.g. `matlab.mixin.Copyable`) is followed by `handle`. */
+    superclassNames(info: ClassInfo): string[];
+    /** `superclassNames` by class name; empty for an unknown class. */
+    classAncestors(className: string): string[];
+    /** A class followed by its ancestors that have class definitions, in
+     *  method-resolution order. */
+    classLineage(info: ClassInfo): ClassInfo[];
+    /** True if the class derives from a handle base class. */
+    isHandleClass(info: ClassInfo): boolean;
     /** Check if a class (or any ancestor) has a given method. */
     classHasMethod(className: string, methodName: string): boolean;
     /** Check if a class (or any ancestor) has a given static method. */