Release notes

Release notes#

0.1.0-beta.1 — preparation#

This is the first beta publication candidate, not a publication record. The maintainer publishes and approves the tag separately. The last published Rust milestone is 0.1.0-alpha.1 from 7cc48490; beta.1 is 0.1.0b1 on PyPI. No Python release predates it. OrbiTE is a transfer engine for LLM inference on NVIDIA; scope and non-goals separate byte movement from the consumer’s cache and discovery policy.

Changes since alpha.1#

  • Rust is primary; Python is a PEP 8 binding to the same retained owners. The Rust inventory and Python inventory describe today’s surface, not a freeze. Public enums and field records are non-exhaustive except TransferOp. NVLinkStats became NvlinkStats, MemType became TopologyMemoryKind, and MemoryBacking is the retained backing type. Hidden binding helpers require the Python crate’s exact core-version pin.

  • TENT wire, API, configuration and naming compatibility are removed. TentSettings, from_tent_*, MC_TENT_CONF, legacy environment mappings, TENT-shaped Python names and transport-ID conversions are gone. Use EngineConfig::from_json/from_file/from_env; only ORBITE_CONF selects an environment document. Unknown keys and wrong types fail. Metrics use orbite_ names. Frozen TENT v0.3.14 remains the design reference, CPU oracle and performance baseline, not a runtime dependency.

  • C ABI, C++/classic-TE adapters, device plugin ABI and diagnostics C exports are removed. The CLI is orbite diagnostics version [--json], replacing tent. Python ships no tent or mooncake.engine alias.

  • Discovery is P2P-only. Consumers publish endpoint and authoritative source epoch. Rust close_segment fences a peer, drains it and reclaims identities after their last reference; uncertain cleanup stays retained and charged. Python segment close remains reversible handle invalidation.

  • FABRIC/libfabric is excluded: NVIDIA platforms only; AWS EFA is a non-goal. Its feature, transport, configuration and metrics are removed; remaining transport discriminants are unchanged. CUDA fabric handles and MNNVL/EGM are unaffected. MPComm is deferred: no consumer or available provider.

  • File vectors accept retained host/CUDA ranges and padding: zero-fill on WRITE, discard on READ, with completed-prefix semantics. Runtime GDS disable and lazy probing preserve feature isolation and strict explicit selection.

  • rdma.gpu_direct_registration = auto | dmabuf | peermem adds a checked, fail-closed CUDA dma-buf route with optional verbs symbol lookup. Explicit Direct registration never silently becomes staging. Export flags remain zero; Grace topology-specific PCIe forcing is not implemented. The opt-in GPU source reuse route remains unqualified.

  • Local-copy submit(direction, descriptors, LocalCopyOptions) replaces the optional event argument; options carry intent, priority and readiness. kernel_cta_limit bounds the grid; kernel_threshold_background defaults to usize::MAX, keeping background DeviceToHost Auto on DMA until calibration. None retains the original CTA budget; normal Auto uses 128 compiled DMA operations. LocalCopyStats adds per-class diagnostics and is no longer Copy. Forced backends, overlap ordering and event-retained owners remain. These APIs are Rust-only; installed calibration is unrun.

  • TCP reuses bounded, epoch-scoped streams. Small eligible host-file work can complete on the caller with a deadline-bounded wait of at most 200 µs. Unfinished rings transfer to the existing drain owner without resubmission. Worker exit/start failures retain submitted owners as sticky Unquiesced; exceptional GDS group paths settle common admission and metrics accounting.

Qualification and limits#

Profile on this source

Evidence / limit

TCP DRAM, configuration

Qualified on Linux CI: named jobs and controls; loopback/multiple processes, not physical two-host qualification

HP-TCP, SHM

Qualified on Linux CI: loopback rails and same-host DRAM; no physical multi-rail or CXL claim

io_uring DRAM/file

Qualified on Linux CI: real ext4/tmpfs; unavailable kernels fail explicitly

Python CPU/TCP and quickstart

Installed-wheel CI, CPython 3.10–3.14, Linux x86_64/aarch64; exporter lifetime and GIL controls remain. Including native features in a wheel does not qualify hardware

GPU, RDMA, GDS, NVLink, MNNVL/EGM, CXL and physical rails

Implemented; installed profiles unqualified on this artifact. Older H20/RoCE artifacts qualify only their recorded revisions. Verification queue

Missing public documentation remains a pre-0.1.0 gate: close the findings and turn the audit into -D missing-docs. The NIXL plugin is not implemented; its upstream and hardware prerequisites remain separate.

Known performance limits#

These are byte-checked CPU-runner measurements, not general speed guarantees. Benchmarks pins revisions, hosts, sample counts and every row; raw results remain CI artifacts. p99 uses 100 samples per trial. Timed WRITEs exclude durability barriers. There is no GPU, RNIC or physical NVMe claim.

Workload

Recorded result / remaining limit

Scattered 64 × 4 KiB TCP

READ p50 8.59→4.23 ms; WRITE 9.33→6.30 ms, still 3.7% above TENT’s 6.07 ms on the paired runner. Single 4 KiB READ CPU falls 370→190 µs; TENT 256 µs. One exclusive lane per peer has no concurrent-caller performance claim

Small tmpfs WRITE (#193)

4 KiB p50 117.9→57.3 µs on stable and 192.8→76.1 µs on 1.85; after/TENT 1.02×/0.96×. A missed caller window still needs worker drain

Bounded-wait trade-off (#193)

Stable tmpfs 4 KiB READ p50 +9.3%; ext4 64 KiB WRITE p99 331→544 µs (+64.4%), separate trial ranges. A miss can delay handoff; its contribution versus VM/device variation is not isolated

Clean-harness ext4 tail (#186)

Rust 1.85 gapped WRITE p99 16.26 ms versus TENT 3.59 ms, overlapping three-trial ranges. Bulk-verifier and offered-load counterfactuals reproduce the tail in unchanged TENT. This stays a P11 limit; physical NVMe measurement is in the hardware batch, with no more virtual-disk tuning planned

Other TCP regression

Rust 1.85 64 MiB READ p50/p99 +2.8%/+10.7% while CPU falls 4.2%; wake latency versus host variation is not isolated

Earlier S26 ext4 values are old-harness evidence: truncate/rewrite reset writeback overlapped 31,999 of 32,000 measured windows. Both harnesses now preallocate once, reset in place and fdatasync before timing; zero fixed windows contained reset writeback. The intermediate clean-reset comparison still used different verification reads. Keep those historical tables under reset isolation and the subsequent block-layer comparison; they are not current release performance claims.

Compatibility boundary#

Breaking Rust/Python API changes remain allowed before 0.1.0, including between betas. The 0.1.x API and wire freeze begins at 0.1.0: same-0.1.x peers will interoperate, with breaking API or wire changes requiring a minor bump under 0.x semver. Until then, both peers must run the same build. The native control-plane VERSION remains 1 and cannot detect a build mismatch; there is no pre-0.1.0 compatibility promise. See the wire rule. Timeout, cancellation and logical terminal status never substitute for physical retirement, and an uncertain WRITE is never replayed.

Maintainer publication procedure#

This section configures a future publication. This PR creates no tag, package publication or GitHub Release. Source versions stay 0.1.0-beta.1 and 0.1.0b1. Only the maintainer approves publication.

One-time setup#

Use PyPI Trusted Publishing and crates.io Trusted Publishing, so neither job stores a long-lived registry token. The crate already exists under owner feichai0017; the Python distribution is a pending publisher until its first successful upload (a pending publisher does not reserve the name).

  1. In repository Settings → Environments, create pypi and crates-io. Each must require a maintainer reviewer (for example feichai0017), prohibit administrator bypass, and allow deployment tags matching v* only, no branches. If the sole maintainer also starts the run, leave “prevent self-review” off so that their separate approval is possible; enabling it requires a second authorized reviewer. Do not run a publishing tag before these protection rules exist. GitHub must offer required reviewers for the repository’s visibility/plan.

  2. In the maintainer’s PyPI account, Publishing → Add a new pending publisher: project orbite, owner OrbitInfra, repository OrbiTE, workflow filename release.yml, environment pypi. Confirm the name remains available. After first upload, manage the publisher under the project’s Publishing tab.

  3. As the existing crates.io owner, add a GitHub trusted publisher to orbite: owner OrbitInfra, repository OrbiTE, workflow release.yml, environment crates-io. No publisher is configured for the unpublished Python Rust crate.

  4. Allow the pinned official publishing actions. Only the two protected jobs receive id-token: write. Only the final GitHub Release job receives contents: write. Build/test jobs have read-only repository access.

The published wheels are the combined RDMA/CUDA/io_uring/GDS/metrics profile, one for each CPython 3.10–3.14 × Linux x86_64/aarch64. They are built in pinned official manylinux 2.28 images with maturin --manylinux 2_28, supporting glibc 2.28 and newer (including RHEL/Rocky 8 and Ubuntu 20.04). No dependency requires a newer glibc. The artifact check rejects grafted verbs/provider, CUDA and cuFile libraries; ELF checks reject linked verbs symbols. Every publication wheel runs the unchanged quickstart in a separate container without those libraries. CPU quickstarts need none of them. Configured GPU/RDMA/GDS paths need the host’s NVIDIA driver, rdma-core/providers and cuFile respectively, and remain unqualified on hardware for this artifact. The sdist uses the same profile and its rebuild requires native build headers. CPU + io_uring and MSRV wheels remain review artifacts; profiles share filenames and must never be uploaded together.

Build dependency installation checks dpkg -s first. Only absent packages are requested, with at most three 180-second update/install attempts that alternate the runner mirror and Ubuntu’s archive (ports on aarch64). Exhaustion is fatal. No failed test job is retried automatically. The workflow recovery hook retries only an initial failed run whose created jobs all succeeded or were skipped, the GitHub uncreated-matrix failure case. Tag and dispatched release runs are excluded; their registry receipts always require manual review.

Review and dry run#

A pull request from a release/ branch runs release.yml as a dry run. It calls the ordinary CI, wheel and oracle jobs once; their standalone PR instances skip only to avoid duplicate copies of those same jobs. After merge, the maintainer can also run:

gh workflow run release.yml --repo OrbitInfra/OrbiTE --ref main -f dry_run=true
gh run list --repo OrbitInfra/OrbiTE --workflow release.yml
# Choose the displayed run ID; then watch and download its tested artifacts.
gh run watch RUN_ID --repo OrbitInfra/OrbiTE --exit-status
gh run download RUN_ID --repo OrbitInfra/OrbiTE --name release-artifacts --dir release-artifacts
(cd release-artifacts && sha256sum -c SHA256SUMS)

The workflow checks versions, exact Python core pin and tag, reruns both Rust toolchains/all CI features, strict docs and docs.rs without verbs headers, the frozen oracle/480-row comparisons, all wheels and the sdist rebuild. It installs and runs the packaged quickstarts. Package allowlists reject logs, traces (except the frozen CPU fixture), generated HTML and hardware run output. The reviewed set contains ten wheels, one sdist, one .crate, SHA256SUMS and these release notes. Dry runs cannot obtain registry credentials or publish.

Approved publication and partial failure#

Only after separate approval, from the accepted clean commit:

git switch main
git pull --ff-only
# Verify HEAD is the approved release-preparation commit before creating the tag.
git tag -a v0.1.0-beta.1 -m 'OrbiTE 0.1.0-beta.1'
git push origin refs/tags/v0.1.0-beta.1

The tag starts a fresh gate/build run. Mismatched tags fail, including during dry runs. Approve each environment only after reviewing the gates and artifact hashes. The publishing jobs run once, verify registry SHA-256 receipts, and only then create a prerelease on GitHub for the existing tag with notes and checksums. Receipt visibility can lag a successful upload: the checker polls missing entries or HTTP 404 within a 60-second budget, at most 13 reads. A different checksum or other read error fails immediately. This never repeats an upload. No branch/manual run can publish unless its ref is that matching tag. For an existing tag, an explicitly approved manual run uses gh workflow run release.yml --ref v0.1.0-beta.1 -f dry_run=false; do not use it to blindly repeat a partly successful publication.

If one registry fails, the workflow summary preserves the other’s result and creates no GitHub Release. A failed upload may already have published some files. Compare PyPI’s version JSON filename/digest list and crates.io’s version checksum with the retained SHA256SUMS before recovery. Do not move the tag, rebuild a different artifact under the same version, enable skip-existing, or rerun successful publishing jobs. A maintainer may rerun only a failed job once they establish that it uploaded nothing. For partial PyPI uploads, approve a recovery uploading only the missing files from the original checked set; for a verification/network failure after upload, verify receipts read-only. python3 scripts/verify-registry.py pypi release-artifacts and the crates-io variant perform those checks without uploading. Create the GitHub Release only after both complete receipts are verified. No automatic recovery or deletion of published versions is part of this workflow.

Contents