Write the Portable Runtime Contract First

Portability is not the absence of platform details. It is a deliberate contract that keeps platform details behind named adapters. If a workload assumes a path layout, signal behavior, clock resolution, socket option, process model, or executable format without recording it, the portability claim is already incomplete.

Define the workload surface

Begin with what the application must do, not with the APIs available on the first host. Describe inputs, outputs, persistent state, time needs, randomness, concurrency, network relationships, and shutdown behavior. Then assign each need to a small runtime interface.

For a file-processing worker, the surface might be one readable input handle, one writable output handle, a monotonic clock, bounded memory, and a status channel. The workload does not need to discover the host home directory or scan all mounted filesystems. An adapter can prepare the handles before the workload starts.

Record these fields for each operation:

1. operation name and purpose;
2. input and output types;
3. error classes the caller must handle;
4. ordering and concurrency rules;
5. blocking or asynchronous behavior;
6. resource lifetime;
7. host mapping; and
8. tests shared by every adapter.

Keep host documentation close

For Linux-specific behavior, use the current kernel documentation as one primary source. The Linux kernel documentation separates subsystem material and versioned behavior better than an undated summary. For FreeBSD, the FreeBSD documentation portal provides current handbooks and architecture material. A portable layer should cite the host contract it maps, including the release or documentation date.

Do not infer sameness because two systems use a function with the same name. Flags, error behavior, path semantics, process inheritance, and event delivery can differ. The adapter should translate only what the portable contract promises. Host features outside that contract remain host extensions.

Make errors portable without erasing detail

A tiny generic error enum is easy to use but can destroy evidence. Keep a stable portable category and attach a host-specific cause for diagnostics. The workload can react to “permission denied” or “resource exhausted” while logs retain the precise platform result.

Do not map an unknown host error to success or to a misleading category. Return an explicit unmapped result and add a test. Portability improves when surprising platform behavior becomes visible.

Use conformance tests as the specification

Write one black-box suite for every adapter. The test should cover valid operations, invalid inputs, boundary sizes, cancellation, timeouts, concurrent use, cleanup, and resource exhaustion. Run it on each supported platform and store platform, version, build, and adapter revision with the result.

The former CloudABI project is one historical example of a runtime-boundary approach. This site is not the original CloudABI project and does not reproduce its specification. The method here is independent: write the smallest contract that the workload needs, make every host mapping explicit, and use shared negative tests to keep the promise honest.

A portable runtime is successful when a new host requires a contained adapter and does not force hidden host assumptions into application logic. The contract is the center. The operating systems are implementations around it.