docs(#1445): note single-pass GC concurrency semantics

[dimitri-yatsenko]

Summary

T3.1 of the 2.3 release plan defers the two-phase transaction-safe GC (#1445) to 2.4 (effort + design-needed). To avoid retracting stronger claims later, add a one-paragraph note to how-to/garbage-collection.md clarifying that the current GC is at-most-once: an object inserted between scan and delete may be briefly orphaned, and a future release will add quarantine-based serialization.

Test plan

• mkdocs serve — note renders in the how-to and reads cleanly

[MilagrosMarin]

Small, well-scoped note. Verified against dj.gc.collect() on master (calls scan() internally then deletes — the race window is real) and against issue #1445, which explicitly tracks the two-phase quarantine work the note commits to. Placement (right after "Run garbage collection periodically" and before "Basic Usage") is sensible — a reader gets the caveat before running any commands.

Two small wording thoughts, neither blocking:

The phrase "at-most-once" in distributed-systems parlance usually refers to message delivery guarantees; here it's used to mean "single-pass, best-effort, no retry/confirmation." "Best-effort" or "single-pass" would read more naturally, and the concluding line already uses "best-effort rather than transactionally safe" — leading with that framing might be tighter.

"An object inserted between the scan and the delete may be briefly orphaned" — the described race is real, but "orphaned" typically means "no reference exists"; here the concern is closer to "deleted despite being newly referenced" (i.e., the row references bytes that just vanished). Small terminological blur; the intent reads clearly enough.

Otherwise clean. Approving.

[dimitri-yatsenko]

Thanks @MilagrosMarin — both wording points addressed (also note the branch was rebased onto current main to drop a stray pre-rename "Renderable" commit that had crept in; the PR is now just the GC note).

• "at-most-once" → "single-pass and best-effort." You're right that at-most-once reads as a delivery-guarantee term. The note now leads with "single-pass and best-effort," matching the concluding line. Title updated to match.
• "orphaned" → "dangling reference." Corrected the direction of the race: it's not that bytes are left without a reference, it's that a row inserted between scan and delete can have its object deleted while newly in use — the new row is left with a dangling reference.

Updated text:

Garbage collection is single-pass and best-effort: it scans references, then deletes objects the scan did not see referenced. If a row is inserted between the scan and the delete, the object it references can be deleted even though it is now in use — leaving the new row with a dangling reference. A future release will add quarantine-based serialization to close this window. Until then, prefer running GC during quiet periods, and treat any single GC pass as best-effort rather than transactionally safe.

[MilagrosMarin]

Thanks @dimitri-yatsenko — both wording points addressed cleanly. "Single-pass and best-effort" lands better than "at-most-once", and reframing to "dangling reference" also gets the direction of the race right — the new row is left holding a pointer to bytes that were just deleted, not the other way around. That's the more precise concern. Rebase also correctly trimmed the stray pre-rename commit — PR is now just the 9-line note.

Re-approving.