Skip to content

Root Package Execution Contract

Jump to bottom
Adrian Burlacu edited this page Feb 3, 2026 · 1 revision

Root Package Execution Contract

Root packages execute on the main thread and therefore share fate with the node they run on. To preserve node liveness, root packages must adhere to the following execution constraints.

Violations are considered fatal pack errors.

1. Core Rule

Root packages MUST NOT perform unbounded synchronous work on the main thread.

Any synchronous execution must be:

  • bounded
  • yield-capable
  • observable

2. Allowed Execution Patterns

2.1 Budgeted Execution

Root packages MUST structure long-running logic to execute within a time budget.

Required properties:

  • Explicit maximum execution time per slice
  • Safe resumption after yield
  • Deterministic continuation

Recommended patterns:

  • Generators / iterators
  • Explicit step functions
  • Finite state machines

2.2 Cooperative Yielding

Root packages MUST periodically yield control back to the runtime.

Acceptable yield mechanisms:

  • scheduler-controlled rescheduling
  • explicit yield points in generators
  • runtime-provided yield() primitive

Root packages MUST assume:

  • they may be paused at any yield point
  • resumption is not immediate
  • execution order is not guaranteed across yields

2.3 Asynchronous I/O

All I/O operations MUST use non-blocking APIs.

Disallowed:

  • synchronous filesystem access
  • synchronous network calls
  • synchronous database drivers

Allowed:

  • promise-based async I/O
  • callback-based async I/O

3. Explicitly Forbidden Operations

Root packages MUST NOT:

  • Execute unbounded loops (while(true), for(;;))
  • Perform synchronous CPU-heavy work
  • Parse or serialize large payloads synchronously
  • Block on locks or shared state
  • Assume exclusive access to the event loop
  • Rely on microtasks for yielding

These operations MUST be delegated to:

  • worker packs
  • background services
  • pre-validated boot phases

4. Blocking Sections (Exceptional)

Synchronous blocking MAY be allowed only when explicitly declared.

Blocking sections:

  • MUST be short-lived
  • MUST be measured
  • MUST be marked as non-resumable
  • MAY be rejected by the runtime

Blocking sections SHOULD be restricted to:

  • early boot
  • trust establishment
  • invariant verification

5. Failure Semantics

If a root package:

  • exceeds its execution budget
  • fails to yield
  • blocks the event loop
  • triggers watchdog timeouts

The runtime MAY:

  • terminate the package
  • restart the package
  • restart the node
  • mark the package as unhealthy

No guarantee of graceful shutdown is provided.

6. Runtime Guarantees

The Stark runtime guarantees:

  • fair scheduling between root packages
  • visibility into execution time
  • isolation boundaries for worker packs
  • recovery after root package failure

The runtime does NOT guarantee:

  • uninterrupted execution
  • real-time deadlines
  • exclusive main-thread access

7. Design Guidance (Non-Normative)

Root packages SHOULD:

  • treat the main thread as a scarce resource
  • assume other root packages exist
  • fail fast rather than block
  • push work outward, not inward
  • prefer resumable designs over atomic ones

Summary

Root packages are trusted, not privileged.

They run at the center of the system, and therefore carry responsibility for its survival.

Clone this wiki locally