numbl 0.3.3 → 0.4.1

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

@@ -0,0 +1,93 @@
+/**
+ * JIT entry point that emits a single user-function specialization as
+ * a C module ready for `cc -shared -fPIC` and `dlopen`.
+ *
+ * Sibling of `compileSpec.ts` (the JS-emit JIT entry); shares the same
+ * `specializeUserFunction` flow + lowerer-cache contract. The output
+ * differs only in the emitted language: C instead of JS, with the
+ * entry spec marked `extern` so the host (numbl's koffi bridge) can
+ * resolve it after `dlopen`. Transitively-called specs stay `static`.
+ *
+ * Caller responsibilities:
+ *
+ * - **Strip `exact` before calling.** Same as `compileSpec` — runtime-
+ *   observed scalars should arrive as opaque-sign types so repeated
+ *   calls converge on a single spec instead of sharding by value.
+ *   `compileSpecC` runs `withoutExact` defensively.
+ * - **Treat lowering errors as JIT bailouts.** `UnsupportedConstruct`
+ *   and `TypeError` from the lowerer propagate to the caller as the
+ *   "decline this JIT proposal" signal.
+ *
+ * Returns a `signature` describing the C function the host needs to
+ * declare to koffi. The signature uses mtoc2 `Type` values directly —
+ * the host adapter translates each to a koffi type spec and assembles
+ * the prototype string.
+ */
+import type { Stmt } from "./parser/index.js";
+import type { Lowerer } from "./lowering/lower.js";
+import type { Workspace } from "./workspace/workspace.js";
+import { type Type } from "./lowering/types.js";
+type FuncStmt = Extract<Stmt, {
+    type: "Function";
+}>;
+/** Describes a single C parameter of the JIT-emitted entry spec. */
+export interface SpecCParam {
+    /** Identifier the C source uses for the param. */
+    readonly cName: string;
+    /** mtoc2 type — host translates to koffi type + marshals values. */
+    readonly ty: Type;
+}
+/** Describes a single C return slot of the JIT-emitted entry spec.
+ *  For `nargout === 1`: a single by-value return slot whose `cName` is
+ *  unused (the function uses C `return`).
+ *  For `nargout >= 2`: each output is appended as an out-pointer param
+ *  named `_mtoc2_o<i>` AFTER the user params — see `emitStmt.ts`
+ *  `fnParamList` for the convention.
+ *  For `nargout === 0`: no return slot. */
+export interface SpecCOutput {
+    readonly cName: string;
+    readonly ty: Type;
+}
+export interface SpecCSignature {
+    /** mtoc2-mangled C name of the entry function (the symbol koffi
+     *  resolves after `dlopen`). */
+    readonly cName: string;
+    /** Param shape, in the order the C function expects. */
+    readonly params: ReadonlyArray<SpecCParam>;
+    /** Output shape. Convention:
+     *   - 0 outputs ⇒ empty array; C return type is `void`.
+     *   - 1 output ⇒ single entry; C return type is `cTypeFor(out.ty)`.
+     *   - ≥2 outputs ⇒ N entries; C return type is `void`, the entries
+     *     describe the out-pointer params appended to the call. */
+    readonly outputs: ReadonlyArray<SpecCOutput>;
+}
+export interface CompileSpecCArgs {
+    /** Workspace whose files are pre-registered. Safe to share across
+     *  many `compileSpecC` calls — `Workspace.finalize()` is idempotent. */
+    workspace: Workspace;
+    /** Lowerer whose `.specializations` map persists across calls. */
+    lowerer: Lowerer;
+    /** The function AST to specialize. */
+    funcDecl: FuncStmt;
+    /** Argument types for this specialization. Caller should have
+     *  stripped `exact`; `compileSpecC` runs `withoutExact` again
+     *  defensively. */
+    argTypes: Type[];
+    /** Number of outputs the call site requests. Salts the spec key. */
+    nargout: number;
+}
+export interface CompileSpecCResult {
+    /** Mangled spec name. Same as `signature.cName`. */
+    cName: string;
+    /** Full C source — ready for `cc -shared -fPIC`. Includes all
+     *  activated runtime helpers + every spec in `lowerer.specializations`
+     *  (the entry spec references its transitive callees by their
+     *  mangled cNames). */
+    source: string;
+    /** Names of runtime snippets activated by emit. Diagnostic only. */
+    activatedSnippets: ReadonlyArray<string>;
+    /** Signature description so the host can build the koffi prototype. */
+    signature: SpecCSignature;
+}
+export declare function compileSpecC(args: CompileSpecCArgs): CompileSpecCResult;
+export {};

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

@@ -0,0 +1,15 @@
+/**
+ * Public surface of numbl's vendored JIT compiler. This is the single
+ * module the executor registry (`src/numbl-core/executors/jit/*`) imports
+ * from — it replaces the former cross-repo `src/numbl-core/mtoc2/index.ts`
+ * bridge. Everything the JIT exposes to the rest of numbl appears here
+ * exactly once.
+ */
+export { compileSpec, type CompileSpecArgs, type CompileSpecResult, } from "./compileSpec.js";
+export { compileSpecC, type CompileSpecCArgs, type CompileSpecCResult, type SpecCSignature, type SpecCParam, type SpecCOutput, } from "./compileSpecC.js";
+export { Workspace } from "./workspace/workspace.js";
+export type { WorkspaceFile } from "./workspace/workspace.js";
+export { Lowerer } from "./lowering/lower.js";
+export { UnsupportedConstruct, TypeError as JitTypeError, } from "./lowering/errors.js";
+export { scalarDouble, scalarComplex, scalarLogical, tensorDouble, tensorComplex, tensorDoubleFromDims, tensorComplexFromDims, withoutExact, isMultiElement, UNKNOWN, VOID, DIM_ONE, } from "./lowering/types.js";
+export type { Type, DimInfo, NumericType } from "./lowering/types.js";

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

@@ -0,0 +1,109 @@
+/**
+ * Class-definition registry. The `Workspace` walks each known
+ * `Stmt.ClassDef` (main file + every workspace file containing a
+ * classdef) and calls `registerClassDef` to validate and infer
+ * property types from the declared default expressions. Results are
+ * keyed by class name.
+ *
+ * Scope for v1:
+ *   - Single `classdef Foo properties ... methods ... end end`
+ *     blocks; no class attributes accepted.
+ *   - No inheritance (`< Parent`), no handle classes, no
+ *     `Events`/`Enumeration`/`Arguments` blocks, no operator
+ *     overloads, no `get.`/`set.` accessors. Every rejected form
+ *     surfaces with a clean `UnsupportedConstruct` carrying the
+ *     class's source span.
+ *   - Properties may declare a default-value expression. When set,
+ *     the default's type drives the property's storage type
+ *     eagerly. When unset, the property's type is inferred at first
+ *     constructor specialization from the first
+ *     `obj.<prop> = <rhs>` write at the top level of the
+ *     constructor body — see `Lowerer.resolveClassType` in
+ *     [lower.ts](./lower.ts). The C typedef hash uses
+ *     `cFieldTypeStr` (one C-type string per property), so the
+ *     typedef stays stable even if writes evolve the internal type.
+ *   - Methods can be the constructor (named same as class, returns
+ *     the receiver), an instance method, or a static method
+ *     (declared inside `methods (Static)` block). v1 only supports
+ *     methods with 0 or 1 outputs (same as user functions).
+ */
+import type { Stmt, Expr } from "../parser/index.js";
+import { type Type, type ClassType } from "./types.js";
+type ClassDefStmt = Extract<Stmt, {
+    type: "ClassDef";
+}>;
+type FuncStmt = Extract<Stmt, {
+    type: "Function";
+}>;
+export interface ClassRegistration {
+    /** Source-level name. */
+    className: string;
+    /** File the classdef lives in (used to salt specialization keys
+     *  and for diagnostics). */
+    file: string;
+    /** Declared property names in source order (sorted version lives on
+     *  `ty.properties` once resolved). */
+    propertyNames: string[];
+    /** Properties with an explicit default-value expression. Each
+     *  carries the lowered default's precise type (sign, exact, shape
+     *  preserved). The C typedef hash uses `cFieldTypeStr` so precision
+     *  differences across writes don't shard typedefs, but downstream
+     *  reads / spec keying benefit from precision. */
+    defaults: Map<string, {
+        expr: Expr;
+        ty: Type;
+    }>;
+    /** Properties WITHOUT a default. Their C-level type is inferred at
+     *  first constructor specialization from direct
+     *  `obj.<prop> = <rhs>` writes in the constructor body. Disjoint
+     *  from `defaults`. */
+    pendingProperties: Set<string>;
+    /** Class instance type. Eagerly resolved when every property has a
+     *  default (`pendingProperties` empty). Otherwise null at
+     *  registration and filled in by the lowerer's
+     *  `resolveClassType()` at first constructor specialization. */
+    ty: ClassType | null;
+    /** Constructor (a method whose name matches the class). May be
+     *  null when the class has no constructor — in that case the
+     *  default-valued receiver is the constructor's "body" and
+     *  `Foo()` (no args) is the only legal call. Required when
+     *  `pendingProperties` is non-empty. */
+    constructor: FuncStmt | null;
+    /** Instance methods, keyed by source name. The constructor is NOT
+     *  included here. Accessors (`get.X` / `set.X`) live in `getters`
+     *  / `setters` and are NOT in this map. */
+    methods: Map<string, FuncStmt>;
+    /** Static methods, keyed by source name. Called as
+     *  `ClassName.method(args)` — the receiver is not passed. */
+    staticMethods: Map<string, FuncStmt>;
+    /** `Dependent` properties — no per-instance storage. Reads route
+     *  through `getters.get(name)`; writes route through
+     *  `setters.get(name)` if a setter exists. Disjoint from
+     *  `pendingProperties` and `defaults`; included in `propertyNames`
+     *  for name-collision checks. */
+    dependentProperties: Set<string>;
+    /** Property getters declared as `function val = get.X(obj)`.
+     *  Keyed by the property name (without the `get.` prefix). v1
+     *  requires the property to be `Dependent`. */
+    getters: Map<string, FuncStmt>;
+    /** Property setters declared as `function obj = set.X(obj, val)`.
+     *  Keyed by the property name (without the `set.` prefix). v1
+     *  requires the property to be `Dependent`. */
+    setters: Map<string, FuncStmt>;
+}
+/** Validate one `classdef` AST and infer its property types. Throws
+ *  `UnsupportedConstruct` for any v1-unsupported form (inheritance,
+ *  class attributes, get/set accessors, events/enumeration/arguments
+ *  blocks, operator overloads, etc.). The `file` argument is stored
+ *  on the registration so cross-file specialization keys can salt by
+ *  it.
+ *
+ *  `externalMethods` carries instance methods discovered by numbl
+ *  in an `@ClassName/` folder — one `<methodName>.m` per file. Numbl's
+ *  `registerWorkspaceFiles` already collected them in
+ *  `ClassInfo.externalMethodFiles`; the `Workspace` finalizer extracts
+ *  each file's primary Function AST and passes them here so they
+ *  participate in the same validation and method-map as in-body
+ *  methods. */
+export declare function registerClassDef(s: ClassDefStmt, file: string, externalMethods?: ReadonlyMap<string, FuncStmt>): ClassRegistration;
+export {};

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

@@ -0,0 +1,35 @@
+/**
+ * mtoc2 lowering errors.
+ *
+ * Most errors carry a `Span` so the CLI can point at the offending
+ * source location. Builtin authors (whose `transfer`/`emit` hooks
+ * don't see a span) throw with `span` undefined; the framework
+ * backfills via `withSpan` at the call-site boundary.
+ */
+import type { Span } from "../parser/index.js";
+export declare class UnsupportedConstruct extends Error {
+    span?: Span;
+    constructor(message: string, span?: Span);
+}
+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
+ *  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/indexFold.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Compile-time index-fold helpers. Used by two sites that need to
+ * resolve a (statically-known shape, statically-known 1-based index
+ * tuple) pair to a column-major flat-buffer offset:
+ *
+ *   1. `foldedElemType` in `lowerIndexLoad.ts` — folds `v(i, j)` to a
+ *      scalar with exact data when the base is fully exact.
+ *   2. `tryRefreshExactAfterIndexedWrite` in `lower.ts` — refreshes the
+ *      base's exact carrier in place after a single-scalar `IndexStore`.
+ *
+ * Both need to map (shape, idxVals) → offset using mtoc's column-major
+ * stride convention, accept either linear single-index or full N-index
+ * forms, and bounds-check each axis. The shared helper keeps the two
+ * call sites consistent.
+ */
+/** Map an N-D shape and a 1-based index tuple to a column-major flat
+ *  offset, or `undefined` if the index is out-of-range or the tuple
+ *  shape doesn't match a supported form.
+ *
+ *  Supported forms:
+ *    - `idxVals.length === 1` (linear single-index): the lone index
+ *      addresses the flat buffer 1..numel. Out-of-range returns
+ *      `undefined`.
+ *    - `idxVals.length === shape.length` (full N-index): each slot
+ *      addresses its axis 1..shape[k]. Out-of-range on any axis
+ *      returns `undefined`.
+ *
+ *  Mixed forms (numSlots between 1 and shape.length, or numSlots >
+ *  shape.length) are not supported by the fold; the caller falls back
+ *  to a runtime read. */
+export declare function columnMajorOffsetFromIndices(shape: ReadonlyArray<number>, idxVals: ReadonlyArray<number>): number | undefined;

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

@@ -0,0 +1,100 @@
+/**
+ * Shared validation helper + slice-arg predicate for the four index
+ * lowering helpers (lowerIndexLoad / lowerIndexStore / lowerIndexSlice
+ * / lowerIndexSliceStore).
+ *
+ * `isSliceArg` lets the dispatchers in `lower.ts` choose between the
+ * scalar and slice paths without each call site re-discriminating on
+ * `Expr` kinds.
+ *
+ * `resolveIndexBase` performs the common preamble shared by all four
+ * helpers: env lookup, numeric/multi-element check, arity check,
+ * builds the base `Var` IR node.
+ *
+ * Adapted from mtoc's `src/lowering/indexResolve.ts`, with the
+ * char-tensor / complex / scalar-base branches dropped — mtoc2 v1
+ * only indexes real-double multi-element tensors.
+ */
+import type { Expr, LValue, Span } from "../parser/index.js";
+import type { IRExpr } from "./ir.js";
+import { type NumericType } from "./types.js";
+import type { Lowerer } from "./lower.js";
+/** Operation label that selects operation-specific message text. */
+export type IndexOperation = "read" | "write" | "sliceRead" | "sliceWrite";
+/** True when an AST expression node is a range or bare colon — the
+ *  dispatcher uses this predicate to decide between scalar (IndexLoad /
+ *  IndexStore) and slice (IndexSlice / IndexSliceStore) paths. */
+export declare function isSliceArg(a: Expr): boolean;
+interface ResolveOptions {
+    /** Span of the base identifier node — used for the Var IR node and
+     *  the "not in scope" diagnostic. Defaults to the outer index span. */
+    baseSpan?: Span;
+    /** "internal" when the dispatcher already verified the binding exists
+     *  (a missing one would be a lowerer bug); "user-facing" when the
+     *  caller is a statement-level dispatcher and the variable may
+     *  genuinely be undefined. */
+    notInScope: "internal" | "user-facing";
+    operation: IndexOperation;
+}
+/** Validate and resolve a member-rooted index lvalue like
+ *  `obj.field(i, j) = rhs`. Walks the Member chain to extract the
+ *  root Ident, the field path (outermost → innermost), and the leaf
+ *  field's NumericType; validates that the leaf is a multi-element
+ *  double tensor and that the index arity matches the leaf's ndim.
+ *
+ *  Returns the same shape as `resolveIndexBase` plus the field path
+ *  and leaf type, so the caller can build an `IndexStore` /
+ *  `IndexSliceStore` whose `base` Var still names the OWNING root
+ *  (struct / class instance) — the codegen path joins `base.cName`
+ *  with `fieldPath` to address the field slot. */
+export declare function resolveMemberRootedIndexBase(this: Lowerer, lvalue: Extract<LValue, {
+    type: "Index";
+}>, span: Span, operation: IndexOperation): {
+    rootVar: Extract<IRExpr, {
+        kind: "Var";
+    }>;
+    fieldPath: string[];
+    leafTy: NumericType;
+    slotCName: string;
+};
+/** Unified resolution result for an indexed-write lvalue base —
+ *  whether the lvalue's base is a bare `Ident` or a `Member` chain.
+ *
+ *  `base` always names the OWNING root variable (for liveness +
+ *  ANF book-keeping). `baseCName` is the slot path codegen targets
+ *  — equal to `base.cName` for bare-Ident, or `<root>.<field>...`
+ *  for member-rooted. `baseTy` is the leaf NumericType (the field's
+ *  type for member-rooted; identical to `base.ty` otherwise) so
+ *  the offset / complex-lane / arity checks downstream don't care
+ *  which form the LHS took. `fieldPath` / `leafTy` are populated
+ *  only in the member-rooted case so the caller can stamp them
+ *  onto the `IndexStore` / `IndexSliceStore` IR node. */
+export interface IndexLvalueBase {
+    base: Extract<IRExpr, {
+        kind: "Var";
+    }>;
+    baseTy: NumericType;
+    baseCName: string;
+    fieldPath?: string[];
+    leafTy?: NumericType;
+    /** Source-level display name for error messages — `name` for
+     *  bare-Ident bases, `root.f1.f2...` for member-rooted bases. */
+    displayName: string;
+}
+/** Resolve an indexed-write lvalue's base — either a bare `Ident`
+ *  or a `Member` chain — to the unified `IndexLvalueBase` shape.
+ *  Single chokepoint shared by `lowerIndexStore` and
+ *  `lowerIndexSliceStore` so the Ident-vs-Member dispatch lives in
+ *  one place. Rejects any other base kind with a clear error. */
+export declare function resolveIndexLvalueBase(this: Lowerer, lvalue: Extract<LValue, {
+    type: "Index";
+}>, span: Span, operation: IndexOperation): IndexLvalueBase;
+/** Validate and resolve the base variable for an index operation. */
+export declare function resolveIndexBase(this: Lowerer, name: string, argCount: number, span: Span, opts: ResolveOptions): {
+    baseTy: NumericType;
+    baseCName: string;
+    base: Extract<IRExpr, {
+        kind: "Var";
+    }>;
+};
+export {};