prometeu-studio/docs/compiler/pbs/decisions/GC and Reachability Decision.md

GC and Reachability Decision

Status: Accepted (Implemented) Cycle: Initial GC-and-reachability closure pass

1. Context

PBS v1 uses GC as the baseline runtime model, but the language still needs a precise statement of:

• what reachability guarantees are normative,
• what reclamation guarantees are normative,
• what remains implementation-defined,
• how GC interacts with the single normative safepoint at FRAME_SYNC,
• and what user code may or may not observe.

2. Decision

PBS v1 adopts the following GC-and-reachability baseline:

1. GC is the baseline runtime model for VM-owned memory in PBS core.
2. Reachability is the normative liveness criterion for GC-managed values.
3. Eventual reclamation is the strongest reclamation guarantee in v1.
4. FRAME_SYNC is the only normative safepoint relevant to GC-observable behavior.
5. User code cannot observe reclamation directly.
6. PBS v1 defines no user-authored finalizers, destructors, or reclamation callbacks.
7. Implementations may perform internal GC work outside FRAME_SYNC only if doing so creates no additional user-visible semantic effects.

3. Normative Reachability Contract

For GC-managed VM-owned values, liveness is defined by reachability from the runtime roots that matter to PBS semantics.

At minimum, these roots include:

• currently active local/frame state,
• reachable fields of reachable struct instances,
• service singleton roots,
• retained callback state that remains reachable,
• and any other runtime roots required to preserve already-observable PBS behavior.

If a GC-managed value remains reachable through the normative runtime state, the implementation must preserve its continued semantic availability.

If a value becomes unreachable, user code must not rely on when reclamation occurs.

4. Reclamation Guarantee

PBS v1 guarantees eventual reclamation, not prompt reclamation.

This means:

• unreachable GC-managed memory may be reclaimed later,
• the language does not promise immediate reclamation,
• the language does not promise reclamation at a specific frame boundary,
• and the language does not expose a semantic event when reclamation occurs.

5. Safepoint Relationship

FRAME_SYNC is the only normative safepoint in PBS v1.

For GC semantics, this means:

• the language does not promise any additional observable GC safepoints,
• no user-visible program rule may depend on another safepoint existing,
• and any internal collector work outside FRAME_SYNC must remain semantically invisible to PBS userland.

The spec does not require a specific collector architecture. It only constrains what may become observable.

6. Observability

User code cannot observe reclamation directly.

PBS v1 provides no user-visible mechanism for:

• detecting that a value was collected,
• registering a callback on reclamation,
• forcing immediate collection,
• or sequencing user code against GC timing.

GC-related information may appear in diagnostics, profiling, or runtime tooling, but those surfaces are not ordinary language semantics.

7. Finalization and Cleanup

PBS v1 forbids user-authored finalizers and destructor-like reclamation hooks.

GC reclamation of pure VM-owned values does not trigger user code.

Host-backed cleanup policy is not defined by GC finalization semantics in this decision. If host-backed resources require explicit or contract-specific cleanup rules, those belong to the host-boundary decision track rather than to GC finalization in userland.

8. Invariants

• Reachability, not timing, is the normative semantic axis.
• Reclamation timing remains implementation-defined.
• No direct user-visible behavior is allowed to depend on collector timing.
• The only normative safepoint is FRAME_SYNC.
• GC must not create extra user-visible sequencing effects outside the already-closed execution model.

9. Beginner-Facing Model

The user-facing explanation should be:

• if a value can still be reached by the program, it remains alive,
• once it can no longer be reached, the runtime may clean it up later,
• the program does not control or directly observe that cleanup moment.

10. Explicit Non-Decisions

This decision record does not yet close:

• the exact collector algorithm,
• host-backed resource cleanup semantics,
• diagnostics wording for GC-related tooling surfaces,
• the full root-set wording as finally integrated into the memory specification.

11. Spec Impact

This decision should feed at least:

• docs/pbs/specs/10. Memory and Lifetime Specification.md
• docs/pbs/specs/12. Diagnostics Specification.md
• docs/general/specs/16. Runtime Execution and Initialization Specification.md

12. Validation Notes

The intended split is:

• GC defines reachability and eventual reclamation,
• FRAME_SYNC is the only normative safepoint,
• reclamation timing is not user-observable,
• host-backed cleanup is a separate boundary question rather than a user finalization feature.