Contracts and edge cases

Platform spec article

Contracts and edge cases

Back to Memory and GC runtime contract ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0005-phase-a-before-phase-b Ship Phase A GC before parallel mutators Accepted

   v0.2 targets single mutator; Phase B requires spec and barrier completion first.

   Context

   Parallel GC mutators need write barriers, stack-map coverage, and scheduler coordination. Shipping partial parallel GC risks data races on the Abfall heap.

   Decision

   Phase	Mutators	Ship order
   A (v0.2)	One Beskid mutator; many cooperative fibers	Default ship
   B (v0.3, opt-in)	Parallel mutators + real gc_write_barrier on pointer-payload channels + syscall-pool guard	Wired behind BESKID_RUNTIME_PHASE_B / set_runtime_phase(RuntimePhase::PhaseB); stays opt-in until preemption emission and concurrent-mark stress land
   B (later)	Phase B becomes the default	Requires AOT/JIT to insert runtime_preempt_check prologues and full concurrent-mark stress coverage

   Phase B must not become the default without updating this feature hub and fiber scheduler contracts.

   Consequences

   Phase A barriers stay correct because Phase B reuses the same Dijkstra insertion barrier; the difference is that Phase B exercises it on multi-mutator workloads and on pointer-payload channel ops. Fiber/feature docs cross-link Phase tables.

   Verification anchors

   GC integration tests under crates/beskid_runtime/tests/:

   • tests/concurrency.rs — channel/scheduler core
   • tests/gc.rs, tests/gc_concurrency.rs — Phase A heap and root handles
   • tests/phase_b_concurrency.rs — Phase B multi-mutator stress, pointer-payload channels with write barriers, syscall-pool guard, optional preemption hook

   Platform-spec Phase diagrams in hub and design model.

   Open full ADR page

2. 0006-abfall-tri-color-heap Abfall tri-color heap with write barriers Accepted

   Reference runtime uses vendored Abfall mark/sweep with barriered stores.

   Context

   The prior arena model needed a collector that supports concurrent marking and precise scanning with compiler-emitted descriptors.

   Decision

   Component	Role
   Abfall	Tri-color mark/sweep heap integrated in beskid_runtime::gc
   Barriers	gc_write_barrier on pointer stores during marking
   STW	Limited stop-the-world for root scan and phase transitions
   Snapshots	GcSnapshot / enter_runtime_scope for host tooling

   Git anchor: 6ecd493 (vendored Abfall + Beskid heap integration).

   Consequences

   Lowering must emit barriers where Phase requires them. Hosts attach runtime scope before JIT/AOT execution.

   Verification anchors

   compiler/crates/beskid_runtime/src/gc/; JIT runtime tests.

   Open full ADR page

3. 0007-heap-type-descriptors Heap objects carry type descriptors for scanning Accepted

   alloc attaches descriptors; roots include stacks, globals, and handles.

   Context

   Conservative stack scanning alone is insufficient for precise Beskid object graphs across fibers and codegen optimizations.

   Decision

   Rule	Detail
   Header	Heap objects begin with a type descriptor pointer for precise scan
   Allocation	alloc(size, type_desc) uses abfall::Heap::allocate_beskid
   Strings / arrays	BeskidStr, BeskidArray headers per builtins layout
   Roots	Stacks (stack maps), globals (registered roots), gc_root_handle externals
   Compiler	Lowers descriptors and stack maps; does not embed collector policy

   Consequences

   Descriptor schema changes are ABI-visible per D-EXEC-ABI-0002.

   Verification anchors

   beskid_codegen stack maps; beskid_runtime alloc/GC tests.

   Open full ADR page

Articles

• Contracts and edge cases MUST rules for allocation, barriers, roots, and Phase A mutator exclusivity. article Standard Reviewed Fri May 22
• Design model Heap ownership, tri-color GC, Phase A mutator rules, and compiler/runtime split. article Standard Reviewed Fri May 22
• Examples Allocation failures, GC pacing triggers, and external root pinning scenarios. article Standard Reviewed Fri May 22
• FAQ and troubleshooting GC pauses, mutator violations, barrier omissions, and heap growth debugging. article Standard Reviewed Fri May 22
• Flow and algorithm Allocation, barrier insertion, collection pacing, and safepoint algorithms. article Standard Reviewed Fri May 22
• Verification and traceability Runtime GC tests, Abfall integration, and compiler stack-map obligations. article Standard Reviewed Fri May 22

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 SpecSection(s) · 1 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  Memory and GC runtime contract

  Parent feature hub

Normative requirements

ID	Requirement
GC-001	All heap objects must carry type descriptors reachable from the object header for precise scanning.
GC-002	Pointer stores in generated code must lower to gc_write_barrier when concurrent marking is enabled.
GC-003	Phase A must execute at most one Beskid mutator performing allocations at a time.
GC-004	gc_collect / gc_collect_if_needed must be safe to call from host tooling when runtime scope is entered.
GC-005	External roots must pair gc_register_root with gc_unregister_root (or handle APIs) to avoid leaks.
GC-006	Stack maps must be emitted for functions that hold GC pointers across safepoints.
GC-007	Phase B mutators must attach to a shared heap through attach_phase_b_mutator (or an equivalent runtime scope) before allocating or reading GC-managed pointers.
GC-008	Syscall-pool worker threads must not allocate on the Beskid heap; the runtime must trap the violation when assertions are enabled.
GC-009	Pointer-payload channel transfers must apply the insertion write barrier on both send and receive paths, and must keep the in-flight pointer reachable via an external GC handle while it sits in the queue.
GC-010	Optional preemption (runtime_preempt_check) must be a no-op when preemption is disabled and must never block a syscall-pool worker thread.

GC export contracts

Symbol	Returns	Semantics
gc_bytes_allocated	i64	Total allocated bytes (diagnostic)
gc_object_count	i64	Live object estimate
gc_phase	i64	Phase enum 0/1/2
gc_write_barrier	void	Barrier hook
gc_root_handle	i64	Temporary external pin
channel_send_ptr / channel_receive_ptr	i64 status	Pointer-payload channel ops with barrier and external-handle handoff
runtime_preempt_check	void	Optional safe-point hook; yields when preemption is enabled

Edge cases

Case	Behavior
Null pointer store	Lowering should avoid barrier; runtime barrier on null should no-op
Fiber migration mid-mark	Scheduler holds mutator lock; no second mutator attaches (Phase A only)
Multiple Phase B mutators on one heap	Each thread holds a MutatorAttachGuard; shared heap + per-thread GC context
Full heap during str_concat	Panic/trap — matches allocation failure policy
Conservative fallback	Forbidden — Beskid uses precise descriptors only
Syscall-pool worker accidentally allocates	assert_mutator_allowed panics; the worker is not a mutator
Pointer-payload channel sender from a non-fiber OS thread	Backpressure resolved by try_send + thread::yield_now, never park_current

Rejected alternatives (decision record)

Reference counting, conservative GC, and region-only allocation are rejected for v0.2; see legacy Concurrent GC decision summary.

Related topics

• Memory model (language)
• Builtins and symbols