@mica-js/compiler 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DigitalEcho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,276 @@
-# Temporary Holding Version
+# @mica-js/compiler
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser-compatible TypeScript ESM compiler for validated `@mica-js/device-model`
+execution bodies. All `OperationIR` variants are emitted as direct JavaScript;
+there is no runtime IR dispatcher or dependency on the old IR or simulator.
+
+## API
+
+- `compileBody(region)` returns `(host, args?, reaction?) => Generator`.
+- `compileComputation(computation)` returns `(host) => unknown`. It synchronously
+  completes nested calls and rejects any yielded execution signal.
+- `compileBodyArtifact` and `compileComputationArtifact` additionally return the
+  executable, generated JavaScript source, captured constants, operation/source
+  positions, suspension/resume locations and conservative effect metadata.
+- `ExecutionHost`, `ExecutionSignal`, `ReactionFrame` and value helpers are exported.
+
+Inputs must have passed model validation, scope/effect checks and instance binding.
+The compiler does not replace model validation. Arbitrary names and literal values
+are captured as data; binary64 constants retain NaN, infinities and negative zero.
+Primitive constant pooling preserves signed zero, and known primitive equalities
+use direct strict comparisons. No effectful computation is reordered or eliminated.
+Generated bodies no longer reference their input IR.
+
+`compileBody(fn.body)(host, args)` needs no function parameter declarations at
+compile time. Each value parameter is initialized by its explicit
+`{ kind: 'parameter', index, result, type }` operation, which reads `args[index]`.
+Resource parameters instead use parameter references directly. Supply arguments in
+the declared positional order, retaining resource parameters in their positions.
+Argument count, resource category and value types are validated by the model/binder,
+not inferred or defaulted by the compiler.
+
+Native JavaScript generators preserve locals across suspension. Native branches,
+loops and labeled value regions preserve lazy evaluation and control flow. Calls
+use generator delegation; stop and redirect terminate the entire delegated path,
+even if a driver resumes after a terminal signal. Drivers should close the outer
+execution generator when receiving either terminal signal. Receive results are
+passed to `generator.next(value)`. A receive or waitUntil signal can be satisfied
+immediately by the driver without introducing a scheduling boundary. Ticks always
+yield, including zero; elapse(0) does not yield. waitUntil ends its instruction path.
+Time and redirect values are checked at the operation's execution position.
+
+Runtime values use `null` for none, enum member-name strings, frozen plain records,
+`Uint8Array` byte snapshots, plain sample objects and flat readonly intent branch
+arrays. Both constructed and constant bytes produce a fresh `Uint8Array` each time
+the operation executes. Byte constants capture frozen number-array seeds, never a
+mutable buffer reused across invocations. Typed arrays are immutable by execution
+contract: hosts must not mutate received values, must copy mutable boundary inputs
+and must provide SDK `ReadonlyBytes` wrappers at the external boundary.
+`host.resistor` supplies an intent branch array; intent combinations flatten these
+arrays without changing branches. Resource references are direct name strings or
+the corresponding `args[index]`. The host enforces memory, resistor, channel and
+resource ownership contracts.
+Equality is structural for records, bytes and samples, with strict numeric equality
+including NaN inequality and signed-zero equality. Strings index UTF-16 code units.
+Byte construction and indexing enforce range checks without coercion.
+
+Effect metadata is syntactic and includes all branches. Calls are conservatively
+marked as possibly reading/writing any resource, suspending, redirecting, stopping,
+reading time and consuming random state; resolve actual transitive effects through
+the validated model call graph. Position lines/columns refer to the exposed generated
+source (one-based), not the engine's surrounding Function wrapper. Resume locations
+are diagnostic metadata, not serializable generator frames.
+
+Compilation uses `new Function` once per body and requires a host CSP that permits
+dynamic JavaScript compilation. Generated execution itself requires no Node APIs.
+No asynchronous execution, scheduling or electrical solving is implemented here.
+
+## Bounded Direct JIT
+
+`compileDirectJit(instructions, binding)` optionally compiles an entire cached PC
+trace into one numeric-bank switch/loop. Each instruction supplies `pc`, `nextPc`
+and its already validated `body`. Unsupported instructions are omitted; an unknown
+or unsupported PC exits with `fallback` before changing that instruction's PC or
+performing any of its effects. The first occurrence of each PC owns lookup, even
+when unsupported. If nothing is supported, compilation returns `undefined`.
+Optional binding `blockedStates?: ReadonlySet<string>` and
+`blockedMemories?: ReadonlySet<string>` are compile-time write barriers. A write to
+any blocked name, including implicit PC assignment or a write in either `if`/`select`
+branch, excludes that complete instruction before any effect or PC change. Other
+cached PCs remain compilable, and excluded instructions contribute no resource
+metadata. Reading a blocked resource is still supported. No barrier Set lookups
+occur during execution. Recompile when membership changes; finish any old pending
+instruction with `stopAfterInstruction` before switching programs.
+
+`DirectJitBinding` supplies `states` and `memories` as `ReadonlyMap<string, number>`
+and an explicit `pc: { name, index }` matching the state bank. `DirectJitFrame` is
+runtime-owned reusable storage: `states: unknown[]`, `memories: Uint8Array[]`,
+`stateDirty: number[]`, `memoryDirty: number[]`, `time`, `due`, `resume`,
+`locals: unknown[]`, and optional `stopAfterInstruction`.
+Initialize `resume` to zero and allocate `locals` with `program.localCount` slots.
+Allocate dirty arrays with `Math.ceil(bank.length / 32)` words and clear both arrays
+before each `run` invocation. Each completed write sets its resource's bit using
+`dirty[index >>> 5] |= 1 << (index & 31)`, including implicit and redirected PC writes.
+Bits are set after validation and the write; reads and failed writes do not set bits.
+Nonzero resume IDs and saved locals belong to the producing program; never transfer
+an outstanding continuation to a newly compiled program. `due` is an absolute wake
+time. Times and durations use integer picoseconds in the existing time range.
+
+`program.run(frame, deadline)` returns `deadline`, `fallback`, `stopped`, or
+`invalidated`. It executes multiple instructions without generators, per-instruction
+objects, host callbacks, or runtime Map lookups. Scalar intermediates stay in native
+locals until a horizon requires saving them. State/memory effects accumulate in the
+supplied reusable banks; the runtime must commit/invalidate only resources marked
+in the current invocation's dirty words in `finally`, including when execution
+throws. Conservative resource lists are eligibility guards, not flush lists: a
+resumed suffix must not republish a prefix write after an external event.
+Memory addressing and store values follow the
+generic host's safe-integer checks; `store8` uses Uint8Array wrapping semantics.
+
+The supported subset includes number/bool constants, state reads/writes, scalar
+unary/binary arithmetic, bitwise operations, comparisons, numeric builtins, mutable
+scalar locals, static-memory `load8`/`store8` with checked dynamic numeric offsets,
+scalar `select`/`if` regions with value yields,
+and one positive constant `elapse` per instruction. Numeric suffixes may run after
+the elapse, including a captured load's delayed register write and optional `stop`.
+Alternatively a terminal redirect accepts a dynamic finite numeric target with a
+positive constant delay; the target PC is written before time advances. A terminal
+standalone stop is supported. Other control flow, resource parameters, non-state
+reads, dynamic durations, multiple delays, calls, and other host operations fall
+back as complete instructions, never after partially running an unsupported body.
+
+Before a body starts, PC is set to `nextPc`. A horizon can split any elapse without
+replaying prefix effects or rereading captured loads. At `time === deadline`, no
+instruction starts and no continuation or post-elapse suffix executes. Absolute
+due times beyond `7200000000000000` throw after preserving completed prefix effects.
+For code invalidation or eligibility changes, retain the old program and frame,
+set `stopAfterInstruction`, and run only that pending instruction to completion.
+The result is `invalidated` before another instruction begins; an idle frame with
+this flag exits immediately. A pending stop instead returns `stopped`.
+
+`readStates`, `writeStates`, `readMemories`, and `writeMemories` conservatively cover
+the whole accepted program, including both branches and implicit PC reads/writes.
+The binding runtime must guard these lists against observers, derived/hook read
+dependencies, code memories, waiters, and incompatible ownership before entering.
+The compiler does not choose throughput policy or schedule peripherals: callers
+supply exact horizons, including events and any CPU visibility quantum. Keep the
+generator backend for precise execution and unsupported instructions.
+
+Focused tests: build this package, then run
+`node --test packages/compiler/tests/direct-jit.test.mjs` from the repository root.
+
+## First-Release Analysis And Maps
+
+Every compilation indexes the original body before optimization. `compileBody` and
+`compileComputation` run the same correctness-preserving constant/use analysis, but
+emit executable functions directly without generating CFG edges, liveness sets,
+recovery maps, source positions or artifact objects. They retain no diagnostic IR.
+
+Artifact compilation captures lightweight source/emission information. Its CFG/SSA,
+effects and recovery metadata are lazy, memoized getters; requesting those fields
+lowers regions into an independent, immutable internal graph (`artifact.mir`).
+Merely reading `artifact.execute` or `artifact.source` does not build that graph.
+Operation-granular basic blocks have explicit predecessors, successors, branch/match edges,
+loop backedges, break/continue targets, value-region yields, call completion,
+suspension/resumption and return/throw/stop/redirect exits. Internal instructions
+carry operand IDs, detached attributes, nested-region IDs, original input paths,
+source links and per-operation effects. This is separate from public `RegionIR`;
+the JavaScript emitter keeps native structured control flow, not a CFG interpreter.
+
+Results have single-assignment definitions and use lists; select/short-circuit
+joins record phi inputs. Mutable locals remain explicitly identified slots, not
+SSA-renamed local versions. Fixed-point liveness handles loops and is computed both
+for the original baseline and for optimized uses/definitions.
+
+The default optimizer propagates known primitive/enum constants through arithmetic,
+comparisons, numeric builtins, optional lifting and none checks. Folded numbers stay
+binary64 values captured outside source text, including NaN and signed zero. An
+unused-result pass removes only total, effect-free scalar computations. Unknown
+intermediates used by original operations are conservatively retained, even if their
+only consumer is dead, so baseline recovery never requires unavailable unknown
+values. Known discarded values have constant materialization recipes. Dynamic bytes,
+reads, calls, assertions, resistor construction, indexing and other potentially
+failing operations remain. A non-null check is removed only for a known non-null
+constant. There is no branch speculation, host-read reuse, effect reordering or
+trust in a call's `pure` annotation. `{ optimize: false }` disables these transforms
+while retaining the same stable baseline position IDs and analysis/maps.
+
+Artifacts additionally expose:
+
+- `sourceMap`: stable original operation IDs, paths, inherited source locations and
+  real generated UTF-16 line/column ranges. Eliminated operations remain present
+  with `generated: null`; folded operations retain their original identity.
+- `frameLayout`: typed result/local/context slots and compiler-created condition or
+  assertion-message temporaries, linked to actual JavaScript binding names/scopes.
+  Constant materialization recipes preserve baseline values removed by folding/DCE.
+  Storage is explicitly `native-generator`, not a serializable external frame.
+- `resumeMap`: actual generated yield/yield* lines, continuation locations and live
+  slots. Receive results are defined on continuation; delegated results are defined
+  on call completion, not before suspension. Terminal signals have no live suffix.
+  Delegated resumption retains the native call stack; a position alone cannot
+  reconstruct it or replay the call safely.
+- `exitMap` and the exported `ExitState` data contract: source-linked baseline
+  positions for return, suspension, terminal control, failure and future optimized
+  exits, with required baseline slots versus slots that need capturing. Resume
+  positions are after the completed wait (or inside a retained delegate), avoiding
+  replay of prefix effects. Guard-exit entries are mapping data, not emitted guards.
+- `dependencies`: resource/callee dependencies plus optional binding identities.
+  Calls and wait predicates retain unresolved dependency summaries until resolved
+  against the model. `binding` is null unless the caller explicitly supplies
+  `{ binding: { instance, entry, generation, codeVersion, instruction } }`; identities
+  and code versions are never invented or inferred from resource names.
+
+The maps describe real emitted baseline locations and recovery requirements.
+Current execution does **not** capture `ExitState` objects, expose native generator
+locals, serialize frames or implement a speculative/deoptimization executor. A
+consumer must retain the native continuation or provide future capture machinery.
+Internal graph/layout schemas are compiler implementation metadata, not a replacement
+for the stable public model schema.
+
+Deferred, rather than claimed complete: local-to-SSA promotion and dominator/range
+analysis; interprocedural call/derived analysis and short-function inlining; alias-
+aware resource read/check CSE; bound numeric resource-slot specialization; optimized
+stack capture and deoptimization execution. The body-only ABI supplies no callee
+bodies or instance binding graph, so this release records conservative dependencies
+instead of making unsupported purity/aliasing assumptions. Model-level validation
+still owns call/derived cycle and effect legality checks.
+
+## Host Evaluation Order
+
+Assertions check their saved boolean condition first. A true condition skips both
+message computation and the host assertion call. On failure, the entire lazy message
+region runs before `host.assert(false, message)`; an omitted message is `undefined`.
+Message effects are therefore visible to the host assertion, while a throwing or
+redirecting message never reaches that call. The host must throw for a failed assertion.
+
+Memory operations call `host.load`, `host.store`, `host.copyBytes` and
+`host.memoryLength` at their original execution positions. Reads are not hoisted,
+cached or merged across writes or suspension. Generated calls pass the original
+operand values; the host validates resource ownership, nonnegative safe-integer
+byte offsets, complete ranges and safe-integer store values before mutation.
+Multi-byte accesses may be unaligned; store values use width-specific low bits only
+after validation. Byte copies must return independent immutable snapshots.
+
+Resource names appear as captured `C[index]` entries in generated source, while
+resource parameters appear as `args[index]`. Inspect `artifact.constants` alongside
+`artifact.source` to resolve captured names. Operation/source positions locate the
+load/store call site, not the inside of the host memory helper. The benchmark's
+DataView host is a small checked implementation of only the two exercised opcodes,
+not a replacement for the simulator's memory and lifecycle implementation.
+
+## Benchmark
+
+Build once, then run the bounded Node benchmark from the repository root:
+
+```powershell
+pnpm --dir packages\compiler build
+pnpm --dir packages\compiler bench --smoke
+pnpm --dir packages\compiler bench
+```
+
+The benchmark imports the public compiler package API and constructs new-model IR.
+It measures arithmetic and arithmetic-plus-memory kernels with native generated
+loops, parameterized seeds and loop counts. The memory kernel stores little-endian
+32-bit values through a resource parameter and reads big-endian values through a
+direct resource name at unaligned byte offsets.
+
+Each row reports first uncached `compileBody` time, subsequent artifact construction
+time, first lazy metadata materialization time, generated source length in UTF-16
+code units, median warmed batch time, executions/second, rounds/second and memory
+accesses/second. Baseline compilation includes optimization, emission and
+`new Function`, but excludes diagnostic CFG/liveness/recovery work, module import,
+fixture creation, package build and first execution. Artifact construction is timed
+after the baseline, so it can benefit from JavaScript engine source caching; it is
+not presented as a second cold measurement. Metadata timing explicitly forces all
+analysis/layout maps, verifies memoization, and is outside execution timing.
+Cold means the first uncached baseline compilation of each kernel in this process,
+not fresh-process startup; arithmetic is measured before memory.
+Warmed timings use the fast baseline executable and include generator creation,
+one `.next()`, host range/value checks and checksum accumulation. JavaScript reference calculations and preflight checks
+are outside measured batches; results are consumed and verified against reference
+checksums. These are local microbenchmarks, not simulator throughput or latency.
+
+Smoke mode uses 100 warmups, three 1,000-execution samples and 64 rounds per
+execution. Default mode uses 2,000 warmups, five 10,000-execution samples and 128
+rounds. Both modes do fixed, bounded work and add no unit tests. Compare results
+using the same Node version and machine; short smoke timings are especially noisy.