SourceRef and lattice primitives

[iangneal]

Summary

Adds the SourceRef and lattice primitives required by the remaining aggregate analyses without introducing Circom-specific behavior. This is PR 1 of 6 in the stacked series.

Related issues

No standalone issue; this is the first independently validated slice of the Circom analysis handoff.

Changes

• Preserve array shape through bottom joins and expose array-shape access.
• Add element/subarray writes, prefix replacement, removal, and SourceRef::narrowRanges().
• Print the first block argument of a struct @constrain function as %self; other function and nested SCF block arguments retain their existing names or %arg… fallback.
• Model global reads as ordinary rooted SourceRefs; immutable globals remain distinct from template constants.
• Add self-overlap handling and deterministic comparison fallback.
• Add focused API and output regressions in a dedicated unittests/Analysis/SourceRefTests.cpp, including multidimensional/ranged writes, unmatched-prefix preservation, constrain-self spelling, nested SCF fallback, and immutable-global classification.
• Add changelogs/unreleased/iangneal__source-ref-lattice-primitives.yaml.

Testing

• git diff --check
• Dedicated SourceRefTests unit suite and six affected analysis/FileCheck tests
• nix build -L on this exact commit: 371 lit tests and 1,308 unit/CAPI tests passed

Submission checklist

• If I am an external contributor, this PR has a linked issue marked approved; otherwise, this does not apply.
• I added or updated tests for all relevant behavior, or explained above why tests are not needed.
• I updated the relevant TableGen or other documentation, or explained above why documentation is not needed.
• I added a changelog entry describing user-visible changes. (create-changelog in the Nix development shell creates a template.)
• I enabled Allow edits from maintainers if this PR comes from a fork.

AI assistance

• No AI tools contributed to this PR.
• AI tools contributed to this PR.

Tools used: OpenAI Codex.

How the tools contributed: Codex helped partition the original working-tree change, preserve dependency ordering, add focused regressions and changelog entries, and prepare this draft PR.

How I verified the contribution: Reviewed the isolated diff and ran git diff --check, the focused analysis regressions through the project test suite, and nix build -L on this exact commit.

[github-actions]

Test Results

0 files   -   2  0 suites   - 2   0s ⏱️ - 10m 16s
0 tests  - 371  0 ✅  - 367  0 💤  - 4  0 ❌ ±0 
0 runs   - 742  0 ✅  - 734  0 💤  - 8  0 ❌ ±0 

Results for commit d77528c. ± Comparison against base commit 5a013d1.

♻️ This comment has been updated with latest results.