# Karyos 0.1.0-alpha.1

Released: 2026-10-15

The first Karyos alpha, for evaluation only. It contains the embedded driver on Linux and macOS and the cross-process control path on Linux.

0.1.0-alpha.1 is an early alpha for evaluation. It is not for production
use, and nothing in it is published to crates.io. APIs, wire formats and
shared-memory layouts will change.

## What works

- **Embedded driver, on Linux and macOS.** Publication and subscription in
  one process over log buffers:
  - exclusive publication (`offer`, `try_claim`) and concurrent publication
    from several handles;
  - claims with a commit deadline: a stuck claim is aborted and its readers
    skip it;
  - required subscribers, which bound the publisher and are never lapped,
    and optional subscribers, which are lapped and rejoin at the head with
    the lost range reported;
  - copy delivery: a handler always reads a private copy, so a slow handler
    never pins shared memory;
  - stream removal, publication seal, and mapping generations with a
    cutover that client handles follow;
  - driver counters, read in process.
- **Cross-process control path, on Linux.**
  - The driver admits a client process over its Unix socket, with
    credential and process exit checks.
  - A protocol version exchange refuses an incompatible pair before any
    mapping.
  - The client's command ring, the broadcast buffer and the counters are
    passed as sealed shared-memory regions.
  - A client and its resources are released by its process exit proof
    (pidfd). A killed client is released; a stopped one keeps its slot and
    resumes; a restarted driver starts a new instance while the old
    mappings stay valid for the clients that hold them.
  - Entry points: `EmbeddedDriver::with_ipc` and `do_work` on the driver
    side, `karyos_client::ipc::attach` on the client side. There is no
    example binary yet.
- **Libraries for later releases**, usable directly: the keyed conflation
  table, the bounded record journal, trace records, sampling, clock
  calibration and latency histograms, the deterministic simulator and the
  benchmark harness.

## What does not work yet

- **Cross-process data streams:** a publication or subscription in a
  process other than the driver's. Planned for 0.1.0-alpha.2.
- **Also planned for 0.1.0-alpha.2, in embedded mode:** the observer reader
  role, the `snapshot` and `close` rejoin policies, handling the loss of a
  required participant (heartbeats and the `hold`, `continue` and `abort`
  policies), conflated subscriptions, tracing on the data path, per-stream
  observability, the error log and the operational tools (`karyosd`,
  `karyos-stat`, `karyos-errors`).
- **Later phases:** UDP transport, network I/O backends, lanes, guards,
  timed transmission and wire security; Archive and replay; Cluster.

> **Important**
>
> No latency or throughput figure is published for this alpha. The benchmark harness exists, but its
> results are indicative only.

## Known limitations

- Cross-process IPC is Linux only. On macOS, IPC is embedded, in one
  process.
- A process with write access to the driver's directory or mappings is
  outside the isolation boundary. Deployment permissions must prevent that
  access.
- Liveness heartbeats are not implemented: a paused client keeps its
  resources until it exits or detaches.
- Every admitted process can write to the shared-memory regions; read-only
  tool access does not exist yet.
- Hosted CI is not running; the gates are run locally.
- A restarted driver's listen may be refused for a moment while a process
  forked at that instant still holds the old socket; the tests retry for up
  to 2 s.
- A thread pidfd must not count as an exit proof. Linux 6.8 rejected
  `PIDFD_THREAD` itself; Karyos's own rejection of a real thread pidfd was not
  tested, because exercising that path requires Linux 6.9 or later.

## Evidence

Functional evidence only: Docker and virtual machines say nothing about
latency on physical hosts.

| Check                                                     | Environment                  | Result                                           |
| --------------------------------------------------------- | ---------------------------- | ------------------------------------------------ |
| Release gate `make pre-push`                              | macOS arm64, rustc 1.99.0    | 613 tests passed, 0 failed                       |
| Release gate `make miri` on `karyos-sys`                  | macOS arm64                  | 318 of 318 pass, no undefined behaviour reported |
| Release gate `make sim`, 2000 seeds per scenario          | macOS arm64                  | 7 of 7 scenarios pass                            |
| Release gate `scripts/linux-test.sh --workspace --locked` | Docker, kernel 6.8.0 aarch64 | 601 passed, 0 failed                             |
| Process tests of `karyos-driver`                          | Docker, kernel 6.8.0 aarch64 | 4 of 4 pass, five consecutive runs               |
| Platform tests of `karyos-driver`                         | Docker, kernel 6.8.0 aarch64 | 11 of 11 pass, three consecutive runs            |
| Linux x86_64, kernels 6.9 and later                       | Not run for this alpha       | Not claimed                                      |

## Upgrading

There is no earlier release. Expect breaking changes in 0.1.0-alpha.2.