docs(gc): add precise-tracing API redesign plan

[Flamki]

This PR adds a focused planning note for the GC redesign direction after removing the gc_allocator experiment path.

What this adds

• notes/precise_tracing_api_plan.md
  • precise-tracing API direction without root/reference-count dependence
  • explicit invariants (rooting, weak/ephemeron, finalization/resurrection, teardown)
  • phased execution plan (contract + prototype + gated integration)
  • validation and risk controls aligned with current tracker issues
• README link for discoverability

Why

Recent maintainer guidance points toward API-focused GC redesign and staged integration, while #54 removes the Collector: Allocator experiment. This note captures a practical plan that matches that direction and keeps scope clear.

Scope

• docs only
• no runtime/API behavior changes

Validation

• cargo fmt --all -- --check
• cargo test --workspace

[jedel1043]

I don't think we want a plan to "redesign an API", we want an API redesign proposal. That's much better than just proposing to do it "somehow", since that doesn't prove its feasibility. Having at least a proposed API would open discussion on how to improve it or change it to better fit Boa's needs.

[Flamki]

Thanks for the clarification — agreed.

I updated this PR to be an API redesign proposal (not just a plan). The latest commit adds a concrete draft API surface and feasibility path:

• proposed core types/surface (Gc<T>, Root<T>, WeakGc<T>, GcContext, Scope<'gc>)
• draft method/signature shape for allocation, rooting, casts, weak upgrades, and collection utilities
• explicit semantic invariants (tracing authority, root-slot model, weak/ephemeron behavior, finalization/teardown safety)
• compatibility/adoption mapping to the current Boa-facing boa_gc surface
• open review questions to drive design discussion

If useful, I can split the proposed API into focused follow-up issues (by parity area) after this gets initial review direction.

[jedel1043]

If roots are not tied to the gc context by lifetime, couldn't you cause UB by holding onto a reference to the inner data of a root, then dropping the context and trying to access the hold reference?

[Flamki]

Great point, thanks — agreed this needed to be explicit.

I updated the proposal to brand roots with the GC context lifetime:

• Root<'gc, T> now carries a context lifetime marker
• Scope::root now returns Root<'gc, T> (tied to the same scope/context lifetime)
• added a safety note clarifying that safe code cannot keep rooted references after the context/scope is dropped

So the intended model is that roots cannot outlive their owning GC context in safe code.

[jedel1043]

Wait, this is extremely limiting since it essentially means you cannot have more than one root at a time

[Flamki]

Thanks, that’s a fair concern.

I pushed an update that keeps the lifetime safety guarantee without serializing root creation:

• changed Scope::root from an exclusive-borrow shape to a shared-borrow shape
• roots are now scope-branded (Root<'scope, 'gc, T>) so they remain tied to the owning context lifetime
• documented the expected implementation detail that root-slot registration uses internal mutability, which allows multiple roots to exist at once

So the model now aims for both:

1. no “single-root-at-a-time” restriction, and
2. no safe-code path for roots to outlive their owning GC context.

[jedel1043]

That still doesn't allow multiple roots, because Scope mutably borrows from GcContext, so the underlying Root also mutably borrows from GcContext.

[Flamki]

Good catch. Fixed now:

• Scope uses shared &GcContext (not mutable borrow)
• root stays lifetime-branded (Root<'scope, 'gc, T>)
• model now allows multiple roots + keeps context-lifetime safety