perf(driver): scope lowering invalidation per unit

[ghaith]

Drafted by Claude (Opus 4.7). Reviewer judgement applies as normal.

Why this PR exists

Today every lowering participant that mutates the AST follows it up by
re-indexing and re-annotating the whole project, even on a clean
full build. That makes the wall-clock cost of parse → index → annotate dominated by redundant re-passes inside the participant
chain. It's also the structural blocker to ever making incremental
rebuilds work.

This branch reshapes the lowering pipeline around per-unit invalidation
deltas, drops the redundant re-passes where the participant can prove
it didn't touch anything, and lays down the infrastructure (unit
provenance, reverse-dep graph) that a future LSP / incremental driver
will consume.

It is intentionally posted here as an RFC-style PR — I'd like
feedback on the API shape before landing. See the "Open for review"
section at the bottom.

Where the win comes from

The savings stack from three sources, in rough order of contribution:

• Precheck gates on each lowerer. When the project has no
  properties, no RETAIN, no aggregate-returning POUs, etc., the
  corresponding participant returns early instead of doing a
  whole-project re-index / re-annotate.
• Per-unit re-index after participants that only mutate a known
  subset of units. The polymorphism table pass, the retain
  rewrite, and the array-literal rewrite each re-index just the
  units they touched rather than the whole project.
• Partial re-annotation after signature-rewriting passes.
  AggregateTypeLowerer (and any future signature-rewriting lowerer
  using the UnitLowerer adapter) re-annotates only the closure of
  units that depended on the rewritten signatures, using a
  reverse-dependency graph built from the resolver's existing
  Dependency set. Signature changes are tracked per-POU, so body
  edits don't ripple to callers of unrelated POUs in the same unit.

Projects vary in how much each lever fires — projects with no
polymorphism, no aggregate returns, and no retain variables see most
of the wall-clock saving. Polymorphism-heavy projects still pay a
full re-index + full re-annotate in
PolymorphismDispatchAdapter::post_annotate (the clearest next
target after this PR).

PLC_TIMING=1 plc --check ... reports per-phase timings if you want
to measure on a local project.

What's in the PR, step by step

The branch reads cleanly commit-by-commit. Each conventional-commit
subject covers one slice; the bullets below summarise what each slice
does and why.

1. Per-phase pipeline timing

A new PhaseTimer RAII guard wraps the four top-level pipeline phases
and every participant invocation. Enabled by PLC_TIMING=1; logs to
stderr with nesting indent. No behaviour change when disabled
(PhaseTimer::new_with(|| format!(...)) defers label allocation
until the env var is set, so the instrumentation doesn't perturb the
disabled baseline). Documented in
book/src/development/phase_timing.md.

2. Per-unit symbol ownership on Index

Adds a UnitSymbolIndex side-table on Index mapping UnitId → Vec<OwnedSymbol>. Index::import_with_unit(unit_idx) tags the
imported entries; Index::remove_unit(unit_idx) drops every entry a
specific unit contributed (POUs, globals, types, implementations,
enum globals, initializers).

Shared entries (auto-generated POUs and implementations whose names
collide across compilation units) are reference-counted via
UnitSymbolIndex::has_owner_other_than: every importer records a
stake, and remove_unit only drops the underlying entry when the
last owner is removed. Without this, the first removal of a shared
entry deletes it and orphans the remaining units' ownership rows.

The side-table approach was chosen over adding a unit_id field on
every entry struct: there are ~344 entry-construction sites in the
indexer and a per-entry field would force them all to thread an ID
through. The side-table is one new field on Index and one
construction site per import. Tradeoff: an OwnedSymbol { kind, map_key, identifier } indirection per entry instead of a direct
field.

UnitId sentinels: BUILTIN, SYNTHETIC (for the resolver's
new_index), UNTAGGED (for legacy code paths during the
transition). UnitId::source_index() -> Option<usize> is the typed
accessor for places that previously paired is_source() with
raw() as usize.

3. Reverse-dependency graph

ReverseDependencyGraph inverts the per-unit
FxIndexSet<Dependency> the resolver already collects into
symbol_name → Set<UnitId>. Lets partial re-annotation compute the
"who used the symbol before its signature changed?" closure.

The closure is correct only if the resolver records a Dependency
for every cross-unit reference — including implicit ones through
interface dispatch and vtable indirection. The contract on which
resolver paths must record a Dependency (and which paths are still
open risks — cross-unit generic monomorphization is the documented
gap) lives in book/src/development/reverse_dependency_graph.md.

4. Precheck gates on each participant

The most-broadly-applicable near-term win. Each participant that
previously unconditionally re-indexed / re-annotated the whole project
now first asks a cheap index predicate (has_any_properties, no
RETAIN, etc.) or a bool from the lowerer's visit. If the answer
is "no work", the implicit whole-project re-pass is skipped.

Touches: PropertyLowerer, InheritanceLowerer, ArrayLowerer,
RetainParticipant, PolymorphismLowerer, LoopDesugarer.

5. Per-unit re-index after polymorphism table

PolymorphismLowerer::post_index previously re-indexed the whole
project after generating vtable types. Now it tracks which units the
table generator touched and only re-indexes those.

Adds Index::reindex_unit(unit_id, &mut unit) — calls
pre_process(unit) to mirror ParsedProject::index, removes the
old entries, imports the new ones.

6. Partial re-annotation after AggregateTypeLowerer

The biggest single behavioural change in the chain. After the
aggregate-return rewrite mutates a unit's POU signatures, only the
units in the reverse-dep closure of those signatures are
re-annotated; the rest reuse their existing annotations.

Adds AnnotatedProject::reannotate_units, the closure builder, and
runs evaluate_constants after the partial reindex (the new
VAR_IN_OUT parameters can have STRING[K+1]-style sizes that need
const-folding).

This is the change with the largest behavioural surface; end-to-end
checks are the new cross-unit lit tests (see Verification).

7. Per-unit re-index for Retain + Array

Same pattern as step 5 applied to the two smaller lowerers. Uniform
shape across all bool-returning participants.

8. LoweringBookkeeper helper

Extracts the recurring "track mutated units, track signature changes,
compute closure, run reindex + evaluate_constants + reannotate"
sequence into a LoweringBookkeeper with two terminal methods:
apply_to_indexed(IndexedProject) and
apply_to_annotated(AnnotatedProject). Participants build a
bookkeeper and hand it the project; the orchestration lives in one
place.

9. UnitLowerer trait + AutoLowerer adapter

API ergonomics for new lowerer authors. A UnitLowerer trait whose
lower_unit returns a UnitChange { mutated, signature_changed };
AutoLowerer<T> adapts a UnitLowerer into a
PipelineParticipantMut by walking the units, collecting changes
into a LoweringBookkeeper, and applying it. The author writes one
method per unit; the bookkeeping is automatic.

10. UnitLowerer::prepare for two-pass lowerers

Some lowerers need a project-wide context-gathering pass before they
can rewrite a unit (the polymorphism dispatch table is the
motivating case). prepare(&mut self, ctx) runs once before the
per-unit lower_unit loop; default implementation is a no-op.

11. ArrayLowerer migrated to UnitLowerer

Smallest migration — used as the canary for the new trait. No
behaviour change.

12. PolymorphismLowerer table migrated, with shared instance

The polymorphism participant has two hooks — a post_index table
pass that emits vtables/itables, and a post_annotate dispatch pass
that consumes them. Both must see the same PolymorphismLowerer
state (vtable instance names hashed with source path, IdProvider
sequence, etc.) or the dispatch half emits constructor bodies missing
__vtable__ctor(self.__vtable) for symbols the table half generated.

The two hooks are now wired through an Rc<RefCell<PolymorphismLowerer>>
shared between the post_index adapter (a UnitLowerer) and the
post_annotate adapter (a PipelineParticipantMut). The pattern is
documented as the recommended shape for future two-hook participants.

13. Writing a lowering pass — book chapter

A new book/src/development/writing_a_lowerer.md walks through five
patterns for new lowerers: pure-AST, signature-changing,
two-pass-with-prepare, full-PipelineParticipantMut (when the
trait isn't enough), and shared-state via Rc<RefCell<...>>. Worked
examples for each.

14. AggregateTypeLowerer cleanups

Two related cleanups:

• The AnnotationMap::into_any_box trait method existed only to
  round-trip a Box<dyn AnnotationMap> back to a concrete
  AstAnnotations. The field is now Option<AstAnnotations>
  directly; the trait method and its two impls are gone.
• The hand-incremented mutations: usize counter is replaced by a
  MutationTracker that distinguishes body mutations (statement
  inserts) from signature rewrites. The visitor's mutation
  primitives (push_pre_statement, push_post_statement,
  signature-rewrite in visit_pou) call touch() /
  signature_changed(pou_name) themselves. The call site no longer
  has to remember to bump anything, and the per-POU recording means
  the partial-re-annotate closure only invalidates callers of POUs
  whose interface actually changed — not every POU in the touched
  unit.

Verification

• cargo test --workspace --lib — all lib tests pass.
• cargo xtask lit — full lit suite passes. Cross-unit regression
  tests in tests/lit/multi/ cover the paths this PR depends on:
  • cross_unit_aggregate_signature — STRING-returning function
    called across a unit boundary; verifies the partial-re-annotate
    closure picks up direct cross-unit calls.
  • cross_unit_polymorphism_dispatch — base→derived vtable
    dispatch across units; verifies the polymorphism table pass
    leaves both vtables wired up.
  • cross_unit_interface_dispatch_signature — interface method
    with aggregate return implemented and dispatched across three
    units; verifies the reverse-dep closure covers the
    interface-dispatch path.
  • cross_unit_vtable_ctor_in_member — Wrapper holding
    Derived as a member, dispatched via POINTER TO Base aimed
    at the embedded member; guards against a missing
    __vtable__ctor chain when the member's vtable lives in a
    different compilation unit than its consumer.
• cargo fmt --all clean.
• cargo clippy --workspace -- -Dwarnings clean on the CI toolchain
  (Rust 1.93.x). Newer local toolchains surface a couple of
  pre-existing needless_lifetimes lints in
  src/resolver/tests/resolve_expressions_tests.rs that are unchanged
  from master.

Open for review

Specific things I'd appreciate input on before this lands:

1. Side-table vs per-entry unit_id. The UnitSymbolIndex
   trades indirection for migration cost. If reviewers prefer the
   per-entry field shape, the migration is mechanical but ~344 call
   sites.
2. UnitLowerer vs LoweringBookkeeper as the recommended
   author surface. They coexist on purpose — LoweringBookkeeper
   is the substrate for unusual participants, UnitLowerer is the
   shorthand for the common case. Discoverability could be better.
3. MutationTracker body-vs-signature split. Signature changes
   are recorded per-POU; body mutations only mark the unit dirty.
   If reviewers prefer AST-level dirty flags or snapshot-and-diff,
   easy to revisit.
4. PR size. Fourteen commits, grouped by intent (instrumentation
   → infrastructure → per-step perf wins → API ergonomics → cleanup).
   If reviewers would still prefer it split, the natural fault lines
   are:
   • PR1: instrumentation + per-unit provenance + precheck gates
     (steps 1–4) — fast, bit-identical, no API surface changes.
   • PR2: partial re-index + re-annotation (steps 5–8) — the
     biggest behavioural surface, needs the most review.
   • PR3: API ergonomics + cleanup (steps 9–14) — refactor only.
5. Future work, intentionally not in this PR: in-process
   incremental driver (the LSP-ready piece), on-disk cache,
   applies_to precheck on UnitLowerer, evaluate_constants
   scoped to a delta, partial re-annotate inside
   PolymorphismDispatchAdapter::post_annotate (currently still
   does a full re-index + full re-annotate when polymorphism is in
   use; the clearest next target).

Test plan

• cargo test --workspace
• cargo xtask lit
• cargo fmt --all clean
• cargo clippy --workspace -- -Dwarnings clean on Rust 1.93.x
• Spot-check PLC_TIMING=1 plc --check output on a local
  project; confirm the trace lines indent sensibly and no
  participant logs a nested whole-project index /
  annotate it shouldn't.

🤖 Generated with Claude Code

[github-actions]

Build Artifacts

🐧 Linux

Artifact	Link	Size
deb-x86_64	Download	38.5 MB
schema	Download	0.0 MB
stdlib	Download	32.4 MB
plc-x86_64	Download	43.7 MB
deb-aarch64	Download	30.9 MB
plc-aarch64	Download	43.6 MB

From workflow run

🪟 Windows

Artifact	Link	Size
stdlib.lib	Download	4.3 MB
stdlib.dll	Download	0.1 MB
plc.exe	Download	38.5 MB

From workflow run