kumi 0.0.37 → 0.1.0

data/docs/FUNCTIONS.md

@@ -134,9 +134,12 @@ Auto-generated documentation for Kumi functions and their kernels.
 
 `agg.join:ruby:v1`
 
+**Inline:** `+= $1` (`$0` = accumulator, `$1` = element)
+
 **Fold:** `= $0.join`
 
-_Note: No identity value. First element initializes accumulator._
+**Identity:**
+- string: ``
 
 **Reduction:** First element is initial value (no identity)
 
@@ -253,6 +256,7 @@ _Note: No identity value. First element initializes accumulator._
 **Identity:**
 - float: `0.0`
 - integer: `0`
+- decimal: `0`
 
 **Reduction:** Monoid operation with identity element
 
@@ -405,7 +409,7 @@ _Note: No identity value. First element initializes accumulator._
 
 ```ruby
 (x, lo, hi)
-  [[x, lo].max, hi].min
+  x.clamp(lo, hi)
 ```
 
 _Note: No identity value. First element initializes accumulator._
@@ -435,6 +439,23 @@ a.to_s + b.to_s
 
 _Note: No identity value. First element initializes accumulator._
 
+## `core.cos`
+
+- **Arity:** 1
+- **Type:** float
+
+### Parameters
+
+- `angle`
+
+### Implementations
+
+#### Ruby
+
+`cos:ruby:v1`
+
+_Note: No identity value. First element initializes accumulator._
+
 ## `core.div`
 
 **Aliases:** `div`, `divide`
@@ -506,6 +527,23 @@ _Note: No identity value. First element initializes accumulator._
 
 _Note: No identity value. First element initializes accumulator._
 
+## `core.exp`
+
+- **Arity:** 1
+- **Type:** float
+
+### Parameters
+
+- `number`
+
+### Implementations
+
+#### Ruby
+
+`exp:ruby:v1`
+
+_Note: No identity value. First element initializes accumulator._
+
 ## `core.gt`
 
 **Aliases:** `>`, `greater_than`, `gt`
@@ -597,6 +635,23 @@ _Note: No identity value. First element initializes accumulator._
 
 _Note: No identity value. First element initializes accumulator._
 
+## `core.log`
+
+- **Arity:** 1
+- **Type:** float
+
+### Parameters
+
+- `number`
+
+### Implementations
+
+#### Ruby
+
+`log:ruby:v1`
+
+_Note: No identity value. First element initializes accumulator._
+
 ## `core.lt`
 
 **Aliases:** `<`, `less_than`, `lt`
@@ -671,29 +726,29 @@ _Note: No identity value. First element initializes accumulator._
 
 _Note: No identity value. First element initializes accumulator._
 
-## `core.mul`
+## `core.mul:string_repeat`
 
 **Aliases:** `mul`, `multiply`
 
 - **Arity:** 2
-- **Type:** promoted from `left_operand`, `right_operand`
+- **Type:** string
 
 ### Parameters
 
-- `left_operand`
-- `right_operand`
+- `string_value`
+- `repeat_count`
 
 ### Implementations
 
-#### Ruby
+#### String_repeat
 
-`mul:ruby:v1`
+`mul:string_repeat:ruby:v1`
 
 **Implementation:**
 
 ```ruby
-(a, b)
-  a * b
+(str, count)
+  str * count
 ```
 
 _Note: No identity value. First element initializes accumulator._
@@ -800,11 +855,46 @@ _Note: No identity value. First element initializes accumulator._
 
 ```ruby
 (a, b)
-  a ** b
+  r = a ** b
+  r.is_a?(Complex) ? Float::NAN : r
 ```
 
 _Note: No identity value. First element initializes accumulator._
 
+## `core.sin`
+
+- **Arity:** 1
+- **Type:** float
+
+### Parameters
+
+- `angle`
+
+### Implementations
+
+#### Ruby
+
+`sin:ruby:v1`
+
+_Note: No identity value. First element initializes accumulator._
+
+## `core.sqrt`
+
+- **Arity:** 1
+- **Type:** float
+
+### Parameters
+
+- `number`
+
+### Implementations
+
+#### Ruby
+
+`sqrt:ruby:v1`
+
+_Note: No identity value. First element initializes accumulator._
+
 ## `core.sub`
 
 **Aliases:** `sub`, `subtract`
@@ -832,6 +922,23 @@ _Note: No identity value. First element initializes accumulator._
 
 _Note: No identity value. First element initializes accumulator._
 
+## `core.tanh`
+
+- **Arity:** 1
+- **Type:** float
+
+### Parameters
+
+- `number`
+
+### Implementations
+
+#### Ruby
+
+`tanh:ruby:v1`
+
+_Note: No identity value. First element initializes accumulator._
+
 ## `core.to_decimal`
 
 - **Arity:** 1
@@ -911,7 +1018,7 @@ _Note: No identity value. First element initializes accumulator._
 
 _Note: No identity value. First element initializes accumulator._
 
-## `core.to_string`
+## `core.to_string:float`
 
 **Aliases:** `to_str`, `to_string`
 
@@ -926,7 +1033,7 @@ _Note: No identity value. First element initializes accumulator._
 
 #### Ruby
 
-`to_string:ruby:v1`
+`to_string_float:ruby:v1`
 
 **Implementation:**
 

data/docs/INPUTS.md

@@ -0,0 +1,164 @@
+# Kumi Input Shapes
+
+The `input do … end` block declares the shape of the data a schema runs on:
+scalars, arrays, hashes, and any nesting of them. Every value referenced in the
+body (`input.foo.bar`) must trace back to a declaration here.
+
+This is the reference for declaring inputs. For the rest of the language
+(declarations, operators, functions, control flow) see [SYNTAX.md](SYNTAX.md).
+
+## The element rule: always name the element
+
+Kumi **maps over arrays by default** (unless you `zip`). The single child inside
+an `array` block names the element that the map binds and iterates over — so the
+element must always be named. Every `array` declares **exactly one child**:
+
+- a primitive (`integer :value`) for a **scalar array**,
+- a `hash` (`hash :item do … end`) when each element has **several fields**,
+- a nested `array` for an **array of arrays**.
+
+There is no childless/nameless array — without a name there is nothing for the
+map to bind. Omitting the child is an error that tells you exactly this.
+
+`index: :i` is **not** the element — it names the **axis/position** so you can
+read the index value with `index(:i)`. You do *not* write `input.cells.i` to
+reach the element; the element is the named child (`input.cells.value`) or the
+broadcast array itself (`input.cells`).
+
+## Scalars
+
+Scalar inputs represent single values:
+
+```kumi
+input do
+  integer :x
+  float :rate
+  decimal :price        # Precise decimal for money calculations
+  string :name
+end
+```
+
+**Example:**
+```kumi
+schema do
+  input do
+    integer :x
+    integer :y
+  end
+
+  value :sum, input.x + input.y
+  value :product, input.x * input.y
+end
+```
+
+## Arrays
+
+Arrays represent sequences. Navigate using dot notation through each level.
+Remember the [element rule](#the-element-rule-always-name-the-element): each
+`array` declares exactly one named child.
+
+**1D Array (scalar elements):**
+```kumi
+input do
+  array :cells do
+    integer :value     # `value` names the element
+                       # Access: input.cells.value  (maps elementwise)
+                       #         input.cells         (whole array, e.g. fn(:size, …))
+  end
+end
+```
+
+**2D Array (grid):**
+```kumi
+input do
+  array :rows do
+    array :col do
+      integer :v       # Access: input.rows.col.v
+    end
+  end
+end
+```
+
+**3D Array (cube):**
+```kumi
+input do
+  array :cube do
+    array :layer do
+      array :row do
+        integer :cell  # Access: input.cube.layer.row.cell
+      end
+    end
+  end
+end
+```
+
+## Arrays of Hashes
+
+Common pattern for structured collections — use a `hash` child when each element
+has several fields:
+
+```kumi
+input do
+  array :items do
+    hash :item do
+      float :price
+      integer :quantity
+      string :category
+    end
+  end
+end
+
+# Access: input.items.item.price
+#         input.items.item.quantity
+```
+
+## Hashes
+
+Hashes represent structured data with named fields:
+
+```kumi
+input do
+  hash :config do
+    string :app_name
+    array :servers do
+      hash :server do
+        string :hostname
+        integer :port
+      end
+    end
+  end
+end
+
+# Access scalar: input.config.app_name
+# Access nested: input.config.servers.server.hostname
+```
+
+## Arrays with Named Indices
+
+`index:` names an axis so you can read its **position** with `index(:name)`. It
+is independent of the element — you still name the element child (here the
+placeholder `integer :_`, since only the positions are used). `index(:i)` reads
+the position; it is never an element accessor (`input.x.i` is not a thing).
+
+```kumi
+input do
+  array :x, index: :i do
+    array :y, index: :j do
+      integer :_           # element child (value unused, only positions matter)
+    end
+  end
+end
+
+# Use in expressions
+let :W, fn(:array_size, input.x.y)
+value :row_major, (index(:i) * W) + index(:j)
+value :col_major, (index(:j) * fn(:array_size, input.x)) + index(:i)
+```
+
+## See also
+
+- [SYNTAX.md](SYNTAX.md) — declarations, operators, functions, control flow.
+- [SYNTAX_NOTES.md](SYNTAX_NOTES.md) — parser differences, mixed nested
+  array/hash recipes, expression literals, and post-parse analyzer errors.
+- All-pairs over arrays: `cross` (one array, A × A') and `outer` (two arrays,
+  A × B) in [SYNTAX.md](SYNTAX.md#all-pairs-cross).

data/docs/OUTPUT_SCHEMA.md

@@ -31,15 +31,19 @@ bin/kumi analyze schema.kumi --dump output_schema --side-tables
 
 **Schema:**
 ```kumi
-input items: array {
-  item: hash {
-    price: float
-    quantity: integer
-  }
-}
+schema do
+  input do
+    array :items do
+      hash :item do
+        float :price
+        integer :quantity
+      end
+    end
+  end
 
-trait expensive: items.item.price > 100.0
-value total: items.item.price * items.item.quantity
+  trait :expensive, input.items.item.price > 100.0
+  value :total, input.items.item.price * input.items.item.quantity
+end
 ```
 
 **Generated Output Schema:**

data/docs/PASSES.md

@@ -0,0 +1,76 @@
+# Compiler Pass Conventions
+
+These rules are enforced by `spec/kumi/analyzer_pipeline_contract_spec.rb`,
+`PassManager` contract checks, and RuboCop. Change the enforcement when you
+change a rule.
+
+## Naming
+
+- Every pass class name ends in `Pass`; its file name ends in `_pass.rb`.
+- New acronyms in class names require a zeitwerk inflector entry in
+  `lib/kumi.rb` and are discouraged — prefer plain words.
+
+## Two pass shapes, never mixed
+
+- **Analyzer passes** (`lib/kumi/core/analyzer/passes/`): subclass
+  `Passes::PassBase`. `run(errors)` takes an error accumulator and returns an
+  `AnalysisState`. State is immutable; produce new state with `state.with`.
+- **IR passes** (`lib/kumi/ir/*/passes/`): subclass `Kumi::IR::Passes::Base`.
+  `run(graph:, context:)` returns a graph; compose with `IR::Passes::Pipeline`.
+- Bridging happens only through the boundary adapters `IRValidatePass` and
+  `IRLowerPass` — never call an IR pipeline ad hoc from an analyzer pass.
+
+## State contracts
+
+Every analyzer pass declares what it touches, at the top of the class body:
+
+    class SNASTPass < PassBase
+      reads  :nast_module, :metadata_table, :registry
+      writes :snast_module
+    end
+
+- `reads` — required keys; fails fast in `PassManager` if absent. Also defines
+  a reader method per key.
+- `optional_reads` — keys that may be absent; reader returns `nil`.
+- `writes` — every key the pass adds or replaces. A pass that produces no
+  state declares bare `writes` (no arguments) so the contract is still
+  explicit. `PassManager` rejects any undeclared write.
+- `# In:` / `# Out:` comments are banned — the DSL is the single source of
+  truth, and `spec/kumi/analyzer_pipeline_contract_spec.rb` checks that every
+  pipeline pass declares a contract and that pass ordering satisfies all reads.
+- Passes that annotate IR/NAST nodes in place (e.g. `AttachTerminalInfoPass`)
+  declare bare `writes`; keep such in-place mutation limited to node `meta` /
+  annotation fields, never structure.
+
+## Error reporting
+
+One channel per logical error — never report AND raise the same problem (that
+surfaces it twice, once via the accumulator and once via PassManager's exception
+capture, which also leaks internal file paths).
+
+- **User-facing errors** (the schema is wrong): record them in the `errors`
+  accumulator passed to `run`, with a real `location:` (pass the node's `loc`,
+  never interpolate it into the message string). Use `report(errors, msg, node:)`
+  to keep going and collect more, or `halt_pass!(errors, msg, node:)` to record
+  one and stop the pass cleanly. A halted/erroring pass fails because `errors`
+  is non-empty — no exception needed.
+- **Internal invariants** ("can't happen" — a violated assumption, not bad user
+  input): `raise Kumi::Core::Errors::CompilerBug, "..."`. It is framed as a bug
+  to report and is never presented to users as if they wrote bad input.
+- Do not raise `SemanticError`/`TypeError` directly from a pass for user errors;
+  route them through the accumulator so they are located and deduplicated.
+
+## Loading
+
+- zeitwerk owns everything under `lib/kumi/`. Inside `lib/`, only require
+  stdlib (`require "json"` etc.) — never `require "kumi/..."` for autoloadable
+  constants. Exceptions are the files explicitly ignored in `lib/kumi.rb`.
+
+## Debug and checkpoint env vars
+
+- `DEBUG_<SHORT_NAME>=1` enables per-pass debug output; the short name is the
+  class name minus the `Pass` suffix, underscored (`SNASTPass` → `DEBUG_SNAST`).
+- `KUMI_RESUME_AT` / `KUMI_STOP_AFTER` take the pass short class name
+  (e.g. `SNASTPass`).
+- `KUMI_DEBUG_REQUIRE_FROZEN=1` makes `PassManager` assert state values are
+  frozen after each pass (debug mode only).

data/docs/PASS_AUDIT.md

@@ -0,0 +1,179 @@
+# Analyzer Pass Audit — Findings & Plan
+
+Audit of `lib/kumi/core/analyzer/` (≈45 passes + machinery). Baseline: 959 examples,
+0 failures, 50/50 goldens. Each finding is evidence-backed; severity is impact × reach.
+
+The framework itself (`PassManager`, `AnalysisState`, contract DSL in `PassBase`,
+`docs/PASSES.md`, the contract spec) is **good** — immutable state, declared reads/writes,
+ordering enforcement, per-pass budget, checkpoint/resume. The problems are in how passes
+*report errors* and a few localized hygiene issues. Most value is in error reporting.
+
+---
+
+> **STATUS (2026-06-18, later): widened beyond passes.** Fixed a SECOND user-facing leak
+> (unknown function `fn(:nope,...)` leaked an internal pass/file path — the validator's
+> existence check called a method that raised instead of returning false; added a non-raising
+> `RegistryV2#function?`). Typed the registry kernel-lookup invariants, IR execution-engine
+> combinator invariants, and schema.rb operational errors: added `Errors::ConfigurationError`
+> (host-app misuse), put the unused `Errors::RuntimeError` to work for align_to's :error policy.
+> ~70 bare `raise "string"` remain in lower-traffic IR-pipeline/dev paths. 971 specs, 50/50 goldens.
+>
+> **STATUS (2026-06-18): F1, F2, F3, F4, F5 DONE + location rendering unified.**
+> Added `Errors::UnsupportedFeature` (a valid construct the backend can't emit) alongside
+> `CompilerBug`. Converted the codegen "does not support opcode/shift-policy/inline" raises
+> (Ruby + JS emitters) to `UnsupportedFeature`; converted the compiler accessor invariants
+> ("unknown accessor mode/operation") and the binder/macro_expander/pass_manager contract
+> invariants to `CompilerBug`. Unified all source-location rendering on one `file:line:col`
+> format (Location#to_s is the single authority; ErrorEntry/LocatedError/PassFailure/SourceFrame
+> all delegate; killed the double-location). Gated by error_reporting_spec + error_handling_spec.
+> DISCOVERY: `compiler/access_planner.rb` (v1, 258 LOC) is DEAD — superseded by
+> `AccessPlannerV2`, zero live refs, no specs; its 7 ArgumentError invariants were left
+> untouched pending deletion (separate cleanup). Remaining: **F6**, **F7**, +delete dead v1.
+> 969 specs, 50/50 goldens.
+>
+> **STATUS (2026-06-18): F1, F2, F4, F5 DONE.** A type mismatch now surfaces as exactly
+> one located error with no internal leaks (was 3). Added `Errors::CompilerBug`; `PassBase`
+> gained `report`/`halt_pass!` (via a `catch(HALT)` in PassManager) and lost the broken
+> `error` footgun; removed the duplicate re-append in `analyzer.rb`; swept
+> `nast_dimensional_analyzer_pass` + `snast_pass` + `ir_execution_schedule_pass` and the
+> invariant lookups in `attach_anchors`/`attach_terminal_info`/`input_collector`/
+> `precompute_access_paths` to CompilerBug. Rule documented in `PASSES.md`. Gated by
+> `spec/kumi/core/analyzer/error_reporting_spec.rb`. Remaining: **F3** (codegen "does not
+> support" capability raises — 7 sites), **F6**, **F7**. 965 specs, 50/50 goldens.
+
+## F1 — Errors triple-report; located error buried under internal leaks  ★★★ (highest impact)
+
+**Evidence:** a single `add(string, string)` type mismatch surfaces THREE times to the user:
+
+```
+at s.kumi line=5 column=18: add(string, string) - type mismatch        <- good, located
+Error in Analysis Pass(NASTDimensionalAnalyzerPass) at .../nast_dimensional_analyzer_pass.rb:119: ... type mismatch
+Error in Analysis Pass(NASTDimensionalAnalyzerPass) at .../nast_dimensional_analyzer_pass.rb:119: ... type mismatch
+```
+
+**Root cause:** `NASTDimensionalAnalyzerPass` (and others) do BOTH
+`report_type_error(errors, ...)` (accumulate, located) AND immediately `raise TypeError`
+(`nast_dimensional_analyzer_pass.rb:108-128`, `:151`). `PassManager#capture_exception`
+(`pass_manager.rb:148`) catches the raise and adds a SECOND error built from the backtrace
+head (`Error in Analysis Pass(X) at <file:line>: …`) — leaking compiler internals + file
+paths to the user. The duplication-to-three comes from the raise being captured and the
+located error also flowing through.
+
+**Fix:** pick ONE reporting channel per logical error. For user-facing errors: accumulate
+via `report_*` and `return state` (or `throw`/sentinel to stop the pass) — do NOT also raise.
+`capture_exception` should be reserved for genuine bugs (unexpected exceptions), and its
+message should not be presented as a user error alongside located ones. Dedup errors before
+`handle_analysis_errors` formats them.
+
+## F2 — Location passed in the message string, not the structured field  ★★★
+
+**Evidence:** `snast_pass.rb:94` —
+`raise SemanticError, "select mask axes ... at: #{n.loc}"`. The location is interpolated
+into the text instead of `SemanticError.new(msg, n.loc)`, so `SourceFrame`/`PassFailure`
+can't render a code frame and the coordinate can't be deduped.
+
+**Also:** 14 sites do `raise Kumi::Core::Errors::SemanticError, "msg"` / `TypeError, "msg"`
+with NO location arg at all (`snast_pass.rb:102,133,140,196,209`,
+`nast_dimensional_analyzer_pass.rb:128,151,179,183,211,215,396`, `ir_execution_schedule_pass.rb:23,54`).
+Each user-reachable one should pass the node's `loc`.
+
+**Fix:** every `LocatedError` raised from a user-reachable condition passes `node.loc` as the
+second arg; never interpolate location into the message.
+
+## F3 — Bare `raise "string"` (RuntimeError) for both invariants and user errors  ★★
+
+**Evidence (14 sites):** `input_collector_pass.rb:120`, `attach_anchors_pass.rb:60,70,90`,
+`attach_terminal_info_pass.rb:36`, `snast_pass.rb:102`, `nast_dimensional_analyzer_pass.rb:69,344`,
+`precompute_access_paths_pass.rb:76` (`raise ArgumentError, "order"` — opaque), the three
+codegen emitters (`"… codegen does not support …"`).
+
+Two distinct intents are conflated:
+- **Internal invariants** ("unknown parent container", "no anchor for axes") — "can't happen"
+  bugs. These SHOULD raise, but as a dedicated `Kumi::Core::Errors::CompilerBug` (new) so
+  they're never mistaken for user errors and carry a "please report" framing.
+- **Capability limits** (codegen "does not support opcode X") — these are real, expected
+  conditions; should be a typed error with the offending opcode/policy, not a bare string.
+
+**Fix:** introduce `CompilerBug < Error` for invariants; convert capability raises to a typed
+`Errors::UnsupportedFeature` (or reuse `CompilationError`) with structured context.
+
+## F4 — `PassBase#error` helper is a footgun (reads unset `@errors`)  ★★
+
+**Evidence:** `pass_base.rb:113-116` — `def error(...) add_error(@errors, ...)`. `@errors`
+is never assigned by `PassBase`; `run(errors)` passes the accumulator as an ARGUMENT. Only
+`snast_pass.rb:17` sets `@errors` manually (then ignores it and raises anyway). No other pass
+calls `error`. So the base helper silently pushes to `nil` for any pass that uses it without
+the undocumented `@errors =` ritual.
+
+**Fix:** either (a) remove the broken `error`/`add_error` instance helpers from `PassBase` and
+standardize on the `ErrorReporting` mixin's `report_*(errors, …)` (explicit accumulator), or
+(b) make `PassBase#run` store `@errors = errors` via a `super`/template method so `error`
+works. Prefer (a) — explicit accumulator threading matches the rest of the codebase.
+
+## F5 — Two reporting idioms split the pipeline in half  ★★
+
+**Evidence:** ~15 passes take `run(errors)` and accumulate; ~14 take `run(_errors)` and only
+`raise`. The accumulator path enables multi-error reporting + located `PassFailure`; the raise
+path gives single-error, degraded `capture_exception` output. The split is not by intent
+(validation vs lowering) — it's incidental.
+
+**Fix:** document the rule in `PASSES.md` ("user-reachable errors accumulate; invariants
+raise `CompilerBug`"), then bring the raise-only validators in line. Lowering passes that only
+hit invariants legitimately keep `_errors`.
+
+## F6 — `FormalConstraintPropagator` misfiled in `passes/`, breaks naming convention  ★
+
+**Evidence:** `passes/formal_constraint_propagator.rb` — class `FormalConstraintPropagator`,
+no `Pass` suffix, not a `PassBase`, not in any pipeline list. It's a COLLABORATOR used by
+`UnsatDetectorPass:19`. It also carries the banned `# RESPONSIBILITY:/DEPENDENCIES:/INTERFACE:`
+header comment (cousin of the `# In:/# Out:` ban in PASSES.md).
+
+**Fix:** move it to `lib/kumi/core/analyzer/` (alongside `binder.rb`, `folder.rb`,
+`constant_evaluator.rb`) so `passes/` contains only passes; drop the header comment.
+
+## F7 — Codegen emitters duplicate structure (JS 410 / Ruby 212 LOC)  ★ (lower priority, higher risk)
+
+**Evidence:** `codegen/loop/js/emitter.rb` and `codegen/loop/ruby/emitter.rb` share a parallel
+method skeleton (`emit_instruction`, `emit_function`, `emit_acc_step`, `emit_shift_read`,
+`apply_inline`, `kernel_expr`, `format_literal`, `format_object`, `tuple_keys?`, `reg`) and the
+same opcode-dispatch + "does not support" raise pattern, but emit different target syntax.
+
+**Assessment:** real duplication, but target languages legitimately diverge; over-abstraction
+here is a known trap. Recommend a SMALL shared base (opcode dispatch table + the unsupported-
+opcode raise via F3's typed error + register/scratch naming), NOT a unified emitter. Defer
+until F1–F5 land; treat as opportunistic.
+
+## F8 — Two error modules with overlapping names  ★ (note, not necessarily a change)
+
+`Core::ErrorReporting` (instance mixin: `report_*`, `raise_*`) vs `Core::ErrorReporter`
+(module: `create_error`, `add_error`, `raise_error`, `ErrorEntry`). The split is defensible
+(mixin vs factory) but the near-identical names invite confusion. Consider renaming the mixin
+to `ErrorReportable` OR documenting the boundary in one place. Low priority.
+
+---
+
+## Plan (ordered by impact, each independently shippable & test-gated)
+
+1. **F1+F2+F4+F5 together (the error-model fix)** — the highest-value, coherent change:
+   - Add `CompilerBug` error class.
+   - Establish the rule: user-reachable → accumulate located error + stop pass cleanly;
+     invariant → raise `CompilerBug`. Document in `PASSES.md`.
+   - Remove/fix the `PassBase#error` footgun.
+   - Sweep `nast_dimensional_analyzer_pass` and `snast_pass` first (they cause the visible
+     triple-report), then the rest of the raise-only validators.
+   - Dedup errors in `analyzer.rb` before formatting.
+   - **Net user-visible win:** one clean, located error instead of three with leaked internals.
+   - Gate: new spec asserting the type-mismatch case yields exactly ONE located error with no
+     `Error in Analysis Pass(...)` / no internal file paths.
+
+2. **F3** — typed errors for invariants (`CompilerBug`) and capability limits
+   (`UnsupportedFeature`/`CompilationError`) across passes + codegen emitters.
+
+3. **F6** — relocate `FormalConstraintPropagator` out of `passes/`.
+
+4. **F7** — opportunistic small shared codegen base (only after 1–3, only if low-risk).
+
+5. **F8** — naming/doc clarification (optional).
+
+Non-goals: rewriting the pass framework (it's sound), reordering the pipeline, touching IR
+pass internals beyond error reporting.