jz 0.5.1 → 0.6.0

package/src/ctx.js

@@ -7,9 +7,13 @@
  * Refactored into focused sub-contexts for better maintainability.
  */
 
-import { DEFAULTS as ABI_DEFAULTS } from './abi/index.js'
+import { makeAbi } from './abi/index.js'
+export { HEAP, LAYOUT, PTR, ATOM, nanPrefixHex, atomNanHex, ssoBitI64Hex, sliceBitI64Hex, ptrNanHex, ptrBoxPrefixBigInt, encodePtrHi, decodePtrType, decodePtrAux, ATOM_HI, oobNanLiteral, oobNanIR, followForwardingWat } from '../layout.js'
 
 // === Carrier layout ===
+// Canonical bit layout lives in layout.js (compiler-free). Re-exported above for
+// backward-compatible `import { LAYOUT, PTR } from './ctx.js'`.
+//
 // i64 carrier holds either:
 //   - raw f64 number bits (any non-NaN-shape pattern), discriminated by
 //     `f64.eq(f, f)` — true for real numbers, false for NaN-shape pointers.
@@ -19,38 +23,6 @@ import { DEFAULTS as ABI_DEFAULTS } from './abi/index.js'
 // `${LAYOUT.TAG_SHIFT}` etc. so a layout change propagates by re-evaluation.
 // Hot dispatch (__ptr_type/__ptr_aux/__ptr_offset) keeps the inline expansion
 // for codegen size; those sites are commented as LAYOUT-tied.
-export const LAYOUT = {
-  TAG_SHIFT: 47,
-  TAG_MASK: 0xF,           // 4-bit tag (16 type slots)
-  AUX_SHIFT: 32,
-  AUX_MASK: 0x7FFF,        // 15-bit aux (schemaId, elemType, atomId, …)
-  OFFSET_MASK: 0xFFFFFFFF, // 32-bit offset (4GB heap)
-  NAN_PREFIX: 0x7FF8,      // top 13 bits of any NaN-shape pointer
-  NAN_PREFIX_BITS: 0x7FF8000000000000n, // pre-shifted for i64 OR
-  SSO_BIT: 0x4000,         // STRING aux bit 14: 1=inline (≤4 ASCII chars in offset), 0=heap
-  SLICE_BIT: 0x2000,       // STRING aux bit 13: 1=view (no length header — len in aux[12:0],
-                           //   offset points into a parent buffer), 0=own heap string.
-  SLICE_LEN_MASK: 0x1FFF,  // aux[12:0] — view length (≤8191; larger slices fall back to copy)
-}
-
-// === Tagged-pointer type codes ===
-// 4-bit tag (LAYOUT.TAG_MASK = 16 slots).
-// To retire a type, gate emission behind a feature flag and drop its dispatch
-// branches; to add, renumber with care — hardcoded branches in module/* must update.
-export const PTR = {
-  ATOM: 0,      // null, undefined, booleans, symbols (aux=atomId)
-  ARRAY: 1,     // heap-allocated arrays
-  BUFFER: 2,    // ArrayBuffer: [-8:byteLen][-4:byteCap][bytes]
-  TYPED: 3,     // TypedArrays (Float64Array, etc.)
-  STRING: 4,    // strings (heap or inline-SSO; aux bit LAYOUT.SSO_BIT distinguishes)
-  // 5: free
-  OBJECT: 6,    // plain objects
-  HASH: 7,      // dynamic objects (Map-like)
-  SET: 8,       // Set collections
-  MAP: 9,       // Map collections
-  CLOSURE: 10,  // first-class functions
-  EXTERNAL: 11, // JS host object refs (aux=0, offset→extMap index)
-}
 
 // === Global context with nested sub-contexts ===
 // Each namespace has a single lifecycle phase and clear ownership. Violating
@@ -62,21 +34,35 @@ export const PTR = {
 //   function — per function being lowered
 //   emit     — transient during a single AST→IR dispatch
 //
-// | Namespace | Phase    | Writers                   | Readers                    |
-// |-----------|----------|---------------------------|----------------------------|
-// | core      | compile  | reset, modules, inc()     | emit, compile, modules     |
-// | module    | compile  | prepare, index.js         | prepare, compile, emit     |
-// | scope     | compile  | analyze, compile          | compile, emit              |
-// | func      | function | compile                   | emit, modules              |
-// | types     | function | analyze                   | emit, modules              |
-// | schema    | compile  | prepare, analyze, compile | prepare, analyze, emit     |
-// | closure   | init     | modules (fn plugin)       | emit, compile              |
-// | runtime   | compile  | emit, modules             | emit, compile              |
-// | memory    | compile  | index.js                  | compile                    |
-// | error     | compile  | prepare, compile, emit    | err()                      |
-// | transform | compile  | index.js                  | prepare                    |
-// | features  | compile  | emit, modules, prepare    | compile (resolveIncludes), |
-// |           |          |                           | stdlib factories           |
+// | Namespace | Phase    | Writers                         | Readers                   |
+// |-----------|----------|---------------------------------|---------------------------|
+// | core      | compile  | reset, modules, inc(), emit*    | emit, compile, modules    |
+// | module    | compile  | prepare, index.js               | prepare, compile, emit    |
+// | scope     | compile  | analyze, compile, plan, modules | compile, emit             |
+// | func      | function | compile, narrow                 | emit, modules             |
+// | types     | function | analyze, plan                   | emit, modules             |
+// | schema    | compile  | prepare, analyze, compile       | prepare, analyze, emit    |
+// | closure   | init     | modules (fn plugin)             | emit, compile             |
+// | runtime   | compile  | emit, modules                   | emit, compile             |
+// | memory    | compile  | index.js                        | compile                   |
+// | error     | compile  | prepare, compile, emit          | err()                     |
+// | transform | compile  | index.js                        | prepare, compile, emit    |
+// | features  | compile  | emit, modules, prepare          | compile, stdlib factories |
+// | abi       | compile  | reset (makeAbi)                 | ir.js codegen, optimizer  |
+// | bridge    | compile  | reset (bridge.js)               | bridge.js → emit, modules |
+//
+// *emit's only `core` write is ctx.core.hostGlobals (a bare host-global reference),
+//  drained to env imports at compile (compile/index.js) — NOT to ctx.scope, so emit
+//  never writes scope. The stdlib module factories DO write ctx.scope.globals
+//  directly (core/string register __heap, __strBase, __tof_* there at compile phase).
+//
+// plan-phase writers (extending compile-phase): plan writes
+//   ctx.scope.{globalValTypes, globalTypedElem, globals, globalTypes} via
+//   inferModuleLetTypes / unboxConstTypedGlobals / inferModuleIntGlobals,
+//   and ctx.types.{dynKeyVars, anyDynKey} from collectProgramFacts results.
+// narrow-phase writers: narrowSignatures (under plan) temporarily swaps
+//   ctx.func.{localReps, locals, current} per-function with save/restore
+//   so per-call-site signature inference sees the right scope.
 export const ctx = {
   core: {},       // emitter table + stdlib registry (seeded by reset + modules)
   module: {},     // module graph: imports, resolved sources, module-init blocks
@@ -88,11 +74,22 @@ export const ctx = {
   runtime: {},    // runtime state: data segments, string pool, atom table, throws flag
   memory: {},     // module memory config (pages, shared)
   error: {},      // source location carried through emit for err() messages
-  transform: {},  // compile-time options (jzify, etc.)
+  transform: {},  // compile-time options + injected services. Three categories:
+                  //   user opts   : noTailCall, strict, alloc, importMetaUrl, host, inspect
+                  //   derived cfg : optimize (resolved by resolveOptimize from user input)
+                  //   services    : parse, resolveUrl, jzify (when set to a function by the
+                  //                 host pipeline; boolean form is a user opt). Service
+                  //                 injection is the pattern that lets the self-host kernel
+                  //                 run without a parser — it omits these and prepare uses
+                  //                 ctx.module.importAsts instead.
   abi: {},        // per-type rep lookup (see abi/index.js). { number: rep, string: rep, ... }
                   // Set by reset() to the default carrier bundle. Read by codegen sites
                   // that delegate rep-specific behavior — today just the optimizer's
                   // peephole hook; expanding as per-site narrowing tags individual sites.
+  bridge: {},     // emit/flat/wat dispatch, bound by reset() (see bridge.js). Lets every
+                  // module call emit() without importing the emitter — breaks the cycle.
+  features: {},   // codegen capability flags (external, sso, typedarray, …), reset() seeds
+                  // the defaults; see reset() for the field list and who flips each.
 }
 
 /** Create a child scope via shallow flat copy (metacircular-safe: no prototype chain).
@@ -102,6 +99,17 @@ export const derive = (parent) => ({ ...parent })
 /** Include stdlib names for emission. */
 export const inc = (...names) => names.forEach(n => ctx.core.includes.add(n))
 
+/** Declare a module global as a structured record — the single shape behind
+ *  every `ctx.scope.globals` entry:
+ *    { type: 'i32'|'i64'|'f64', mut: bool, init: number|string, export: string|null }
+ *  `init` is a number or a watr const literal (`-1`, `nan:0x…`, hex). Replaces
+ *  the old WAT-text strings: type queries are field reads, emission builds IR
+ *  directly (no parse-back), and `globalTypes` is set in the same move. */
+export const declGlobal = (name, type, init = 0, opts) => {
+  ctx.scope.globals.set(name, { type, mut: opts?.mut !== false, init, export: opts?.export ?? null })
+  ctx.scope.globalTypes.set(name, type)
+}
+
 /** Wrap an emit handler with a declarative stdlib-dependency list. The deps
  *  become data — exposed as `.deps` (tabulatable, analyzable) — and are `inc`'d
  *  on every call, while the body `fn` stays a pure `args → IR` builder (also
@@ -111,13 +119,27 @@ export const emitter = (deps, fn) => {
   const run = (...args) => (inc(...deps), fn(...args))
   run.deps = deps
   run.pure = fn
-  // Preserve the body's arity: `typeof Math.x` folding keys off emitter `.length`
-  // to tell callable builtins (sin) from constant ones (PI). The rest-param
-  // wrapper would otherwise report 0 for everything.
-  Object.defineProperty(run, 'length', { value: fn.length, configurable: true })
+  // Carry the body's parameter count as `.argc`: the rest-param wrapper above
+  // reports `.length` 0, so a handler's logical arity must travel as plain data
+  // (read back via `emitArity`, never the masked function `.length`). Two
+  // consumers need it — `typeof Math.x` folding (callable builtin vs constant)
+  // and the `.`-emit property/method split (arity-1 reads as a value; arity ≥2
+  // is call-only).
+  run.argc = fn.length
   return run
 }
 
+/** Logical arity of an emit handler: wrapped handlers (emitter/call/method/dual)
+ *  carry it as `.argc`; bare ones expose it as the function's own `.length`. */
+export const emitArity = (h) => h?.argc ?? h?.length
+
+/** Tag an emit handler as a property getter — it yields a value when the
+ *  property is *read* (`re.source`, `m.size`), so the `.`-read path may fire it.
+ *  Untagged handlers are methods: a bare read of `m.values` must not invoke them
+ *  (that would materialize a view instead of reading the `"values"` property);
+ *  they fire only from the method-call path. Apply outermost: `getter(emitter(…))`. */
+export const getter = (fn) => (fn.getter = true, fn)
+
 /** Expand ctx.core.includes transitively via ctx.core.stdlibDeps. Call before WASM assembly.
  *  Each module co-locates its own deps with its stdlib registrations at init time. */
 export function resolveIncludes() {
@@ -139,7 +161,8 @@ export function resolveIncludes() {
 }
 
 /** Reset all compilation state. Called once per jz() invocation. */
-export function reset(proto, globals) {
+export function reset(proto, globals, bridge) {
+  ctx.bridge = bridge
   ctx.core = {
     emit: derive(proto),
     stdlib: {},
@@ -152,6 +175,11 @@ export function reset(proto, globals) {
                             // Drained at module-assembly time into `(import "wasm:js-string" "name" …)`
                             // nodes; host wires JS-side polyfills via interop's
                             // env builder for engines without builtin support.
+    hostGlobals: new Set(), // host globals (globalThis/process/WebAssembly/…) referenced as
+                            // values. Recorded by emit on first use; drained into
+                            // `(import "env" "name" (global $name i64))` at assembly. Same
+                            // usage-gated pattern as jsstring — emit records, assembly owns
+                            // the ctx.module.imports write.
   }
 
 
@@ -159,6 +187,8 @@ export function reset(proto, globals) {
     imports: [],
     modules: {},
     importSources: null,
+    importAsts: null,   // self-host: pre-parsed [specifier, ast] pairs (the kernel can't parse).
+                        // Consulted by prepareModule before falling back to ctx.transform.parse(source).
     hostImports: null,
     hostImportValTypes: new Map(),
     resolvedModules: new Map(),
@@ -170,7 +200,7 @@ export function reset(proto, globals) {
 
   ctx.scope = {
     chain: derive(globals),
-    globals: new Map(),
+    globals: new Map(), // name → { type, mut, init, export } records (see declGlobal)
     userGlobals: new Set(),
     globalTypes: new Map(),
     globalValTypes: null,
@@ -190,6 +220,7 @@ export function reset(proto, globals) {
     localReps: null,
     refinements: new Map(),  // flow-sensitive: name → {val?: VAL.*, notString?: true} inside a type-guarded branch
     boxed: new Map(),
+    cellTypes: new Set(), // boxed vars whose CELL stores raw i32 (closure-capture narrowing)
     stack: [],
     uniq: 0,
     inTry: false,
@@ -201,6 +232,10 @@ export function reset(proto, globals) {
     // by the pass owners so re-entrant analyzeBody calls don't clobber each other.
     localValTypesOverlay: null,
     localTypedElemsOverlay: null,
+    _ccBody: null,      // memo key: body node last scanned by inBoundsCharCodeAt (src/type.js)
+    ccInBounds: null,   // memo value: Set of in-bounds charCodeAt callee nodes for _ccBody
+    _aiBody: null,      // memo key: body node last scanned by inBoundsArrIdx (src/type.js)
+    aiInBounds: null,   // memo value: Set of in-bounds "recv\0idx" array-read keys for _aiBody
   }
 
   ctx.types = {
@@ -212,6 +247,13 @@ export function reset(proto, globals) {
   ctx.schema = {
     list: [],
     vars: new Map(),
+    poisoned: new Set(),   // names whose assignments disagree on shape (literal +
+                           //   non-literal, or two different literals). A poisoned
+                           //   name never (re)binds in schema.vars: fixed-slot reads
+                           //   against ONE literal's layout would misread the other
+                           //   sources' objects. Populated by prepare's `=` handler;
+                           //   end-of-prepare state is what compile reads, so the
+                           //   conflict is order-insensitive.
     register: null,
     find: null,
     targetStack: [],
@@ -246,6 +288,14 @@ export function reset(proto, globals) {
     bodies: null,
     make: null,
     call: null,
+    numericReturn: null,  // Set<closureBodyName> proven to return a plain number — lets
+                          // callers skip the __to_num result coercion (function.js seeds it).
+    paramTypes: null,     // Map<closureBodyName, bool[]> — per-param "every direct call site
+                          // passed a number" lattice; emitClosureBody marks such params
+                          // VAL.NUMBER so their body uses skip __to_num (tryDirectClosureCall seeds).
+    minArgc: null,        // Map<closureBodyName, number> — fewest args any direct call passed.
+                          // A slot at index ≥ minArgc is omitted by some call (→ may be undefined),
+                          // so it must NOT be typed NUMBER, else `x === undefined` mis-folds to false.
   }
 
   ctx.runtime = {
@@ -258,6 +308,9 @@ export function reset(proto, globals) {
     throws: false,
     userThrows: false,  // user wrote `throw`/`try`/`catch`/`finally` — keep runtime declared
                         // even when all throws are dead-code-eliminated (JS-side ABI contract).
+    staticPtrSlots: null,  // [byteOffset] data-segment slots holding NaN-boxed ptrs (host relocates); lazy-init in ir.js
+    staticDataLen: 0,      // byte length of the address-0 static string block (seeded by module/number staticStr)
+    typeofStrs: null,      // [str] interned typeof result strings; lazy-init in module/core `typeof`
   }
 
   ctx.memory = {
@@ -294,6 +347,9 @@ export function reset(proto, globals) {
   // Shape: { abi, functions: { [name]: { exported, params, results, ptrKind?, locals, callerReps } }, schemas }.
   ctx.inspect = null
 
+  // Advisory sink. Populated when compile() receives opts.warnings.
+  ctx.warnings = null
+
   // Feature flags: capabilities the compiled module may exercise at runtime.
   // Set true by producer sites (import points, auto-imports, dynamic call sites).
   // Read by stdlib template factories and deps graph at resolveIncludes() time to
@@ -309,7 +365,7 @@ export function reset(proto, globals) {
   //   (b) a capability needs an opt-in A/B switch against the default path
   //       (SSO is the planned first user — default string-literal emission
   //       currently forces SSO for ≤4 ASCII chars at string.js:49)
-  ctx.abi = ABI_DEFAULTS
+  ctx.abi = makeAbi()
 
   // Only flags actually read by codegen live here. Hash/regex/json substrates
   // are pulled organically by inc(__*) — no flag mediates them, so no flag exists.
@@ -325,8 +381,67 @@ export function reset(proto, globals) {
   }
 }
 
+/** Debug-mode invariant checks. Encodes the writers/readers contract documented
+ *  above as runtime asserts so a bad refactor surfaces at the phase boundary
+ *  instead of as a distant nondeterministic failure. No-op unless
+ *  `JZ_DEBUG_INVARIANTS=1`; designed so phase-boundary callers can sprinkle
+ *  `assertCtxInvariants('post-prepare')` without runtime cost in production.
+ *
+ *  Phases checked:
+ *   - `post-reset`     : every sub-context exists; Maps/Sets initialized.
+ *   - `post-prepare`   : module + scope populated; func.list possibly empty.
+ *   - `pre-emit`       : func.current set; locals Map present; rep maps live.
+ *   - `post-compile`   : no transient temps leaked (func.uniq stable across calls). */
+const DBG_INVARIANTS = typeof process !== 'undefined' && process.env?.JZ_DEBUG_INVARIANTS === '1'
+export function assertCtxInvariants(phase) {
+  if (!DBG_INVARIANTS) return
+  const fail = msg => { throw new Error(`[ctx invariant] ${phase}: ${msg}`) }
+  const must = (cond, msg) => { if (!cond) fail(msg) }
+
+  must(ctx.core && ctx.module && ctx.scope && ctx.func && ctx.transform && ctx.features,
+       'sub-contexts present')
+  if (phase !== 'pre-reset') {
+    must(ctx.core.includes instanceof Set, 'core.includes is Set')
+    must(ctx.core.emit && typeof ctx.core.emit === 'object', 'core.emit table')
+    must(Array.isArray(ctx.func.list), 'func.list array')
+    must(ctx.func.locals instanceof Map, 'func.locals Map')
+    must(ctx.func.refinements instanceof Map, 'func.refinements Map')
+  }
+  if (phase === 'pre-emit') {
+    must(ctx.func.current, 'func.current set before emit')
+    must(ctx.func.locals.size != null, 'locals open for writes')
+  }
+}
+
+/** Enable compile-time advisories. Pass `opts.warnings` (mirrors `opts.profile`). */
+export function initWarnings(sink) {
+  if (sink == null) {
+    ctx.warnings = null
+    return
+  }
+  sink.entries ||= []
+  ctx.warnings = { sink, seen: new Set() }
+}
+
+/** Record one advisory; `loc` is a source byte offset used only to derive
+ *  line/column — it is never persisted on the entry. No-op unless
+ *  `initWarnings` wired a sink. */
+export function warn(code, message, meta = {}, loc = null) {
+  if (!ctx.warnings) return
+  const key = `${code}:${meta.fn || ''}:${meta.line || ''}`
+  if (ctx.warnings.seen.has(key)) return
+  ctx.warnings.seen.add(key)
+  const entry = { code, message, ...meta }
+  if (loc != null && ctx.error.src) {
+    const before = ctx.error.src.slice(0, loc)
+    entry.line = before.split('\n').length
+    entry.column = loc - before.lastIndexOf('\n')
+  }
+  ctx.warnings.sink.entries.push(entry)
+}
+
 /** Throw with source location context. */
-export function err(msg) {
+export function err(msg, cause) {
   let detail = msg
 
   if (ctx.error.loc != null && ctx.error.src) {
@@ -345,7 +460,10 @@ export function err(msg) {
     detail += `\n  current AST: ${formatErrorNode(ctx.error.node)}`
   }
 
-  const e = new Error(detail)
+  // Preserve the triggering error (if any) as the cause: when an internal jz bug
+  // is wrapped, the original stack — pointing at the actual codegen site — survives
+  // in the chain (`Error: …  [cause]: …`) instead of being replaced by this frame.
+  const e = cause !== undefined ? new Error(detail, { cause }) : new Error(detail)
   const stackLines = e.stack.split('\n')
   const firstFrame = stackLines.findIndex(line => line.trimStart().startsWith('at '))
   const frames = firstFrame >= 0 ? stackLines.slice(firstFrame) : stackLines.slice(1)