# 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.