[paracycle]

This aligns Rubydex's constant resolution with CRuby in nine places. Fixes #1073. Each commit fixes one behaviour and adds tests that fail without it, for both indexer backends, plus a note in docs/ruby-behaviors.md.

The gaps came from comparing Rubydex with a formal model of CRuby's constant lookup (ported from vm_get_ev_const, rb_const_search and rb_const_search_from). Every case was then checked against real Ruby (4.0.9). On that differential suite, the number of probes where Rubydex and CRuby agree goes from 78 of 103 to 96 of 103. The remaining 7 are intentional; see below.

Changes

Commit	Ruby behaviour	Before
Check a namespace's own constants before its prepended modules	rb_const_search_from reads the starting namespace's own table first, so with class C; prepend P; X = 2; end, C::X is C::X	P::X
Stop qualified constant lookups at Object	Foo::TOP raises NameError: a qualified search stops when the first owner is Object itself, unless it started at Object. Kernel/BasicObject constants past Object are still found	resolved to ::TOP
Report constant paths that reference private constants	Only :: enforces private_constant, even inside the class (Foo::PRIV in class Foo) and for ::PRIV. New PrivateConstantReference warning; the reference still resolves, so navigation keeps working	no diagnostic
Include top level mixins into Object	A top level include M is main.include, which includes M into Object	M's constants unresolved
Treat ||= constant writes as conditional definitions	VERSION ||= "2" in a subclass of a class that defines VERSION defines nothing	declared Child::VERSION
Make the last assignment the primary target of a reassigned alias	X = A; X = B; X::C is B::C	A::C
Resolve self::X directly in namespace bodies	In a class, module or singleton class body, self::X is Foo::X	dynamic reference
Don't resolve a superclass to the class being defined	In module GSD; class ApplicationRecord < ApplicationRecord, the superclass is evaluated before the class exists, so it is ::ApplicationRecord (#1073)	GSD::ApplicationRecord itself
Apply built-in mixins before user mixins when linearizing	class Object; include M; end gives [Object, M, Kernel, BasicObject]: the VM includes Kernel before any code runs	[Object, Kernel, M, BasicObject]

A follow-up commit refines the ||= change: when the existing constant is only defined later in the same file, the ||= still defines a new constant, because Ruby runs defined? at that point.

Design choices worth a look

• Top level include is recorded as a synthetic reopening of Object: a ClassDefinition at the include call site, carrying the mixins. This reuses the existing linearization and incremental invalidation. The trade-off is that Object gains a definition at that location. Only statements directly in the program body count: inside a block (Struct.new do ... end), self is unknown. Top level prepend is a NoMethodError, and top level extend only affects main.
• ||=: both indexers set a new DefinitionFlags::CONDITIONAL on ||= constant and alias definitions. Before declaring one, the resolver looks the name up the way defined? does: lexically for a bare name, with a qualified search for a path. If that finds a constant owned by another namespace and defined earlier (or in another file), the definition joins that declaration instead of creating a new one. If the lookup is blocked by a partial ancestor chain, it waits once and then falls back to the old behaviour.
• PrivateConstantReference is a Warning, like the other resolution rules. Visibility is only known after the convergence loop, so the resolver remembers the constant paths it resolved in this run and checks them once visibilities are applied.
• Namesake superclass: a new Name flag (before_definition) gives the superclass in class Foo < Foo its own name instead of sharing the class's name. Its lookup skips the declaration the class's own name resolves to. The flag only changes the NameId when it is set, so all existing ids are unchanged.
• self::X is only resolved when no block encloses it within the namespace body. A block may be instance_eval'd or class_eval'd, and inside a method self depends on the receiver.

Known limitations and remaining differences

• These are decided once, like other cross-file effects. If the constant an ||= deferred to is deleted, the conditional constant is re-declared in its own scope. Adding the original back doesn't undo that until the file with the ||= is re-indexed.
• The 7 remaining differences in the differential suite:
  • 5 private constant paths. They resolve, which is intentional, but are now reported.
  • 1 load-order case: Ruby resolves against the constants that exist when the line runs, Rubydex against the final graph.
  • 1 self::X inside a block, where self cannot be known statically.
• Mixins from different user files are still applied in URI order. That includes RBS core definitions, so when RBS core files and workspace files both mix modules into the same class, their relative order depends on the paths rather than on load order.

Testing

• cargo test (1187 lib tests, including the new ones for both backends), cargo fmt --check and cargo clippy --all-targets are clean.
• bundle exec rake compile and bundle exec rake ruby_test: 411 runs, 0 failures.
• I ran each new test without its fix to confirm it fails.
• Each Ruby behaviour above was checked with ruby 4.0.9.

Requested by Ufuk Kayserilioglu ufuk.kayserilioglu@shopify.com

AI Confidence Score: 4/5. All behaviours were verified against CRuby and covered by tests. The ||= and top level include representations are design choices the maintainers may want to change.