A3S OCI Runtime Roadmap

August 22, 2026 · View on GitHub

Status: In development

Standards baseline: OCI Runtime Specification 1.3.0

Primary consumer: A3S Box through a3s-oci-sdk

Release Contract

The production runtime must implement every normative OCI Runtime Specification 1.3.0 requirement applicable to Linux containers and every driver it advertises. A reduced A3S-only OCI profile is not an acceptable terminal state.

Complete means all of the following:

every applicable config.json, state, and feature property is represented without loss;
every applicable value and cross-field rule is validated before runtime state mutation;
every requested control is enforced or the operation fails;
lifecycle and hook ordering matches the specification;
recovery preserves the same externally observable state;
upstream OCI validation and lifecycle suites pass;
the feature report describes only behavior that passed the same release build's tests.

The SDK is also a release blocker. A3S Box must be able to perform the complete supported lifecycle without constructing CLI commands or importing platform driver internals.

Repository Boundary

A3S OCI Runtime is the sole low-level execution engine. It owns exact OCI validation, actual container state, durable operation replay, process control, platform drivers, utility VMs, the guest agent, and runtime-scoped cleanup.

A3S Box owns product configuration and desired state, image distribution and builds, named volumes and product snapshots, network/IPAM/DNS policy, Compose, health and restart policy, log retention, and secret authorization. Box passes prepared, immutable execution inputs through a3s-oci-sdk; OCI Runtime does not pull images, build images, implement Compose, or become a Docker daemon.

The dependency direction is strict:

A3S Box or containerd shim
          |
          | a3s-oci-sdk over bounded local IPC
          v
OCI Runtime host service
          |
          +-- native Linux driver
          `-- utility-VM drivers (KVM / HVF / WHPX)
                          |
                          `-- authenticated Linux guest agent

Boundary rules:

OCI Runtime must not depend on Box product crates or durable state types. Box-specific fixtures may test compatibility but cannot define runtime semantics.
Box requests DedicatedVm, SharedGuestKernel, or SharedHostKernel. Runtime selects an enforcing driver and never silently weakens isolation.
Runtime owns actual OCI state, process/VM identity, generation, exit status, operation journals, recovery, and quarantine. Callers own desired state and retain only an exact runtime reference.
Image, storage, network, secret, and TEE policy stay outside the OCI core. Versioned extensions may attach already-authorized resources or expose runtime mechanisms without moving product policy into this repository.
The containerd runtime-v2 shim belongs here and calls the SDK directly. It must not shell out to A3S Box or duplicate lifecycle state.

Delivery Milestones

The detailed workstreams below are not a strict waterfall. Integration begins with an early vertical slice so contract problems are found before every OCI field and platform feature is implemented.

Milestone	Runtime delivery	Cross-repository exit gate
M0 - Boundary freeze	Generic public contracts, attachment schemas, driver/isolation vocabulary, and state ownership	Box depends only on `a3s-oci-sdk`; runtime behavior does not depend on Box types
M1 - Host service	Multi-driver registry, secure Unix/Windows service endpoints, durable routing, state migration, restart reconciliation, and reattachment/cleanup	A service restart at every lifecycle boundary preserves or safely terminates the exact workload
M2 - Windows experimental	Launch-ready WHPX driver, protected runtime storage, pinned kernel, immutable system root, authenticated protocol-v10 agent, and leak gates	A fresh Windows host passes complete SDK lifecycle, I/O, filesystem, resource, recovery, and multi-container suites
M3 - Box cutover	Stable SDK surface and Linux/KVM/HVF drivers needed by the unified Box adapter	Box routes `microvm` and `sandbox` through the SDK with no silent fallback
M4 - containerd	Runtime-v2 shim using OCI bundles and SDK operations directly	containerd task, restart, I/O, and cleanup suites pass without invoking the Box CLI
M5 - parity extensions	Storage/network attachments, reusable guest sessions, checkpoint/restore, and TEE mechanisms	Box storage, networking, warm-pool, snapshot, and security gates pass through public extensions
M6 - supported release	OCI 1.3 evidence, adversarial security, upgrade compatibility, signed packages, and long-running real-host qualification	Every advertised driver and operation has evidence from the exact release artifacts

Conformance is continuous across M1-M6. R5 is the final audit, not the first time normative requirements are enforced. Box migration starts after the M1 vertical slice and does not wait for every optional OCI feature.

Remaining Work Execution Plan

The detailed workstreams below are the canonical task checklist. This section orders that work; it does not maintain a second completion state.

Wave	Outcome	Canonical workstreams	Exit evidence
W0 - Evidence and host safety	Close normative classification, descriptor-relative ownership, and utility-VM transport recovery gaps before widening launch claims	R0, R1, R5	No unclassified requirement or silent path fallback; every injected host/agent interruption recovers or cleans up the exact generation
W1 - Native Linux qualification	Turn the existing explicit Native Linux path into a packaged, reproducible A3S Box Sandbox baseline without KVM	R3, R4	Signed or checksummed packages pass the complete Rust, Python, TypeScript, and Go Sandbox suites on x86_64 and aarch64 with `/dev/kvm` absent and inaccessible
W2 - Real-driver restart continuity	Reattach supported live process, I/O, and filesystem sessions after an out-of-process runtime restart, or terminate them with exact durable evidence	R1, R6	Native Linux and one utility-VM driver pass the same owner-death and service-restart matrix without duplicate effects, invented exit status, or leaked resources
W3 - Utility-VM experimental drivers	Qualify immutable guest assets and complete WHPX first, followed by HVF and KVM through the same SDK and guest-agent contract	R2, R2M, R2L, R3	Each promoted driver independently passes lifecycle, I/O, filesystem, resource, recovery, negative-isolation, multi-container, and soak gates on a fresh host
W4 - A3S Box cutover	Route both Box isolation choices through the SDK and remove fallback only after behavior and recovery parity pass	R6	`microvm` and `sandbox` use recorded SDK routes with no direct VMM path, no silent fallback, and complete cross-platform behavior and soak evidence
W5 - Downstream adapters and extensions	Add containerd and optional parity mechanisms without moving product policy into the runtime	R7, R8	Each adapter or extension is version-negotiated, separately advertised, restart-safe, and tested through public SDK contracts
W6 - Supported release	Finish upstream OCI, adversarial security, upgrade, packaging, and long-running qualification against exact release artifacts	R5, M6	The release report binds every advertised driver and operation to passing evidence from the published artifacts

R5 work runs throughout every wave. W6 is the final audit of evidence produced earlier, not a late conformance implementation phase. Work within a wave may run in parallel, but a readiness promotion waits for that wave's complete exit evidence.

Every retained real-host report must identify the source commit, package or runtime-asset digest, platform, architecture, driver, isolation class, schema version, and exact test profile. A green capability probe, an unretained local run, or evidence from a different artifact does not satisfy an exit gate.

Current Baseline

Completed:

independent A3S-Lab/OCI-Runtime repository and monorepo submodule;
pure OCI lifecycle transition contract;
versioned driver status, readiness, isolation, and evidence;
deterministic multi-driver selection and durable recorded-driver routing, including fail-closed startup audit for missing or isolation-drifted drivers;
protected Windows SDK host serving over a local named pipe with first-owner, DACL, remote-client rejection, concurrency, and shutdown-release gates;
explicit clone-wide guest-agent transport shutdown before utility-VM shim reap, providing the ownership boundary required by a long-lived VM driver;
single-owner utility-VM sessions with clone-safe guest access and idempotent retained cleanup evidence, exercised by WHPX/HVF lifecycle harnesses;
one shared 20-workload-operation guest-to-driver adapter, including exact-target file transfer and filesystem metadata/mutations, plus a qualification-only WHPX RuntimeDriver candidate that owns one VM per exact dedicated-VM generation, serializes same-ID launch without blocking distinct container VMs, retains retryable create sessions, reaps terminal failures and deletes once, and refuses bundles outside a protected, per-generation runtime share mounted separately from the system root; owner-death restart reconciliation retains an exact-generation stopped tombstone and replays authenticated exit evidence when available;
one platform-neutral dedicated utility-VM lifecycle shared by the public HVF driver and the Linux KVM candidate. It serializes Create per container, owns one VM per exact generation, validates isolation before moving a bundle, validates missing, linked, non-private, drifted, escaping-rootfs, and absolute-bind handoff sources before creating a Guest-visible share, retains retryable handoffs, removes terminal and conflicting generations, delegates all 20 workload operations and six OCI hook phases, recovers stopped tombstones, and shuts down each live owner at most once;
secure WHPX DLL loading and hypervisor capability probe;
native Linux namespace, cgroup v2, and pidfd signaling prerequisite reporting that does not touch /dev/kvm;
Linux KVM device, access, ioctl, and API-version reporting without libkrun initialization;
deterministic Linux x86_64 and AArch64 libkrun archives with one shared manifest binding archive, library, firmware, and exported-kernel identities;
isolated Linux libkrun create/configure/plain-vsock/release context evidence with runtime symlink and content-drift rejection, without opening /dev/kvm or entering a VM;
a shared Linux KVM lifecycle qualification entry for x86_64 and AArch64, with 16 KVM-gated lifecycle, multi-container, lifecycle-fault, and transport-fault cases plus an explicit zero-case unavailable report on runners that cannot open KVM;
a qualification-only Linux KVM Host Service entry that keeps the public candidate probe-only, but permits one explicitly scoped owner-death and restart gate to register the exact driver. The gate SIGKILLs a live service, requires pidfd-bound shim/worker cleanup and authenticated SIGKILL evidence, opens a distinct replacement service, replays stopped state and Wait, and performs stopped-only Delete with descriptor, endpoint, handoff, share, and recovery-report cleanup. CI emits zero-case unavailable evidence when KVM cannot be opened; fresh-host available reports are still outstanding;
a separate linux-kvm-bounded-soak-only-v1 Host Service entry that runs a default 25 fresh generations through one durable owner. Every wave retains exact generation and replay evidence plus process, descriptor, marker, endpoint, bundle-handoff, runtime-share, recovery-report, and configured Guest cgroupsPath lifetime checks. CI records zero completed iterations and skips the Alpine fixture when KVM cannot be opened;
one fail-closed a3s.oci.linux-kvm-provenance.v1 contract shared by the authenticated entry, post-probe failure, compatibility-drift, lifecycle, owner-restart, and soak reports. It requires a clean exact checkout, rejects a claimed revision that differs from the built checkout, and binds the Git object format, commit/tree, Linux platform/architecture, CLI and shim bytes, runtime manifest and selected runtime files, immutable system-image manifest, build/test profiles, libkrun-kvm, and DedicatedVm. PR qualification now records the actual checked-out merge commit rather than a different branch-head revision;
Apple Silicon and Hypervisor.framework capability reporting through a direct kern.hv_support query;
entitlement-aware direct Hypervisor.framework VM-object create/destroy evidence with versioned, fail-closed diagnostics;
isolated macOS libkrun context create/configure/plain-vsock/release evidence from a checksum-pinned, runtime-reverified arm64 bundle;
real macOS HVF guest entry using the pinned libkrun firmware kernel and a digest-verified Alpine arm64 userspace, with natural exit status, exact host-visible marker verification, bounded worker reap, and marker cleanup;
real macOS static arm64 guest-agent boot through AF_VSOCK and a private Unix socket, with LOCAL_PEERPID, direct shim-worker parent verification, one-time token authentication, protocol-v10 negotiation, exact advertisement of 20 workload operations plus one maintenance acknowledgement, process-group termination, exact endpoint removal, observed PID reap, and in-process descriptor-inventory restoration;
real macOS fixed-bundle create/state/start/kill/wait/delete evidence using the shared Windows lifecycle harness, including exact mutation retries, create/start separation, bounded running wait, exact repeated normal exit status, exact live process inventory, cgroup-v2 pause/resume with real workload-progress evidence, replay-safe live CPU/memory/cpuset/PID update, normalized cgroup-v2 stats, running and stopped observation, post-delete NotFound, and nominal process, endpoint, marker, and runtime-root cleanup;
real macOS no-delete cleanup after successful create, start, and kill boundaries, with exact fault identity, guest executor shutdown, endpoint and marker removal, shim/worker reap, descriptor-inventory restoration, and no new guest runtime root;
real macOS protocol-v9 create interruption at all four Host and five Guest request/dispatch/response transitions, with one exact crossing, nonce-bound Guest cleanup evidence, no normal delete, complete Guest runtime cleanup, and Host endpoint, process, and descriptor restoration, plus both explicit Host shutdown transitions after a successful create, with idempotent owner close and the same complete cleanup evidence;
bounded, versioned macOS HVF soak orchestration that starts a fresh utility VM for every complete two-container lifecycle, namespace-join, rootfs/mount, and PID-supervision matrix, and retains unique endpoint, process, descriptor, marker, runtime-root, and per-wave console evidence;
explicit native Linux driver integration that reuses the shared executor without linking or initializing libkrun;
real native Linux create/state/start/kill/wait/delete SDK evidence on x86_64 and aarch64, including exact repeated SIGKILL status and bounded running wait, plus public SDK exec replay, duplicate process-ID rejection, durable process journals, pidfd signal replay, stable per-process wait, and init-exit exec cleanup, exact init/exec oom_score_adj read-back, plus durable cgroup-v2 pause/resume and exact live process inventory, replay-safe resource update, and normalized stats with real workload-progress evidence, plus controlling PTY allocation, OCI consoleSize initial and resized dimensions, exact init LINUX32 personality, exec CPU affinity before and after workload cgroup membership, interactive I/O, merged output, and VEOF close, repeated with /dev/kvm absent and present but unusable;
type-checked joins for existing UTS, mount, IPC, network, cgroup, PID, user, and time namespaces, including retained rootfs execution after a mount join, three-pass user-namespace permission recovery, and shared native Linux/macOS utility-VM lifecycle evidence;
detached ID-mapped filesystem and bind mounts using exact dedicated or container user-namespace mappings, including native idmap versus ridmap recursion and unchanged source-ownership evidence plus shared native Linux/macOS utility-VM lifecycle evidence;
real native Linux no-delete cleanup after create, start, and kill on x86_64 and aarch64, including init-PID reap and executor, durable-state, marker, and session-root removal;
WHPX partition-object create/delete smoke on Windows;
isolated libkrun shim with a pinned, checksum-verified Windows runtime bundle;
libkrun context create/configure/release smoke on Windows;
real WHPX VM entry, Linux userspace command, virtiofs marker, and natural exit-code smoke on Windows;
real WHPX guest-agent boot through AF_VSOCK and the protected Windows pipe, with exact shim-PID authentication, protocol-v1 negotiation, and retained host/shim evidence;
Linux guest bootstrap executor for an exact fail-closed OCI profile, with a PID-authenticated abstract Unix create/start barrier, create-time UTS, mount, IPC, network, cgroup, PID, user, and time namespaces, parent-installed UID/GID maps, verified time offsets, hostname and domainname, isolated rootfs propagation, ordered OCI mounts with missing target creation, masked and read-only paths, read-only rootfs enforcement, pivot_root, authenticated host-visible PID reporting, exact-generation state, a dedicated namespace PID 1 supervisor with adopted-child reaping, bounded typed init rejection reporting, session idempotency, retained workload pidfd signaling, exact-target exec registries with retained rootfs and namespace descriptors, per-process pidfds and replay journals, stable process wait, cgroup-v2 pause/resume, live process inventory, init-exit supervision, and complete session cleanup;
helper-backed rootless native Linux create/start/exec/signal/wait/kill/delete evidence on x86_64 and aarch64, with container root mapped exactly to the nonzero effective host UID/GID, subordinate UID/GID ranges installed through verified setuid-root newuidmap/newgidmap, setgroups=deny, exact map and ownership read-back, ordered durable events, and complete cleanup;
single-container native Linux runtime ownership behind a private 0600 same-UID Unix SDK endpoint, with an owner-only root, automatic A3S Box FD 3/4/5 binding for one exact container ID, full transported lifecycle evidence, SIGINT/SIGTERM driver shutdown, inode-scoped socket removal, and empty executor-root evidence on x86_64 and aarch64 without KVM;
a long-lived multi-container Native Linux host owner behind the same private same-UID Unix SDK contract. It opens the durable service and experimental driver before publishing runtime.sock, accepts ordinary SDK attachments without Box process-local descriptors, preserves exact recorded-driver and generation routing across reopen, and performs bounded driver shutdown. The explicitly opted-in x86_64 and aarch64 Box production routes now prepare bundles and launch through this owner; default routing, transparent live-session reattachment, and cross-platform cutover remain;
shared Linux executor support for all six OCI hook phases in normative order, with runtime/container namespace placement, exact OCI state on stdin, bounded configuration, timeout and process-group cleanup, typed rollback for every failing prestart through poststart phase, warning-only poststop continuation, and native Linux lifecycle trace evidence;
direct A3S Box compiler compatibility fixture pinned to Box commit d24c951989c8ee8dbc772ccd0021713855613656, with schema/semantic loading and fail-closed executor planning for its absolute rootfs, annotations, capabilities, cgroup v2 resources, exact device allowlist, legacy cgroup mount normalization, and AArch64 seccomp policy;
public-SDK-only A3S Box lifecycle, process-session, filesystem, observability, and resource-control consumer at Box commit a16772c3, with isolation preflight before product reservation, distinct product/runtime identities and generations, exact endpoint/driver/configuration/attachment binding, attachment-schema negotiation before product mutation, stable SDK operation IDs, lost create/start response recovery without duplicate create, stopped-only cleanup, graceful-signal escalation, exact terminal projection, and memory-retaining pause/resume with capability preflight, claim-scoped replay identities, immutable binding validation, and lost-response reconciliation without repeating freezer mutations. The same in-process contract suite now binds captured and streaming exec to the exact OCI generation; rejects unavailable capabilities, stale generations, alternate rootfs, invalid IDs, empty commands, and changed keyed content before a second process can start; proves replay-safe stdin, cursor-checked output, signal/wait, PTY/resize, exact normal and signaled status, raw-log separation, timeout cleanup, and caller-cancellation cleanup. Exact live process targets, normalized stats, and strict ordered-event cursors are rechecked against the same runtime binding. Partial Box resource intent is compiled into one complete OCI contract, claimed before mutation, replayed after a lost response with one runtime effect, and published atomically to both managed restart state and compatibility state. An immutable create-intent digest keeps the original create operation replayable after later resource changes. File upload/download and filesystem stat/mkdir/move/list/remove use the same cross-platform session facade with capability and Box-generation preflight, bounded response conversion, target/shape drift rejection, and one-effect replay of explicitly retryable mutations. Native Linux executes those calls in a bounded parent-death helper that inherits only the retained root plus exact user/mount namespace descriptors, validates descriptor order and uniqueness, and enters the namespaces before applying container IDs. The native fixture now mounts /tmp as tmpfs so the real filesystem smoke covers namespace-owned mounts rather than only the image rootfs. The deterministic cross-process contract now retains the Box process stream and input handle through an observed owner disconnect, then continues inventory, stdin, output, signal, wait, and cleanup after reconnecting to a replacement durable host service. The x86_64 and aarch64 production owner routes and fresh-Box-process stopped-only restart gates now pass; real-driver live-session reattachment plus WHPX, default-routing, and broader cutover gates remain open;
Linux executor enforcement for exact capability sets with real bounding, effective, permitted, inheritable, and ambient kernel read-back, exec bounding ceilings, exact no_new_privileges read-back, private controller-enabled cgroup-v2 management, memory/CPU/cpuset/PID settings and live updates with read-back and rollback, normalized cgroup stats, transactional namespaced sysctls with exact read-back and pre-Create rollback, exact static device nodes within a bounded default-deny profile, and pure-Rust x86_64/AArch64 seccomp BPF retained across init and exec;
versioned control/workload cgroup topology for trusted A3S Box init: exact linux.resources enforcement on a3s-workload, derived outer control-plane headroom, pre-opened FD 6/7 membership handoff, read-only guest cgroupfs, workload-scoped update/freeze/stats, non-group OOM behavior, and complete topology cleanup;
real WHPX fixed-bundle create/state/start/kill/delete evidence, including exact mutation retries, pre-start non-execution, running and stopped observation, marker verification, post-delete NotFound, and nominal leak checks;
direct qualification-only WHPX RuntimeDriver evidence through the exact protected per-generation share, including create/start/kill/wait replay, authenticated shutdown-report publication, stopped-only delete, and process/share/recovery cleanup;
focused real-host WHPX transport regression evidence across one serial and two parallel lifecycles, network namespace, storage, volume-init, nine negative, and four owner-termination cases, including a request above the 4 KiB stream boundary;
a runtime-owned Windows libkrun bundle pinned to the 3 KiB host-to-guest stream segmentation and writable virtio-fs fsync fixes, with deterministic archive and payload checksums;
async, Send + Sync, transport-independent Rust SDK contract;
complete official OCI runtime model pass-through in the SDK;
strict, bounded OCI 1.0.0 through 1.3.0 bundle decoding;
pinned OCI Runtime Specification 1.3.0 schemas and upstream fixtures;
offline configuration, state, and features schema validation;
a CI-checked v2 support lock for all 423 schema properties and enum values: 257 enforced, two validated, 75 rejected as unsupported, 89 rejected as inapplicable native workload platforms, and zero pending or conformant;
a CI-checked inventory of all 764 RFC 2119 occurrences across the 15 normative OCI 1.3.0 documents;
rejection of unknown configuration properties;
immutable SHA-256 binding of the loaded config.json;
public a3s.oci.attachments.v1 derivation and validation for rootfs, mounts, networking, process I/O, secret classifications, and optional runtime extensions, with fail-closed protocol-3 negotiation, durable manifest retention, and exact digest replay;
exact config.json retention and fail-closed SDK wire deserialization;
OCI feature reporting for all eight Linux namespaces, 41 capability names, cgroup v2, x86_64/AArch64 seccomp actions and operators, and ID-mapped mounts, with unsupported managers, flags, and security modules disabled;
phase-aware, bounded common, Linux, and VM semantic validation boundary;
exhaustive SDK request validation on in-process and transport boundaries;
version-negotiated, length-delimited transport for every SDK operation;
tested Windows named-pipe and Unix-domain-socket client connectors;
authenticated, version-negotiated, bounded host/guest lifecycle protocol with exact bundle and response correlation, protocol-v1 compatibility, and protocol-v2 stable init wait plus protocol-v3 exact-target exec, process signal, and process wait messages, all dispatched by the shared Linux executor with version-filtered capability advertisement, plus protocol-v4 pause, resume, and live process inventory, protocol-v5 update and stats, protocol-v6 bounded process I/O, protocol-v7 terminal resize, and protocol-v8 durable process-I/O mutation contexts with exact session replay, plus protocol-v9 descriptor-confined file and filesystem sessions and protocol-v10 bounded Host acknowledgement of completed Guest replay records;
an exhaustive negotiated-version fault registry for all 21 guest operations, spanning four host request/response stages, five guest read/dispatch/write stages, and two host shutdown stages. An authenticated in-memory matrix injects every one of the 189 operation-stage pairs, proves one crossing and terminal disconnect per point. A portable agent-backed RuntimeDriver matrix also arms each of the nine transport stages exactly once for all 20 public workload operations across durable HostRuntimeService reopen. Pre-dispatch faults defer the guest request until the replacement connection; post-dispatch mutation faults replay the guest journal while read-only state and uncached wait observations are safely reissued. A fully written mutation response replays the completed durable record, while a fully written wait response replays its durable terminal cache. Every path preserves the exact generation; mutations retain one effect and reject changed retries, state resolves a current target to that exact generation, wait and wait-process return stable exact exit results while stale targets fail closed, exec preserves the exact process ID, PID, and terminal mode, and signal-process preserves the exact target and signal;
existing features CLI path routed through the Rust SDK;
reconnectable local SDK endpoints that expose the first broken-stream result without hidden replay, discard the poisoned stream, and renegotiate on the next caller-initiated request. Real Windows named-pipe and Unix-socket tests restart the server behind one retained RuntimeClient; caller-supplied from_io streams remain fail-closed and non-reconnectable;
cross-platform runtime-owner process restart coverage that launches two distinct test-binary processes on the same platform-local endpoint and durable HostRuntimeService state root. One retained client exposes owner death, reconnects to the replacement, recovers the exact generation and live exec target, replays create/start/exec with one deterministic test-driver dispatch each, and continues inventory, stdin, signal, wait, output, and cleanup through the replacement owner;
foreground run implemented only as a typed SDK composition of durable create, start, wait, and stable force-delete cleanup;
deterministic durable container enumeration with isolation filtering, complete record validation, host-service reopen evidence, and no driver dispatch;
durable exact-generation lifecycle and process events with global ordered cursors, replay-safe identities, bounded filtering, long polling, crash repair, host-service reopen evidence, and no driver dispatch;
single-writer durable state for the complete core lifecycle, with exact bundle snapshots, monotonic generations, generation fencing, global idempotent create/start/kill/delete journals, active-operation claims, terminal failure replay, crash reconciliation, and quarantine;
deterministic multi-driver registration with one owner per isolation class, identical advertised operation/Hook surfaces, create-time selection, and exact recorded-driver routing across host-service reopen;
async RuntimeDriver integration plus a tested host implementation of create, state, start, kill, delete, and driver-advertised wait, exec, signal-process, wait-process, pause, resume, processes, update, stats, read-output, write-stdin, close-stdin, and resize;
generation-scoped durable process records, global exec, per-process signal, write-stdin/close-stdin/resize, update, File upload, and Filesystem mkdir/move/remove journals, terminal failure replay, active-operation claims, and stable init/exec exit-status caching across host-service reopen;
typed, exhaustive recovery injection at all 741 registered durable commit stages and all 44 before/after RuntimeDriver boundaries, including startup recovery;
a pinned durable-state root capability used for descendant traversal, reads, enumeration, directory creation, file creation, file replacement, and quarantine moves. macOS, Linux, and Windows reject symlink/reparse-point substitution and path replacement; Linux additionally passes a real same-device bind-mount gate;
runtime-owned Windows state paths with protected DACLs limited to the runtime principal and LocalSystem, inheritance disabled, and every applied owner and ACL verified;
Windows, Linux, and macOS CI.

Not yet complete:

equivalent real-host utility-VM transport/reopen qualification for WHPX and the KVM backend; the complete 180-path HVF matrix is retained;
complete shared guest OCI executor;
a production workload driver;
OCI hook rollback, crash recovery, security-negative, and soak certification;
complete Linux configuration enforcement and driver feature parity;
production-ready native Linux execution;
real-driver live process and filesystem session reattachment;
A3S Box default routing and cross-platform real-host cutover;
containerd runtime-v2 task, restart, I/O, and cleanup integration;
versioned storage, networking, reusable-session, checkpoint/restore, and TEE extensions;
upstream conformance and security certification.

The built-in WHPX driver remains probe-only, and the default host service advertises only features. A host explicitly opened around a launch-ready RuntimeDriver advertises the five required core lifecycle operations, host-owned durable list and events, plus only the optional operations that driver implements.

Detailed Workstreams

R0 — Contract And Spec Ingestion

Exit gate: every OCI 1.3.0 schema property is accounted for as accepted, rejected as inapplicable, or rejected because the selected driver cannot enforce it. No property is silently ignored.

R1 — Durable OCI Lifecycle

Exit gate: lifecycle tests pass under fault injection at every durable write and host/agent transition. The durable-write and RuntimeDriver portions pass; the real HVF host/agent operation-stage matrix passes, while equivalent real-driver coverage remains open for the other utility-VM backends.

R2 — Windows WHPX Utility VM

Exit gate: a fresh Windows host test boots a utility VM, runs the fixed OCI bundle, validates negative isolation cases, retains exact terminal evidence across host restart, and leaves no process, handle, or runtime-root leak. Only then may WHPX become experimental.

R2M — macOS HVF Utility VM qualification harness — 15/15 complete

Exit gate: a fresh Apple Silicon host test boots the utility VM, completes the fixed OCI lifecycle through the authenticated guest agent, validates negative isolation cases, and leaves no process, descriptor, or runtime-root leak. Only then may HVF become experimental. The August 13, 2026 Apple Silicon qualification passed the same immutable-image multi-container matrix, all 3 no-delete cleanup points, all 11 transport fault points, all 180 operation replacement paths, the asset/authentication/entitlement negatives, and 25/25 fresh-VM soak waves with 75 primary generations and a stable 10-descriptor baseline. The built-in HVF capability is therefore experimental. That evidence qualifies the historical R2M harness. Separate August 13, 2026 closing runs through the public Host Service passed the three real-host gates above against signed Apple Silicon artifacts, including a complete post-fix rerun after Unix socket path capacity became a configuration-time invariant. An August 14, 2026 revision-bound rerun then covered the Guest-local devtmpfs device-source correction with the same three gates and zero residue. The currently advertised macOS/HVF public product path is therefore 100% function-complete and remains experimental. Signed release-package qualification, upstream OCI conformance, adversarial security review, upgrade and rollback compatibility, and longer release soak remain promotion gates before supported.

The August 15, 2026 focused follow-up closed durable Host journaling for File upload and Filesystem mkdir/move/remove, raised the durable operation schema to v3, and passed all 18 real-HVF File/Filesystem owner-replacement paths. It also passed the unified post-commit acknowledgement contract for all 14 journaled mutations. These are function-completeness fixes; they do not remove the release-promotion gates above.

R2L — Linux KVM Utility VM

Exit gate: a fresh KVM-capable Linux host boots the pinned utility VM, passes the complete SDK and recovery matrices through the authenticated guest agent, and leaves no process, descriptor, cgroup, endpoint, share, or runtime-root leak. Only then may KVM become experimental.

R3 — Shared Linux Executor And Guest Agent

Exit gate: the same executor passes its lifecycle, configuration, security, and recovery suites in the Windows guest and on native Linux.

R4 — Native Linux Without KVM

Exit gate: A3S Box Sandbox and its Rust, Python, TypeScript, and Go SDK tests pass on supported x86_64 and aarch64 Linux hosts without KVM.

R5 — Full OCI 1.3 Conformance

Complete common configuration and process semantics and bind every accepted or rejected field to the zero-pending normative evidence ledger. The pinned gate freezes all 79 common configuration schema items outside the separately reviewed VM section: 69 are enforced, two are validated, four unsupported Linux process fields are rejected, and four native non-Linux sections are rejected as inapplicable. All 278 config.md requirements are frozen as 227 enforced, 35 validated, 13 reviewed external, and three conformant entries with no pending owner. Arbitrary annotation keys and values remain exact JSON metadata through bundle decoding and Linux executor planning, including escaped NUL and control characters; they are not incorrectly treated as C strings. Empty keys and bounded resource limits still fail closed. This closes common configuration semantics, not Linux configuration, cross-driver lifecycle, security, or release conformance.
Complete Linux configuration enforcement and generate feature reporting from the same driver-specific support data used by validation and execution.
Complete applicable VM configuration semantics without executing untrusted hypervisor, kernel, or firmware paths during validation. The pinned gate freezes all 26 VM-related schema items and all 24 normative VM requirements: four absolute runtime-path requirements are semantically validated, while the remaining 20 requirements and every caller-provided hypervisor, kernel, image, and hardware field are bound to the selected driver's fail-closed runtime-owned-asset policy. Dedicated negative evidence rejects NUL bytes in every executable VM path and parameter. The Host Service rejects the complete schema-valid vm section before durable generation reservation, bundle handoff, platform mutation, or mutating driver dispatch. This closes bundle-supplied VM configuration semantics, not utility-VM lifecycle, security, real-host, or packaged-artifact qualification.
Pass the pinned OCI JSON schema suites for config, state, and features using fixtures emitted by every advertised driver profile. The exhaustive SDK gate runs all 19 vendored positive, schema-negative, and malformed-JSON cases and SHA-256-binds the exact fixture inventory and canonical LF text. A separate Host Service matrix validates the checked-in Native Linux, Linux KVM, macOS HVF, and Windows WHPX configurations, each generated Features document, and created, running, and stopped State documents. This closes schema compatibility only, not the remaining semantic, lifecycle, security, or release-artifact gates.
Pass upstream lifecycle validation tools on every supported platform and architecture using the exact packaged runtime binaries.
Cross-check supported bundles with upstream OCI lifecycle validation tools without shipping a second runtime backend.
Run hook-order, rollback, crash-recovery, security-negative, and long-running soak suites on every advertised driver profile.
Publish an exact, generated support manifest with no unclassified field. The schema-support v2 lock records 257 enforced, two validated, 75 rejected unsupported, 89 rejected inapplicable, zero pending, and zero conformant items. This closes field classification only; release conformance still requires the remaining lifecycle, security, cross-driver, upstream-tool, and packaged-artifact gates above.

Exit gate: the release report contains retained evidence for every applicable normative MUST and MUST NOT requirement in OCI Runtime Specification 1.3.0.

R6 — A3S Box Migration

The Native Linux side now exposes a packaged, long-lived multi-container host service suitable for the unified Box adapter. Box persists an explicit box_vm or oci_sdk route before preflight, prepares its product resources and minimal OCI bundle, and passes the opt-in x86_64 and aarch64 production-owner composition through all four SDKs. Separate gates on both architectures now prove owner/Box process restart with safe stopped-only reconciliation and explicit next-generation restart. The broader gate remains unchecked until live session reattachment passes on the real driver, the same production composition passes WHPX, and the default/MicroVM cutover is complete. OCI Runtime independently proves that abrupt Native Linux owner death safely terminates and reconciles the exact generation without inventing terminal evidence.

R7 — containerd Runtime V2

Define the supported containerd runtime-v2 API and version matrix, the shim binary and package layout, and the exact mapping from containerd namespace and task identity to OCI container ID and runtime generation.
Load the containerd-provided OCI bundle and translate create, start, state, wait, kill, delete, exec, resize, close-I/O, and stats operations into public a3s-oci-sdk calls without invoking A3S Box or importing driver internals.
Preserve containerd stdin/stdout/stderr and terminal semantics through the SDK's bounded process-I/O contract, including reconnect, EOF, resize, exact exit status, and cancellation cleanup.
Reconcile shim and containerd restart at every lifecycle boundary using the runtime's durable generation and operation identities; prove that restart never duplicates a mutation, reroutes a driver, or invents process state.
Run real containerd and ctr integration suites for lifecycle, exec, I/O, signals, stats, restart, forced cleanup, stale identity, and parallel tasks against every advertised driver profile.
Publish the shim with signed or checksummed runtime packages and retain the exact containerd, shim, SDK, runtime, and driver compatibility record.

Contract v1 now freezes containerd.task.v2.Task, the exact 16 implemented methods and explicit Checkpoint gap, runtime type io.containerd.a3s-oci.v2, binary and Linux archive entry containerd-shim-a3s-oci-v2, installation at /usr/local/bin/containerd-shim-a3s-oci-v2, the exact compatibility matrix, and sha256-length-framed-u64be-v1 identity vectors. Tagged Linux archives include the shim and contract document; RuntimeInfo exposes the contract, identity, generation, and exact development-qualification annotations. The same code-owned contract now freezes 23 exact Task and FIFO-pump routes and derives their 18-operation public-SDK union. Endpoint admission consumes that union directly, version and RuntimeInfo output expose it, and manifest tests reject A3S Box, Runtime implementation, Agent, or Core dependencies in the shim crate.

Current Native Linux development evidence covers containerd 2.2.2 lifecycle, exec, pause/resume, update, stats, PID inventory, exact init and exec exits, separate stdout/stderr plus stdin from empty input through 4 MiB, Created/Running/Stopped daemon-restart boundaries, terminal exec resize before and after daemon restart, schema-v8 durable exec incarnations plus init/exec stdin, signal, and resize sequences, exact pending input payloads, signals, and terminal sizes, Open/Closing/Closed stdin state, output cursors, and per-task control sequencing, live terminal-exec input and output continuation without replay after manual shim replacement, including a pending WriteStdin operation committed remotely before the replacement can observe its response and replayed with exactly one input effect, plus a committed CloseStdin boundary that persists Closing, loses the original response, replays through the replacement, commits Closed, and delivers one terminal EOF effect without reopening its FIFO, plus a committed exec SignalProcess boundary that retains sequence 1 SIGSTOP as pending, commits it remotely, replaces the shim, joins the completed operation, and then proves the real process transitions through SIGCONT→SIGSTOP→SIGCONT under fresh sequences 2 through 4, stale task incarnation and runtime-generation replacement, a four-task parallel Create/Start/running-restart/137-cleanup matrix, and exact cleanup after shim SIGKILL with init Created or Running and exec Added or Running. A durable pre-generation create intent now also replays an in-flight Create through its exact incarnation and operation identity after shim SIGKILL, obtains the one runtime generation, and force-cleans it without task, process, bundle, or runtime-state residue. A post-commit Start boundary runs the exact stable Start identity while shim metadata still records Created, then kills the shim and proves bounded DeleteShim cleanup terminates and deletes that running exact generation. A separate post-commit Delete boundary removes the exact runtime generation before killing the shim, then proves DeleteShim treats only that generation's NotFound result plus a successful replay of its stable normal or force Delete identity as a completed remote effect. It then finishes local metadata, rootfs, and bundle cleanup without touching caller-owned container metadata; unconfirmed state loss fails closed. A post-commit Exec boundary submits the exact stable generation-scoped process identity while shim metadata still records the exec as Added, verifies its live PID, then proves DeleteShim reaps both init and exec and removes the exact generation without touching caller-owned metadata. A post-commit SignalProcess boundary starts an exec, suspends the shim before submitting its exact stable SIGKILL identity directly to the runtime, observes the exact signal-9 exit while the init remains Running at its original PID, then kills the stopped shim and proves bounded cleanup removes both processes and the exact generation. A post-commit Kill boundary also submits the exact stable SIGSTOP mutation against a running generation, kills the shim while the stopped process remains live, and proves bounded cleanup delivers the terminal signal and reaps the exact PID. Post-commit Pause, Resume, and PID-limit Update boundaries retain the same exact generation, verify the real paused state or applied pids.max, then kill the shim and prove the same bounded cleanup converges without leaked cgroups or processes. Paused cleanup uses the exact force Delete operation so the runtime thaws and stops the generation as one cleanup operation instead of waiting on a frozen terminal signal. Repeated controls now use a monotonically increasing durable sequence instead of one fixed operation identity: two different Updates and two complete Pause/Resume cycles dispatch distinct mutations, identical completed retries do not dispatch twice, concurrent same-task controls are serialized, and an in-flight retry retains the same sequence across shim metadata reopen. Canonical JSON request fingerprints keep unordered resource maps stable across shim, host, and guest reconstruction. Runtime operation schema v2 records that encoding explicitly while retaining schema-v1 retry validation with the legacy serializer. The August 14, 2026 Ubuntu arm64/containerd 2.2.2 release build also freezes the Runtime before a terminal ResizePty, persists the next per-exec sequence and size, freezes the original shim, commits that exact Resize directly, and replaces the shim before its local journal can observe the response. The replacement replays the same sequence without a second terminal effect, commits the observed size, suppresses an identical retry, and proves that A→B→A allocates fresh identities and restores the real PTY to A instead of replaying the first A. The latest gate also runs one exec to exit 7, deletes it, reuses the same containerd exec ID, restarts containerd while the replacement is Added, and requires exit 23 from a fresh SDK process identity. Its durable per-task exec sequence survives DeleteProcess; exit monitors are incarnation-bound so a late result cannot terminate or poison the replacement. The latest qualification also releases each Native Linux guest mutation record only after its Host result is durable, including every derived chunk identity for a stdin payload larger than the 4 MiB guest frame limit. Three complete 46.92, 47.39, and 47.23-second matrices passed consecutively through Host PID 3605 with installed shim SHA-256 a0e7dce493308ebea0b4642dd81a9e489109a8b3709f2a1ede62b015cc123482. The matching Host and agent SHA-256 values were f097da3529c47a06b32271550417ed810d698a2a6e385f122771c197b7de2b67 and be0b13215c21a2312f8a3e8d79cc9a39ed1a4b07b539f3d557e0f4e168c3345a. The qualification recreates the killed task ID with a new incarnation and generation and leaves no matching task, container, shim, agent child, workload process, bundle, live runtime record, prepared Host operation, session, marker, workload cgroup, or zombie. The remaining R7 items stay open until the remaining failure boundaries, every advertised driver profile, and the published release-artifact compatibility record pass.

Exit gate: containerd task, restart, I/O, and cleanup suites pass through the public SDK without the Box CLI, a direct VMM path, duplicate lifecycle state, or leaked runtime resources.

R8 — Optional Parity Extensions

Add versioned extension discovery and negotiation so an optional operation is advertised only when the selected driver and exact release artifact passed its own gate.
Accept already-authorized storage attachments with immutable identity, access mode, ownership, and cleanup contracts while leaving named-volume and snapshot policy in A3S Box.
Accept already-authorized network attachments with exact namespace, interface, and cleanup identities while leaving IPAM, DNS, and network policy in A3S Box.
Add reusable guest-session ownership with trust-domain, isolation, generation, capacity, reset, and leak fences; never reuse a guest across an incompatible or undeclared trust boundary.
Implement checkpoint and restore as generation-fenced SDK operations with immutable artifact identity, compatibility validation, durable replay, rollback, and exact restored-process evidence.
Carry TEE launch measurements and attestation evidence through typed SDK contracts without moving attestation authorization or product policy into the runtime.
Run Box storage, networking, warm-session, snapshot, restart, and security suites through only the public extensions on each driver that advertises them.

Exit gate: every advertised extension has a versioned contract, fail-closed capability report, recovery semantics, exact release-artifact evidence, and a passing Box consumer gate. Unadvertised optional extensions do not block a supported core runtime release.

Platform Promotion

Driver	Probe-only	Experimental	Supported
Windows libkrun/WHPX	Capability and partition smoke	Fixed bundle plus full SDK lifecycle	OCI, security, recovery, and soak gates
Native Linux	Host feature inventory	Full A3S Box Sandbox suite without KVM	OCI and adversarial gates on x86_64/aarch64
Linux libkrun/KVM	KVM capability evidence	Same guest lifecycle as WHPX	Driver-specific isolation and soak gates
macOS libkrun/HVF	HVF capability and signed VM-object evidence	Same guest lifecycle as WHPX	Driver-specific isolation and soak gates

Promotion is monotonic and evidence-based. Host hypervisor availability alone never enables workload launch.

Commit And Integration Policy

Each coherent, tested increment is committed and pushed to git@github.com:A3S-Lab/OCI-Runtime.git. The a3s monorepo gitlink is updated only after the runtime commit is remotely available and all focused checks pass. Unrelated dirty submodules are never staged.