pass.upass runs a sequence of micro-passes (uPasses) over an LNAST. Its job
is to propagate compile-time-known values, dead-code-eliminate everything
those values make redundant, and emit a new LNAST that replaces the input.
This document is the contract for how the pipeline works today: push-based dispatch over one runner-owned scope-aware symbol table (the 2b flag-day, landed 2026-06-10, on top of the 1b Bundle/Entry reshape landed 2026-06-09). When a change lands in this area, update this doc in the same change.
upass consumes LNAST produced by inou/prp (new), inou/pyrope (legacy,
sunsetting), and inou/slang. Standing constraints from the LNAST contract:
- Value ranges (
max/min) are owned by thebitwidthpass (§2), which observes stores during the runner walk and publishes ranges intobw_metaatend_runforlnast_to_lgraph. No other pass derives or folds on ranges (invariant #6). - Bare ref text. upass assumes
$/%/#prefixes are already removed; direction/storage is carried structurally, not encoded in the name. - tmp identity. The symbol table is keyed by name; the
___Ntmp / named-var distinction never affects fold logic. delay_assignis a fold barrier. upass never folds across one; emit verbatim.
A single pass.upass invocation processes each LNAST in var.lnasts:
(0) extract ─ the Pyrope parser switches a destination stack at
each named comb/pipe/mod, streaming directly into
its final sibling LNAST and popping back at `}`.
Nested functions naturally push another destination.
The compatibility extractor only handles non-Pyrope
or legacy trees that still contain real func_defs.
(1) semacheck ─ one-shot begin_iteration() walk over the source
tree (diagnostics point at user-shaped LNAST)
(2) uPass_ssa::run ─ harvests io_meta. Composite port field accesses and
straight-line scalar SSA for generated scalar trees
are handed to the runner; the conservative legacy
tree rebuild remains for stale SSA, unsupported
tuple-port operations, and source Pyrope that still
needs control-flow SSA.
(3) runner walk ─ ONE depth-first pre-order walk of the source.
Its first stage is the detupler: it learns tuple
fields/types from the shared scoped symbol table
and emits only scalar declarations/operations to
SSA and the remaining passes. The aggregate tuple
nodes are virtual and never enter the output tree.
For each value node the runner resolves the
operands (dst = the live table bundle, src = one
Operand per child) and pushes
process_<op>(dst_name, dst, src) into every
active pass in resolved order (§1.1), collecting
keep/drop votes. Control/structure hooks
(if/stmts/range/attr_set/…) stay cursor-based.
The runner also scalarizes static tuple-port reads
and writes and versions repeated scalar definitions
selected by (2), while it emits 0..N nodes into the staging
tree, folding ref operands through try_fold_ref
(a direct table read) on the way out.
(3b) tree aegraph ─ upass/aeg (injected by pass.upass, same gates as the
DCE): the allowlisted aegraph simplify rules, CSE
and forwarding over the complete staging tree in
tolg's name model. In place only: reader operands
renamed or made constant, statements retyped to a
rule's result; the defs it leaves unread go to (4).
The walk's passes already judged the source form;
the cycle checks (upass/timecheck, tolg's `@[N]`
and LG checker) judge this body by its
dependencies, so in a timed unit what they read
(the cones of timed values, `@[N]` checks, output
chains) stays as written.
(4) post-walk DCE ─ dead_code_eliminate_staging: liveness backstop.
Graph-only compilation records dead statement IDs
for tolg to skip and does not copy the tree. LNAST
output still rebuilds a clean tree because HHDS has
no safe bulk-prune operation yet.
(5) finishers ─ verifier, then assert: read-only walks of the
emitted (dest) tree; cassert tally (§2)
The single walk is the load-bearing performance property: the source tree is traversed exactly once per invocation, and the passes are called as the walk visits each node. There is no iteration knob and no fixed-point loop; direct symbol-table mutation in a fixed pass order makes one sweep per node sufficient.
Each pass.upass invocation starts clean: symbol table rebuilt from scratch,
scope stack empty. Re-runs (after another lowering stage, after an import
resolves) get a fresh view.
Pass order is owned by depends_on declarations + a topo sort, not by
folklore. The mechanism (wired and live today):
- Each pass registers itself via a static
upass::uPass_plugin("name", setup_fn, {deps...})(upass/core/upass_core.hpp:401-416); the optional third argument is thedepends_onlist. uPass_runner::resolve_order(upass/runner/upass_runner.cpp:231-282) runs a DFS topo sort over the requested names, pulling declared dependencies in first and detecting cycles. Duplicate requests are de-duplicated (first completion wins), so a pass appears once in the dispatch list no matter how often it is requested.- The requested-name list is assembled by
pass/upass/pass_upass.cpp(label toggles + theorder=csv override).
Current default request order, with each placement's reason:
| pass | declared depends_on |
placement reason |
|---|---|---|
| verifier | — | requested first and last; resolve_order dedups to one instance — harmless, it is a dest-walk finisher whose slot in the per-node dispatch is irrelevant |
| semacheck | — | one-shot pre-walk; only needs to be registered before the walk starts |
| func_extract | — | placed before the value passes (registration order) |
| attributes | — | first value pass: sticky/attr state must exist before constprop folds .[attr] reads |
| typecheck | {attributes} |
declared kinds available; fails fast before the value passes do work |
| constprop | — | after attributes + typecheck (registration order today) |
| bitwidth | — | last opt pass: no fold_ref, read-only, must observe stores pre-DCE (§2) |
| coalescer | — | after constprop so its known-const guard sees an up-to-date try_fold_ref; dropped from the default order entirely when toln:0 && tolg:0 (nothing materializes) |
| assert | {constprop} |
reads the values constprop populates; last before the final verifier slot |
All placement reasons are declared edges now: typecheck {attributes},
constprop {attributes, typecheck}, bitwidth {constprop},
coalescer {constprop, bitwidth}, assert {constprop}. pass_upass.cpp
generalizes warn-and-drop over every edge as a fixed point: a disabled pass
drops its dependents with a warning, never silently re-enables (the
toln:0 coalescer drop stays silent — policy, not a dependency).
Rules that matter more than the exact spelling:
semacheckruns before rewrites mutate the tree, so user diagnostics point at source-shaped LNAST.- SSA naming is stable at each runner dispatch. The legacy path arrives
pre-versioned; the streaming path preserves source names in the shared
symbol table and emits SSA-versioned definitions/uses to the output tree.
bitwidthandlnast_to_lgraphtherefore consume the same SSA-stable ABI. - Attribute conflict diagnostics are owned by
attributes;typecheckis compile-time-only and propagates nothing to LGraph. bitwidthmust see every store before DCE.- When a new uPass is added or an existing pass starts reading another pass's facts, declare the edge — do not extend the builder's implicit order.
Owns the user-facing checks relocated out of pass.lnastfmt (now a
compiler-internal structural validator): write to a read-only / derived
attribute (:[bits=], :[max=], size/sign/key — the only enforcement site),
declare-once (same-scope redeclaration), and a shadowing backstop (prp2lnast
enforces no-shadowing first, with a sharper span). One-shot
begin_iteration() walk over the source tree — runs before the walk mutates
anything (located via the declare/attr_set loc-carry chain). Read-only; emits
core/diag records (read-only-attr-write, redeclaration,
variable-shadowing). Default on.
Owns value facts. Folds scalars/bundles through the runner-owned
Symbol_table (push hooks read the resolved operands; every fold lands on
the table — there is no constprop-private value state). Each value hook's
return vote decides whether the statement is already-known and droppable
(classify_vote() over the cursor-based classify_statement_impl()
evaluation). Also owns the import machinery statics (pending_imports_,
ambiguous_units_, function_registry) — the kernel's whole-file-retry
seam. Declared facts (mode / typename / unsigned envelope) are read from the
bindings the runner's declare/type_spec bake wrote; range bounds ride the
range tmp's binding attrs (rng_s/rng_e); runtime tuple-slot refs live in
Symbol_table::tuple_slot_ref.
Owns attr_set/attr_get semantics, attribute propagation, and
attribute-conflict diagnostics. Attributes are read-only views of facts
inferred by other passes (bits, max, min), or user-visible metadata
that must propagate and may survive to LGraph generation. Sticky attributes
(canonical leading-_ names; debug ⇒ _debug) propagate through
assignment-shaped ops via Sticky_handler; category-B wiring attributes
(clock_pin, posclk, …) are validated here and reach LGraph through the
emitted attr_set nodes in the dest tree (tolg's lower_attr_set reads
the tree, never a pass-private map). Dispatch is per-attribute via
Handler_registry.
Compile-time type legality only (kind lattice: integer/boolean/string/…).
Checks declaration/store/call compatibility, tuple/scalar shape mismatches,
field membership, and no type change on already-typed destinations. Declares
depends_on {attributes}. It may read type/shape facts but does not
propagate attributes to LGraph and does not own attribute-query behavior.
Responsibility boundary, not a forced directory split — sharing
implementation with upass/attributes is acceptable where simpler.
Runs last in the per-node dispatch. Never feeds constprop's folding,
never rewrites a node. Running inside the walk lets it observe every store
before DCE — the init value of a typed declaration lives in a separate
store node that DCE removes when the var is unused, so a post-DCE pass
would miss overflow on a dead comptime const. The bitwidth-overflow
compile error is emitted at the offending node whenever a TYPED
destination (a declared local/reg, an inlined param/output typespec, or the
unit's own port) does not CONTAIN the right-hand side's range: "does not fit"
when every value overflows, "may not fit" when only some may, and "may not
fit" for a value too WIDE for an i64 range (x << n, a U40 product, a U64:
Symbol_table::wide_values; wrap/sat-exempt, scalars-only today). A read with
no derived range takes its declared type as its range (an input port, a
register read). That is sound because every write into a typed name is
judged, except one whose range nothing derived (a generic's comptime bind, an
opaque call result): such a name joins Symbol_table::unchecked_typed, and
its type is no longer used as its read range (here, nor by the runner's
wrap/sat, cast and argument checks). An untyped name takes the range of its
value and is never checked; a compiler temp falls back to the structural
envelope its producer stamped (a bit-select's width, a cast's type), a Sub
instance output to its port type, an array element to its element type. A
write that does not fit leaves its destination holding the declared range, so
one overflow is reported once. An uncertain if merges each written var's
arms with its pre-if range, and every arm after the first starts from the
pre-if range (inside a loop body a name is not SSA-renamed per arm). A
rolled loop's lifted body is checked like any body, carries included, and
legality must not depend on compile.unroll: the roller evaluates the body's
ranges per iteration at plan time (eval_carry_ranges, the same lattice) and
seeds each carry-in port with the union of the values that enter an
iteration, as it does for the index. It keeps the loop unrolled when that one
walk would still judge a typed write stricter than every iteration does, or
when the ranges cannot be derived and a carry reaches a typed write without
wrap/sat; a loop with break/continue cannot unroll and always rolls. Ranges
live on the binding's Entry (bw_max/bw_min) with a write-through to
lnast->bw_meta() for lnast_to_lgraph; bits/sign derive on demand,
never stored. Wrap/sat narrowing math lives here (attributes keeps only the
policy bit).
Range soundness contract (root-caused 2026-06-10): a derived range is a
conservative bound on the binding's current value — distinct from (and
usually narrower than) the typesystem's declared envelope. Every stamp
REPLACES the binding's range (each stamp is a fresh derivation of this
node's result; reassignments and loop re-walks rebind), a value write
invalidates the old derivation (Bundle::value_entry clears bw), and the
dispatch post-merge takes the freshest derivation. Bitwise op ranges:
a&b ∈ [0, min(maxes)], a|b ∈ [max(mins), ones-cover(max of maxes)],
a^b ∈ [0, ones-cover] for non-negatives (single-point ranges fold exactly,
any sign; possibly-negative non-constant operands go unbounded); ~x is
exactly [-max-1, -min-1]. The runner enforces the invariant with an I():
a comptime-known value must lie within its derived range.
Deferred-emit / dead-store elimination: parks pure scalar defs
(pending map), materializes-at-use via the runner's runner_emit_at_fn
replay seam, DSE on overwrite, drops const-known defs. Comptime mut stores
are parked and never comptime-dropped at flush (see memory
comptime_mut_dse_coalescer). Disabled automatically when nothing
materializes (toln:0 && tolg:0). The remaining lazy-DCE work (sea-of-nodes)
is todo/livehd/1d.html. The park decision rides
the pass's push-hook vote (consume_park_vote()).
Inline-vs-spawn decisions at call sites ride the runner's virtual-splice
inliner (§4); func_extract owns the spawn side — extracting comb/mod/pipe
bodies into separate LNASTs in var.lnasts for independent pass.upass
walks — plus closure capture of outer comptime scalars/bundles/imports into
the extracted body. Function scopes on the shared table are read-through
(closure capture of outer comptime consts) / write-block (an outer write is
a compile error).
A range for that can stay rolled (compile.unroll=false, the default) is
planned by plan_loop_roll, its body is LIFTED into a definition of its own
(<owner>.__loop<N>: the index port, __valid, invariants, carry-in/out
ports) and the loop becomes a rolled_for node that upass.tolg lowers to a
Sub with a loop descriptor (first/step/count PER INSTANCE).
- Shared definitions. A loop nested in a loop that unrolls (its domain
reads the outer index:
for j in (i + 1)..<Ninsidefor i) is rolled once per outer iteration. The outer index is a constant in each copy; when nothing in the body needs it at compile time (unrolled_index_promotable: only arithmetic, comparisons, bit selects/writes and branch conditions read it), it is PROMOTED to an invariant port typed by the outer domain, andlift_or_share_loopinstantiates the definition an earlier copy lifted (same source body and plan signature, a domain and carry/invariant ranges the definition admits). A copy outside them (for j in 0..<igrows withi) re-plans the body over the hull of both domains and, when that plan has the same signature and admits both, widens the still-queued definition in place (widen_lifted_loop: index port type and published ranges). One definition, N instances; the bound is the descriptor, not part of the body. Legalize never splits or unrolls these Subs, so sharing is purely a front-end naming decision. - Loop-index ports. The lifted body marks its index, every invariant that
is an enclosing loop's index and every promoted index as loop-index ports
(
upass::mark_loop_index_port,upass/core/loop_index_ports.hpp; persisted inbw_metaunder a#key). upass.tolg treats a bit position computed only from these and constants as LOOP-AFFINE: constant wherever a consumer expands the loop (pass.abc's carry unroll, the simulator's small-loop unroll). - Bit writes.
v#[p +: w] = x(and an array elementa[i] = x) at a loop-affineplowers to(v & ((1 << p) - 1)) | (set_mask(v >> p, x, 0, w) << p)[0 .. |v|](the shift always cut to v's width: pass.bitwidth sizes it by p's storage envelope, so uncut each write widened the next one's base and K writes per body grew a K*8K-bit chain), which cprop folds to the slicesv[p + w ..],x,v[0 .. p]oncepis constant (the masked RMW(v & ~(m << p)) | ((x << p) & (m << p))does not fold: a word-wide And with a one-hole mask stays per write). A data-dependentpkeeps the masked RMW, which is cheaper for a genuinely runtime position. Independently of loops, when every arm of anif(or a non-exhaustiveunique if/match) that writesvwrites the SAME window of the same pre-ifvalue, the arms' narrow lanes are muxed and the window is written once (merge_window_writes; an arm that does not write keeps the old lane through the write enable), instead of a full-width mux of full-width copies per arm. A data-dependent window written by ONE arm keeps the per-arm form (c ? rmw : vis the same gates; the merge only adds nets). After synthesis expands the loop, the slices and splices these fold to take a colored neighbor's region (pass/synthloop_cleanup.cpp): uncolored, they formed a color-0 wiring region that handed every state bit back to ABC as a fresh input (br_arb_lru mapped 2x larger than the loop-free form). - Bit reads
v#[p +: w]at a runtimepstayget_mask(v >> p, 0, w): pass.abc builds only the demanded prefix of that shift (a W:1 select per bit) and the cost model charges the same, and a constantpfolds it to a slice. - Tuple invariants. A tuple-valued name the body reads only through
constant fields (
s.sel#[i]of a child instanceconst s = sub(..), a dottedt.aof a tuple local) is not one port: each field read becomes an invariant port of its own (s__sel, typed by the instance's output port or the field's facts) or a captured constant, the call reads the field in front of the loop (tuple_get(tmp, s, 'sel'), or the dotted name), and the lifted body's copy reads the port where the source read the field (tuple_get(d, s, 'sel')->store(d, s__sel)) -- the same hardware as hoistingconst sel = s.selby hand, and a nested loop sees a typed port (Loop_roll_plan::tuple_invariants,constant_field_reads). A single-output handle used to cross as a scalar and leaves.selundriven in the body; a multi-output one declined the roll and silently unrolled. - Out-of-range accesses. An unrolled iteration indexes with a constant,
so
arr[i + 1]past the array's extent orv#[i*3 +: 3]past v's declared storage is a compile error there; the lifted body sees only the index port's range. The roll planner's exact per-iteration walk (eval_carry_ranges, loops of at most 4096 iterations) therefore probes every element read/write of a zero-based one-dimension array and every bit write into a declared variable whose index evaluates to a constant, and reports the unrolled diagnostic (array-index-out-of-range,bit-range-overflow, the iteration in the hint) when the access is reachable: arms whose condition is comptime false here, and code after a comptime-takenbreak/continue/return, are skipped; an access under a runtime condition (one reading a runtime input, or written under one) is judged, as the unrolledifarm is. A condition the walk cannot decide but that may be comptime once unrolled (a call, a tuple read, a promoted index) silences the probe for what it guards -- a missed report, never a false one (Loop_range_eval::Oob_access). - Result ranges. The values a rolled loop produces are bound in the
hidden payload, which the plugins do not walk, so each result's range is
published by the runner: every value the loop can leave with
(
eval_carry_ranges), else the declared type. Without abreak/continuethat is the last iteration's carry-out; with one, the loop may leave after ANY iteration, so it is the join of every iteration's carry-out (each already joining that iteration's exit points) -- the last iteration's alone made abreakloop'sacclook like one value. Without a published range a later read was judged by the PRE-loop value (mut v:U10 = 0): a narrowing write went unreported and a neededwrapread as unnecessary, so what compiled depended on compile.unroll. - Runtime
#sext.x#sext[lo..=hi]with loop-index bounds has a runtime sign positionhi - lo; tolg lowers it with shifts ((x & ((2 << p) - 1)) - (x[p] << (p + 1)),pclamped to x's width) that fold to theSextcell's slice oncepis constant. A position is constant only from the operand itself (a literal, or a windowhi - loof structurally constant width), never from a published range alone, and the shifts and the clamp are sized from what the position's pin can hold: a range is only as sound as its derivation, and a one-value range must not hard-wire a sign bit. - Linear planning. upass must stay O(N): the planner walks a loop body
once per CLASS of names, never once per name (
constant_field_reads,body_must_write), and what lies outside the body comes from per-tree indexes built once: "written before this loop" and "read by a later loop domain" from a preorder index (Loop_tree_order: a name's stores and the domains reading it, by position and scope), a typed name's declaration from its declaration sites (decl_sites_of) -- never a walk of the definition per name or per loop (tests/loop_roll_linear_test.sh in upass/runner).
uPass_ssa::run runs once over each LNAST before the main runner
(pass_upass.cpp::work) and always harvests port names/widths into
lnast->io_meta(). Generated scalar LNASTs with only straight-line repeated
definitions keep the parser/extractor tree: the runner versions each scalar
definition and rewrites its later uses while streaming. Static tuple-port
accesses similarly become direct dotted scalar bindings in the runner, so a
composite signature alone no longer forces a compatibility copy. (reg and
wire names are never SSA-versioned; they carry state/net identity.)
The old rebuilding transformer remains the conservative fallback for stale
private SSA names, dynamic or whole-tuple port operations, and hand-written
Pyrope requiring control-flow SSA. upass.ssa_stream=false forces that path
for differential testing. Both paths must lower equivalently; large generated
designs are checked with LGraph LEC when this boundary changes.
upass owns Pyrope's basic typesystem. The rules are declaration-driven: a
value's size envelope and nominal identity come from the declared type (or a
literal's implied type). The one exception is .[bits] of an untyped
comptime integer, which is derived from its value (below).
- Size envelope (
bits/max/min) comes from the declared type::U<N>/:S<N>set width and range;:Boolis the hardware U1 envelope (min=0, max=1, bits=1, never signed);:Stringhas no numeric envelope (readsnil). When onlymax/min(orrange=lo..=hi) is pinned,bitsderives on demand. Unannotated → all three readnil; a baretrue/falseliteral is auto-typed:Bool. - Untyped comptime integers (user ruling 2026-09-27 (6)):
.[bits]of an untyped comptime integer (acomptime const, a const whose value is known, a generic bound to a literal) is the minimal width holding its value (13 -> 4,0 -> 1, a negative value -> its signed width,-4 -> 3);.[max]/.[min]staynil. A typed value keeps its declared width, even unbounded (Z:Unsignedreadsnil), and so does a generic bound to a typed constant (f<N=W>withW:U8reads 8). An untyped runtime value readsnil.upass::value_bits/upass::range_bits(core/range_bits.hpp) are the two formulas; the attributes pass, the runner's template-bound fold and prp2lnast's generic-default fold all call them. std.clog2(x): the built-instdnamespace needs no import. prp2lnast lowersstd.<member>(args)to a call ofstd.clog2. An unknown member, a barestdread, a lambda/type/enum/import alias namedstd, and astd.<member>call where a localstdhides the namespace are errors.upass::std_clog2(core/range_bits.hpp) is Verilog$clog2forx >= 1and has three consumers: constprop's fold (an error forx <= 0, a non-integer, or a runtimex), the runner's template port-bound fold (Unsigned(bits=std.clog2(N))on a generic port), and prp2lnast's type-bound fold (type bounds and generic defaults).- Typed
~(user ruling 2026-09-28 (26)):~xon an UNSIGNED-typed operand of width N flips those N bits ((2^N - 1) - x, a U); on a signed or untyped one it is-x - 1. Unsigned-typed means typed by a declaration or type_spec of its own (a variable/port/reg declared with an unsigned type -- N is its.[bits], soUnsigned(max=5)flips 3 bits -- a slicex#[..]at any position, aU<N>(...)cast temp, an element readarr[i]of a one-dimensional[N]U<W>array, a tuple field or instance output whose entry carries a U), or a~/&/|/^over such values. A NAME bound without a type (const t = x#[..],mut m = w) is untyped even when its value is typed (declared_typed_, dropped again by an untyped declaration in a sibling scope); an untyped template-comb input takes its argument's type in each specialization, as its.[bits]does. The runner makes the choice once (dispatch_bit_not) and re-issues the node in the TYPED LNAST formbit_not(dst, x, N); constprop, bitwidth and the loop planner read N off the node, tolg lowers it to the existingNotplus aGet_maskof N bits (no new cell), and prp_writer spells it back (~xonly when x's emitted declaration prints:U<N>, else~x#[0..=N-1]). A Verilog-read unit is never retyped: inou.slang already emits the typed form at Verilog's context width for an unsigned result and the plain-x - 1for a signed one. Test blocks (inou/prp/prp_sim.cpp) apply the same rule to their own locals, file consts, DUT fields, casts, slices and bitwise expressions. - Aggregates have no
.[bits]— only scalars. Per-fieldt.a.[bits]resolves when the field carries a typed annotation. sizeis cardinality, not bit width (tup.[size]= entry count,str.[size]= character count).typenameis diagnostic-only, set fortype Name = …declarations; structural==ignores it; nominal identity isis's job (p is Foofolds iffp.[typename] == "Foo").- Comptime is non-sticky on copy. A
mutbinding holding a known value does not read as comptime; onlyconst-decl (resolved) or an explicitcomptimemarker does.
Implementation: declared facts are typed Entry/Bundle fields written by
the runner's declare/type_spec bake (kind, decl_max/decl_min, comptime,
mode, type_name; per-field facts ride entry copies through construction and
back-flow from typed-literal extraction tmps via Symbol_table::tget_origin;
bundle-valued fields carry mode/comptime as fmode/fcomptime field attrs).
The single derivation is upass/core/decl_facts.hpp (entries + field attrs +
the pending dotted-decl stash + io_meta ports + the explicit [bits=N] attr);
uPass_attributes::lookup_type_info and the runner/constprop type queries all
delegate to it. derive_max/derive_min/derive_bits are pure functions of
that answer plus explicit attr values.
Walk the dest LNAST after the source walk completes; they see no symbol
table. Casserts are emitted with their cond simplified (const(true),
const(false), or a surviving ref):
| disposition | trigger | counter |
|---|---|---|
| known-true | cond is const_true |
pass_count |
| known-false | cond is const_false |
fail_count |
| unknown | cond is a surviving ref or unknown const |
unknown_count |
Comptime-false cassert → upass::error unless the test header expects it.
verifier_pass:N / verifier_fail:N labels set expected counts (aggregated
across func_extract-spawned lnasts); mismatch raises upass::error.
prplib.py reads :verifier_pass:/:verifier_fail: from the .prp header.
Test mode split (driven by prplib.py): :type: upass = pipeline smoke
test (verifier:false); :type: comptime = correctness check, verifier on.
When multiple pass.upass invocations exist (e.g. around an unresolved
import), the finishers attach only to the final one — deferred while
pending imports remain (§8).
Symbol_table (upass/core/symbol_table.{hpp,cpp}) is owned by the
runner (uPass_runner::symbol_table_) and shared with every pass via
set_runner_symbol_table — one table, one scope stack, per walk. The runner
owns every scope transition: function_scope at run(), block_scope
push before dispatching process_stmts, pop after process_stmts_post,
uncertain-arm marking at the if dispatch.
- One
shared_ptr<Bundle>per live name (Scope.varmap: absl::flat_hash_map<string, shared_ptr<Bundle>>). - Scope kinds:
Function,Block,Always,Conditional(symbol_table.hpp:18);block_scope(key)frames are re-entrant (sameScopeobject recovered on re-entry). Every{ }notifies the table; reads walk innermost → outermost; writes land in the declaring scope. - COW value semantics: whole-bundle assignment shares the
shared_ptr; in-place field mutation un-shares first (unshare_for_write,use_count()>1→ clone). Re-fetchget_bundleafter writes. - If-arm contract: mark-uncertain + invalidate-on-exit
(
symbol_table.cpp:282-357). A declaration inside an arm lives in that arm's scope and dies at}. A write to a name declared in an enclosing scope under a runtime-uncertain condition invalidates that name's value fact on arm exit. There is no frame-per-arm merge — the both-arms-write-the-same-constant fold is deliberately not attempted. - Function scopes are WRITE barriers but READ-transparent:
find_decl_scope(the write/anchor variant) stops at the nearestFunctionscope — a callee body cannot mutate the caller's locals, and a fresh write anchors inside the function — whilefind_decl_scope_readcrosses the barrier, so a callee body walked on the shared table reads outer comptime consts directly (closure capture without side maps).___Ntmps anchor at the Function scope from EVERY entry point (setanddeclare_bareagree — two shadowing bindings in different scopes was a real bug class). - Name facts vs value facts. Declared identity (mode, type_name, kind, decl envelope, residual attrs incl. bind-tracking) rides the NAME: slot replacement preserves it, with the declared facts WINNING over anything riding in on the incoming value bundle (an S6-typed param bound to an S4 actual keeps its declared S6). Values and derived ranges ride the VALUE.
The comb-call inliner is runner-owned (task 1i; design rationale and
literature refs in the header comment of
upass/runner/upass_runner.cpp). The runner
maintains a splice stack of callee LNASTs (active_inline_callees_),
synthesizes param = actual bindings at the body head so the passes see
normal assigns, clones the callee per call site (fresh fold context each
time), and caps recursion depth per callee. Lnast_manager frames
(frames_, tmp_remap_, intern_pool_) keep inlined names stable and
___N tmps collision-free. Vararg callees resolve args[i]/args.NAME
directly; pipe/mod templates specialize per signature into a Sub (task
1p). Passes are unaware they are inside an inline.
Each inlined param and output is typed from its declaration: a literal type
as written, a generic-WIDTH bound (a:Unsigned(bits=N * 4)) folded under
the call's generic binds exactly like a mod specialization (never the
actual's width), and an untyped param adopts the actual's declared type (an
io port's exact range, also past an i64). A bound folds literals, generics,
captured comptime consts and a.[bits|max|min] of an input's declared
type; a generic it needs that nothing binds, defaults or infers is
fcall-generic-arity. Specialized clones match each io port to its io_meta
slot by NAME (a tuple port is flattened there into its leaves).
A defaulted comb input (b:U8=3) does not make the comb a template: only an
untyped input or a generic does. Its default is a body-prologue store into
the Lnast_io_entry::default_value_name() local (__default_b), never into
the port. The comb's own module reads port b (the local is dead there, but
the standalone walk keeps its store like an output driver, so the published
body still carries it); the inliner skips that store for a PROVIDED b and,
for an omitted one, walks it and binds b from the local. A unit restored
without SSA re-harvests has_default from the io node's __default slot.
Every call checks its actuals against the parameters' DECLARED types once,
before it splits into inline / Sub / specialize (check_call_args_fit): an
argument never narrows implicitly (fcall-arg-overflow, "argument a
(range [0, 65535]) in call to low4 may not fit its declared range
[0, 15]"), and a wider integer into a Bool input is the same error. The
overload probe (signature_matches) applies the same containment, so a
runtime U16 skips f(a:U8) for f(a:U16) instead of erroring.
Bundle (upass/core/bundle.{hpp,cpp} since the 1b landing 2026-06-09) is
the comptime value/tuple record threaded through the passes: a data map
(tuple leaves; the bare-scalar leaf lives in an inline root Entry — zero map
nodes for scalars, spilled on whole-map views), a residual attrs map (bare
names, sticky = leading _), and typed pass-fact fields on Entry
(trivial/decl_max/decl_min/bw_max/bw_min/kind/mode/comptime)
and Bundle (mode/type_name/value_kind). Point lookups and prefix
runs are find/lower_bound-bounded; non_attr_entries()/get_attrs()
are zero-copy map references. Bundles carry no name; the table key is the
identity (the runner passes names to hooks for diagnostics, dump() takes
one). A fact-only entry is impossible to store safely: any non-attr
entry reads downstream as a value claim (an invalid trivial = runtime
unknown), which is why declared facts for io ports stay in io_meta, the
dotted-decl stash exists, and declare_bare creates truly-empty bundles.
Value ops dispatch push-based:
Vote process_<op>(std::string_view dst_name, Bundle& dst, Src_span src)
(upass/core/upass_core.hpp, PROCESS_NODE_PUSH). The runner resolves the
operands once per node (resolve_node_operands): dst = the live table
bundle (COW-unshared; a throwaway when unbound — the first write installs
it), src = one Operand{name, bundle, pattern} per child in order (const →
make_const with the parsed value and seeded kind; 0sb/0ub bit-pattern
literals set pattern = force semantics; ref → table bundle or an empty
view; subtree → placeholder). Vote = keep|drop is the emit decision
channel. Control/structure hooks (if/stmts/range/attr_set/attr_get/
tuple_get/declare/type_spec/func_call/…) remain cursor-based nullary
virtuals; a push hook may also walk the cursor when its payload includes
subtrees (named-field stores, does-operands) — dispatch_push saves and
restores the cursor around every call.
storeis part of the push surface; each pass'sprocess_storeroutes ≤1-src to its scalar-assign body and field-path forms to its tuple_set body. (assign/tuple_setLNAST nodes were deleted in task 1t —storeis the single write node.)declare/type_specfirst run the runner's bake pre-step (writes kind/decl envelope/comptime/mode/type_name onto the dst binding; dotted dsts write the root's field entry or the pending stash; extraction tmps back-flow to the source field viatget_origin), then dispatch.
Cross-pass facts flow through the table — there are no pull seams. The
one surviving callback is runner_emit_at_fn (the coalescer's
materialize-at-use replay). uPass_runner::try_fold_ref is a direct
Symbol_table::known_const_scalar read (strict gates: no unknowns, and
only a trivial scalar inlines — a multi-entry tuple or named 1-tuple never
inlines its position-0 value). Declared-type queries go through
upass/core/decl_facts.hpp; call/import resolution through
upass/core/call_resolver.{hpp,cpp} (callee name lookup, actual
collection, import → namespace bundle on the dest).
The runner emits into a staging tree (staging, dest_forest_) as the
walk leaves each source node (emit_push/emit_pop). Per node, the drop
decision combines:
- Push votes — constprop votes drop when the dst's table state proves
the statement redundant (its private
classify_statement_implevaluation); the coalescer votes drop when it parked the statement (one-shot flag, replayed later at first use viarunner_emit_at_fn). - Region verdicts — the
classify_statementvirtual survives for the two passes whose drops are not per-op-shaped: the verifier (cassert discharge: known-true → drop + tally, known-false → error; func_call classification) and func_extract (statements inside virtualized bodies). - Runner-derived dst-drops on the legacy drop-candidate ops (func_call/tuple_get): a fully-known trivial-scalar dst that is not reg/mut-declared means every consumer folds the value. cassert has no dst (child 0 is the condition) and always emits.
On emit, ref operands are folded through try_fold_ref so known values
materialize as const. After the walk, post-walk DCE sweeps the staging
tree (io-root liveness rule), and the staging tree replaces the source
LNAST.
Unresolved imports are tracked by constprop statics (pending_imports_;
ambiguous_units_ for multiply-defined units) rather than per-Bundle
markers. The kernel iterates pass.upass until convergence with whole-file
retry (task 1m): an invocation that still has unresolved imports defers the
verifier/assert finishers; the next invocation rebuilds the symbol table
fresh and re-attempts. Generic, un-inlined function bodies have untyped
inputs ⇒ no envelope ⇒ no overflow check; they are realized only by inlining
into a caller, where the concretely-typed copy is checked.
These must hold after every walk:
- Every ref in the dest LNAST is defined — by an emitted assignment, a
port, a register, or folded to
constat emit time. No dangling refs. - Regs are never dropped. Reg assignments carry timing; constprop may fold their RHS but not elide the assignment.
- Ports are preserved at the module boundary — input ports read, output ports written — even when a constant flows through.
- Deterministic emission order. Children are emitted in source-tree order; the dest LNAST is a topologically-consistent rewrite, not a re-scheduled one.
delay_assignis emitted verbatim; upass never constant-folds across one regardless of symbol-table state.- Only
bitwidthderives value ranges; nothing else folds on them.max/minare derived exclusively bybitwidth(last opt pass) and consumed only bylnast_to_lgraphviabw_meta. bitwidth is the sole owner of overflow (range-vs-declared-envelope) errors. - Spawned LNASTs are self-contained. Outer-scope comptime values are inlined at the use site before func_extract spawns the callee body; spawned LNASTs share no symbol-table state with their caller.
- Single sweep per source node. Exactly one walk per invocation; no iteration knob, no fixed-point loop.
- Canonical bare ref text. Symbol-table keys assume
$/%/#prefixes are already removed. Legacy prefixes frominou/pyropeare producer bugs, not alternate spellings. Const::invalid()is overloaded. It stands for both "not tracked" and "tracked but unknown". When 1b's typed fields land, revisitis_invalid()call sites in constprop to confirm each still means "don't fold".storefans out to two dispatch methods (§6). The LNAST nodesassign/tuple_setno longer exist (task 1t) —storeis the single write node — but the upass layer still dispatches 2-child stores toprocess_assignand 3+-child stores toprocess_tuple_set. Any semantic check a pass runs on the LHS ofprocess_assign(const-rebind tally, type/bitwidth propagation, wrap/sat narrowing) must also fire fromprocess_tuple_seton the same root —a.b = 1arrives as a field-path store, and a check living only on theprocess_assignpath is silently bypassed. Nil-rvalue stores are invalidation, not a binding — exclude from bind tallies. Canonical example:uPass_attributes::process_tuple_setcallsrecord_assign(target, rhs_is_nil)(upass/attributes/upass_attributes_tuple.cpp:272).- Cursor discipline. Cursor-based hooks (and push hooks that walk
subtree payloads) must restore the cursor before returning — fold helpers
may move it.
dispatch_pushsaves/restores around every push call as a backstop. - Aliases share table slots. Whole-bundle assignment shares the
shared_ptr; attrs, entry facts, and shapes ride the share and survive COW clones — there is no alias chase. The flip side: never mutate a shared bundle withoutunshare_for_write(and copy-before-emplace aroundabsl::flat_hash_maprehashes — element moves invalidate references, unlikestd::unordered_map). - Two poison flavors. A truly-EMPTY bundle (fresh
declare_bare) means "declared, no info". An entry with an INVALID trivial means "tracked but runtime-unknown" — storing declared facts as a fact-only entry turns a port into a runtime-unknown VALUE claim (mod varargs became 65-bit unknown constants this way). First-write gates must testget_trivial(name).is_invalid(), not entry existence.
a and b or c (mixed distinct operators at one precedence level without
parens) has no defensible associativity. prp2lnast lowers it as a silent
left-fold with a bare print. The core/diag channel now exists and prp2lnast
emits located compile errors elsewhere (scope checks, decl-init kinds), so
the remaining work is just turning this case into a proper located error.
Also applies to a implies b or c and any future mixed-operator tier the
grammar permits but the language prohibits.
- todo/livehd/1d.html — sea-of-nodes demand-driven emit (unblocked: the 2b flag-day landed 2026-06-10; the per-name Bundle is the natural home for the "consumed" bit).
Landed milestones formerly tracked here: the 1b Bundle/Entry reshape
(2026-06-09) and the 2b push-dispatch flag-day (2026-06-10: runner-owned
scope-aware symbol table, push hooks + votes, bake, decl_facts,
Call_resolver, every pull seam and pass-private side map deleted, bw-range
soundness invariant); earlier: Handler_registry dispatch-vector fix,
Cursor_state save/restore, the bitwidth relocation (goal 1n).