Verification and traceability

Platform spec article

Verification and traceability

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

Implementation anchors

Path	Role
compiler/crates/beskid_runtime/src/gc.rs	Scope, heap TLS, collection drivers
compiler/crates/beskid_runtime/src/builtins/gc.rs	Exported gc_* builtins
compiler/crates/beskid_runtime/src/builtins/alloc.rs	alloc entry
compiler/crates/abfall/	Tri-color heap implementation
compiler/crates/beskid_codegen	Stack maps, barrier insertion, descriptors
compiler/crates/beskid_tests/src/runtime/jit.rs	JIT + GC integration

Tests and benches

Target	Coverage
beskid_tests runtime JIT	Alloc + collect under execution
beskid_runtime runtime_micro bench	Hot path regression guard
Future conformance	Stack map completeness per function (Phase B gate)

Requirement traceability

ID	Evidence
GC-001	Descriptor emission tests in codegen artifacts
GC-002	CLIF inspection / lowering unit tests for barrier calls
GC-003	Fiber scheduler tests + code review of enter_runtime_scope
GC-004	Host GcSnapshot / force_collect tests

Related topics

• Contracts and edge cases
• Codegen and IR