numbl 0.4.18 → 0.4.19

package/dist-browser/numbl-core/executors/jit/callExecutor.d.ts

@@ -25,7 +25,10 @@
  * - **Loop-depth gate.** Declines when `interp.loopDepth > 0` so a
  *   hot loop iterating function calls doesn't pay per-call JIT
  *   propose / spec-cache overhead. Once an outer call is JIT'd, its
- *   loops run inside mtoc2's compiled code anyway.
+ *   loops run inside mtoc2's compiled code anyway. The gate lifts when
+ *   every enclosing loop was itself declined: nothing above will be
+ *   compiled then, and an expensive callee would otherwise run
+ *   interpreted all the way down (`Interpreter.jitDeclinedLoopDepth`).
  */
 import type { Executor } from "../types.js";
 import { type JitType } from "../../jitTypes.js";
@@ -40,6 +43,9 @@ interface JitCallData {
 }
 interface CompiledArtifact {
     readonly specFn: (...args: unknown[]) => unknown;
+    /** The spec's declared output types — needed to convert a returned
+     *  struct back (an untagged JS object otherwise). */
+    readonly outputTypes: ReadonlyArray<CompilerType>;
 }
 export declare const jitCallExecutor: Executor<JitCallData, CompiledArtifact | null>;
 export {};

package/dist-browser/numbl-core/executors/jit/loopExecutor.d.ts

@@ -9,13 +9,15 @@
  * that the synthetic body is a single-element `[loopStmt]` instead of
  * a whole script body.
  *
- * Loop-depth gate: only fires when `interp.loopDepth === 0`. A loop
- * dispatched while the interpreter is iterating an enclosing
- * loop-body would pay per-iter propose/cache overhead with no
- * speedup, because the *outer* loop is the natural JIT entry point
- * (it captures the inner loop's body and runs it natively in mtoc2-
- * emitted code). When the outer loop fires its own JIT, the inner
- * loop never reaches the interpreter dispatcher at all.
+ * Loop-depth gate: fires when `interp.loopDepth === 0`, or when every
+ * enclosing loop has been declined by the JIT. A loop dispatched while the
+ * interpreter iterates an enclosing loop-body would pay per-iter
+ * propose/cache overhead with no speedup, because the *outer* loop is the
+ * natural JIT entry point (it captures the inner loop's body and runs it
+ * natively in mtoc2-emitted code) — but that only holds when the outer loop
+ * actually compiles. If it declined, the interpreter is walking its body and
+ * this loop is the outermost thing still compilable, so the gate lifts
+ * (`Interpreter.jitDeclinedLoopDepth`).
  */
 import type { Executor } from "../types.js";
 import { type JitType } from "../../jitTypes.js";
@@ -36,6 +38,9 @@ interface JitLoopData {
 }
 interface CompiledArtifact {
     readonly specFn: (...args: unknown[]) => unknown;
+    /** The synthetic spec's output types, so a struct written back into the
+     *  env is rebuilt as a struct (the emitted value is an untagged object). */
+    readonly outputTypes: ReadonlyArray<CompilerType>;
 }
 export declare const jitLoopExecutor: Executor<JitLoopData, CompiledArtifact | null>;
 export {};

package/dist-browser/numbl-core/executors/jit/topLevelExecutor.d.ts

@@ -31,6 +31,9 @@ interface JitTopLevelData {
 interface CompiledArtifact {
     readonly specFn: (...args: unknown[]) => unknown;
     readonly nargout: number;
+    /** The synthetic spec's output types, so a struct written back into the
+     *  env is rebuilt as a struct (the emitted value is an untagged object). */
+    readonly outputTypes: ReadonlyArray<CompilerType>;
 }
 export declare const jitTopLevelExecutor: Executor<JitTopLevelData, CompiledArtifact | null>;
 export {};

package/dist-browser/numbl-core/executors/jit/valueAdapter.d.ts

@@ -43,8 +43,15 @@ import type { Type } from "../../jit/index.js";
  *      complex-typed body reads `.re`/`.im`, so a bare number must be
  *      boxed into `{re, im:0}`. */
 export declare function numblToJit(v: RuntimeValue, paramType?: Type): unknown;
-/** mtoc2 emit-JS return value → numbl RuntimeValue. */
-export declare function jitToNumbl(v: unknown): RuntimeValue;
+/** mtoc2 emit-JS return value → numbl RuntimeValue.
+ *
+ *  `retType` is the compiler type the spec declares for this output. It is
+ *  only consulted for plain untagged objects, which is how the emitted code
+ *  represents both a struct and a class instance — the value alone cannot
+ *  tell them apart, so a struct is only rebuilt when the type says Struct
+ *  and anything else untagged is rejected (the executor then bails and the
+ *  interpreter, which has full class semantics, re-runs the call). */
+export declare function jitToNumbl(v: unknown, retType?: Type): RuntimeValue;
 /** True if `e` is the grow-bail sentinel thrown by the emitted JS
  *  store helpers (`mtoc2_idx_*_grow_js` in `scalar_index.js`) — an
  *  indexed store whose index exceeds the runtime extent, which would

package/dist-browser/numbl-core/executors/registry.d.ts

@@ -110,6 +110,14 @@ export declare class Registry {
      *      pure overhead.
      */
     dispatch(siblings: readonly Stmt[], i: number, ctx: DispatchContext): DispatchResult;
+    /** Run one stmt on the AST interpreter.
+     *
+     *  When that stmt is a loop, the interpreter is about to walk its body,
+     *  which invalidates the "an enclosing loop will capture me" assumption
+     *  behind the executors' `loopDepth` gate. `jitDeclinedLoopDepth` records
+     *  that for the duration of the body so nested loops and calls can bid for
+     *  themselves instead of running interpreted all the way down. */
+    private interpretFallback;
     private runStmtCandidate;
     /** Cache lookup + compile-on-miss + run + bail handling. Returns
      *  the executor's success RunResult, or null when the candidate

package/dist-browser/numbl-core/interpreter/interpreter.d.ts

@@ -54,6 +54,17 @@ export declare class Interpreter {
      *  interpreter never sees them, so this gate only fires on calls
      *  that genuinely happen at the interpreter level inside a loop. */
     loopDepth: number;
+    /** @internal Number of those enclosing loops that the JIT *declined*, so
+     *  the interpreter is walking their bodies statement by statement. The
+     *  `loopDepth > 0` gate above assumes an enclosing loop will be compiled
+     *  and will swallow whatever is nested inside it; when that loop was
+     *  declined instead, the assumption is false and everything below it would
+     *  run interpreted however expensive it is. The executors therefore gate on
+     *  `loopDepth > 0 && jitDeclinedLoopDepth === 0`: still no per-iteration JIT
+     *  attempts underneath a loop that is about to be compiled, but a nested
+     *  loop or call under a declined one gets its own chance. Bumped by the
+     *  registry around the interpreter fallback for a loop stmt. */
+    jitDeclinedLoopDepth: number;
     /** @internal Number of enclosing conditional blocks (`if` / `switch` /
      *  `try`) whose bodies the interpreter is currently executing. Used by
      *  the loop classifier: when a loop is dispatched with `condBlockDepth >

package/dist-browser/numbl-core/jit/builtins/runtime/system/cscalar.d.ts

@@ -34,7 +34,7 @@ export function mtoc2_cpow(a: any, b: any): {
     im: number;
 };
 export function mtoc2_csqrt(z: any): {
-    re: number;
+    re: any;
     im: number;
 };
 export function mtoc2_cexp(z: any): {
@@ -42,15 +42,15 @@ export function mtoc2_cexp(z: any): {
     im: number;
 };
 export function mtoc2_clog(z: any): {
-    re: number;
+    re: any;
     im: number;
 };
 export function mtoc2_clog2(z: any): {
-    re: number;
+    re: any;
     im: number;
 };
 export function mtoc2_clog10(z: any): {
-    re: number;
+    re: any;
     im: number;
 };
 export function mtoc2_csin(z: any): {

package/dist-browser/numbl-core/jit/codegen/emitIndex.d.ts

@@ -38,7 +38,7 @@ export declare function emitNdScalarOffset(state: RuntimeState, indices: Readonl
  *  the precomputed source-index buffer). The caller is expected to
  *  emit these lines immediately after closing the slot iteration
  *  loops and before the GCC statement-expression's yield expression. */
-export declare function emitSliceSlotSetup(state: RuntimeState, lines: string[], indent: string, slotsTyped: ReadonlyArray<IndexSliceArg>, baseCName: string, cleanups?: string[]): string[];
+export declare function emitSliceSlotSetup(state: RuntimeState, lines: string[], indent: string, slotsTyped: ReadonlyArray<IndexSliceArg>, baseCName: string, cleanups?: string[], grow?: boolean): string[];
 /** Emit an `IndexSlice` as a C statement-expression-style block that
  *  allocates the result tensor, fills it, and evaluates to the result
  *  via a comma expression. The result is consumed at an owned consume

package/dist-browser/numbl-core/jit/compileSpec.d.ts

@@ -79,6 +79,10 @@ export interface CompileSpecResult {
     source: string;
     /** Names of runtime snippets activated by emit. Diagnostic only. */
     activatedSnippets: ReadonlyArray<string>;
+    /** The spec's output types, in order. The host needs them to convert
+     *  returned values back: a struct and a class instance are both plain
+     *  JS objects in the emitted code, so only the type says which is which. */
+    outputTypes: ReadonlyArray<Type>;
 }
 export declare function compileSpec(args: CompileSpecArgs): CompileSpecResult;
 export {};

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

@@ -225,6 +225,19 @@ export declare class Lowerer {
     recordAssignment(name: string, expr: IRExpr, span: Span): Assign;
     private lowerIf;
     private lowerElseChain;
+    /** MATLAB `switch` lowered to the equivalent if/elseif chain.
+     *
+     *  The subject is evaluated once — hoisted to a temp unless it is already a
+     *  plain variable — and each case label becomes an equality test against it:
+     *  `strcmp` for text, `==` for numbers. A `case {a, b}` list is the OR of
+     *  the individual tests. Everything after that is `lowerIf`'s problem, which
+     *  means switch inherits its branch-env merging and cond folding.
+     *
+     *  Declined (leaving the unit to the interpreter, as before this existed):
+     *  a subject that is neither a scalar number nor text, a label whose kind
+     *  does not match the subject's, and an empty `case {}`.
+     */
+    private lowerSwitch;
     private lowerWhile;
     private lowerFor;
     lowerExpr(e: Expr): IRExpr;

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

@@ -23,6 +23,12 @@ export interface JitDecline {
     kind: string;
     /** Which executor declined: "jit-top-level" | "jit-call" | "jit-loop". */
     where: string;
+    /** Source position of the offending construct, when the thrown error
+     *  carried one. Only used for diagnostics. */
+    at?: {
+        file: string;
+        start: number;
+    };
 }
 /** Record a swallowed JIT decline reason (called from executor catch blocks). */
 export declare function recordJitDecline(d: JitDecline): void;

package/dist-browser/numbl-core/version.d.ts

@@ -1,2 +1,2 @@
 /** Numbl version, used for JIT disk cache invalidation. */
-export declare const NUMBL_VERSION = "0.4.18";
+export declare const NUMBL_VERSION = "0.4.19";