# Karyos 0.1.0-alpha.1

Released: 2026-10-15

> Esta página aún no está disponible en español. Se muestra en inglés.

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.