Verification and traceability

Platform spec article

Verification and traceability

Back to Panic, IO, and syscalls ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0008-panic-terminates-process Runtime panic terminates the process Accepted

   No Beskid stack unwinding across panic; traps end execution.

   Context

   Language Option covers expected errors. Unrecoverable faults and some IO failures need a distinct path that does not conflate with Result channel semantics.

   Decision

   Mechanism	Use
   Option / Result	Expected failures (language-meta + corelib)
   panic / panic_str	Unrecoverable faults, hard IO faults in v1 streams, allocation failures
   Unwind	No Beskid stack unwinding across panics
   Outcome	Runtime panics terminate the process (trap / abort)
   Builtin kind	AbiReturnKind::Never in BUILTIN_SPECS

   Consequences

   Corelib must not catch panics for ordinary control flow. Fiber Detach panics still abort unless future domain recovery is specified.

   Verification anchors

   beskid_runtime::builtins::panic_io; e2e runtime cases.

   Open full ADR page

2. 0009-runtime-owned-syscalls Syscalls centralized in runtime builtins Accepted

   Lowering and corelib route IO through syscall_read/write, not embedded OS code.

   Context

   Scattering platform syscall sequences through codegen duplicates policy and breaks GC mutator rules at IO sites.

   Decision

   Rule	Detail
   Builtins	syscall_read, syscall_write accept fd + buffer (BeskidStr for write)
   Implementation	beskid_runtime::builtins::panic_io — Linux x86_64 direct syscalls in reference tree
   Other targets	May use std::io for fds 1/2 while preserving signatures
   Front-end	Must not embed OS-specific syscall sequences in lowering
   Corelib	System.Input / Output / Error wrap builtins with descriptors

   Git anchor: 12ee673 (split System I/O surfaces).

   Consequences

   New platforms document stub vs native behavior without renaming symbols.

   Verification anchors

   panic_io.rs; console stream corelib tests.

   Open full ADR page

3. 0010-blocking-syscalls-park-fiber Blocking syscalls park the calling fiber Accepted

   Scheduler run_blocking offloads host work without stalling other fibers.

   Context

   Blocking read/write on a fiber must not freeze the entire M:N scheduler or violate Phase A mutator rules on pool threads.

   Decision

   Rule	Detail
   Blocking path	Enqueue host blocking work on syscall pool; park current fiber only
   Wake	Resume fiber on scheduler thread when worker completes
   Pool workers	Must not execute generated Beskid mutator code or allocate as mutators
   Pool worker tagging	Each pool thread calls set_syscall_pool_worker() so the runtime can assert this rule (assert_mutator_allowed) and panic on accidental allocation
   Allocation	Runtime object creation for results happens after resume on scheduler thread
   Console	Producers Send bytes/events; consumers Receive on fibers

   Consequences

   M6+ syscall integration is required for conformance on blocking builtins.

   Verification anchors

   Scheduler run_blocking; fiber scheduler verification article.

   Open full ADR page

Articles

• Contracts and edge cases MUST rules for panic divergence, syscall parameters, and backend neutrality. article Standard Reviewed Fri May 22
• Design model Panic termination, syscall ownership, and runtime-mediated IO boundaries. article Standard Reviewed Fri May 22
• Examples Panic from lowering, syscall_write status codes, and corelib IO scenarios. article Standard Reviewed Fri May 22
• FAQ and troubleshooting Panic vs Option, syscall return codes, and fiber/blocking IO issues. article Standard Reviewed Fri May 22
• Flow and algorithm Panic emission, syscall_write chunking, and blocking IO on fibers. article Standard Reviewed Fri May 22
• Verification and traceability panic_io implementation paths, e2e runtime cases, and IO contract cross-tests. 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 · 2 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
  Panic, IO, and syscalls

  Parent feature hub

Implementation anchors

Path	Role
compiler/crates/beskid_runtime/src/builtins/panic_io.rs	panic, panic_str, syscall_read, syscall_write
compiler/crates/beskid_runtime/src/builtins/mod.rs	Re-exports
compiler/crates/beskid_abi/src/builtins.rs	Signatures for IO/panic
compiler/crates/beskid_e2e_tests/src/tests/runtime_cases.rs	End-to-end panic/IO
compiler/corelib/.../System/Syscall/	Descriptor routing (corelib tests)

Requirement traceability

ID	Evidence
IO-ABI-001	Cranelift unreachable block after panic calls in codegen tests
IO-ABI-002	Shared BUILTIN_SPECS across beskid_engine and AOT link
IO-ABI-005	Code review: no CLIF syscall intrinsics in beskid_codegen for stdio
Console IO-004	corelib_tests console paths

CI

Compiler workspace runs beskid_e2e_tests runtime cases on Linux agents. Platform spec edits should trigger bun run verify:trudoc under site/website when frontmatter changes.

Related topics

• Contracts and edge cases
• Builtins verification