rsyscall-ng 0.1.0__tar.gz

rsyscall_ng-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Andrés Planchón Prestes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rsyscall_ng-0.1.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include LICENSE NOTICE README.md pytest.ini Makefile
+include python/ffibuilder.py python/setup.cfg
+include python/rsyscall/tasks/ssh_bootstrap.sh
+include native/Cargo.toml native/Cargo.lock native/README.md
+recursive-include native/core *
+recursive-include native/rsyscall *
+recursive-include docs/spec *
+recursive-include scripts *
+recursive-include tests *
+prune native/target
+prune native/prefix
+prune reference
+exclude python/rsyscall/_raw*.so python/rsyscall/_raw*.c
+# prebuilt native artefacts are not source: a bundled build regenerates them (setup.py)
+exclude python/rsyscall/_native/librsyscall.so python/rsyscall/_native/rsyscall-*
+global-exclude __pycache__ *.py[cod]

rsyscall_ng-0.1.0/Makefile

@@ -0,0 +1,95 @@
+SHELL := bash
+BACKEND ?= c
+export BACKEND
+.PHONY: help oracle native native-test venv preflight hello baseline baseline-diff test probe probe-diff spec-check wheel wheel-manylinux wheel-test sdist sdist-test clean-venv clean-reference clean-native clean-dist
+
+help:
+	@echo "targets (BACKEND=c|rust selects the native implementation; default c):"
+	@echo "  oracle           clone upstream at the pinned commit into reference/ and build its C library (backend c)"
+	@echo "  native           build the clean-room Rust native side and install it into native/prefix (backend rust)"
+	@echo "  native-test      run the Rust crate's own tests (cargo test -p rsyscall-core)"
+	@echo "  venv             create the backend's venv and install python/ (editable) against its prefix"
+	@echo "  preflight        check that the venv loads librsyscall from the backend's prefix"
+	@echo "  hello            smoke test: clone a process, write to its stdout, exec echo"
+	@echo "  baseline         run the suite, one interpreter per test, and write tests/baseline-<backend>.txt"
+	@echo "  baseline-diff    compare tests/baseline-c.txt with tests/baseline-rust.txt (header line ignored)"
+	@echo "  test             run pytest; pass arguments with PYTEST_ARGS='...'"
+	@echo "  probe            run the black-box probes against the backend's helper executables"
+	@echo "  probe-diff       run the probes against both backends and diff the normalised output"
+	@echo "  spec-check       verify docs/spec: generated layouts and vectors are current, citations valid"
+	@echo "  wheel            build the wheel (bundles the Rust native side) into dist/"
+	@echo "  wheel-manylinux  check the wheel (auditwheel, abi3audit) and retag it as manylinux_2_17 (uvx)"
+	@echo "  wheel-test       install the newest wheel into a throwaway venv and exercise it away from the source tree"
+	@echo "                   (RSYSCALL_WHEEL_PYTHON=3.12|3.13|3.14 selects the interpreter; default 3.14)"
+	@echo "  sdist            build the source distribution into dist/"
+	@echo "  sdist-test       build a wheel from the sdist outside the repository, as pip would (cargo included), and test it like wheel-test"
+	@echo "  clean-venv       remove both venvs and in-tree build artifacts"
+	@echo "  clean-reference  remove reference/ (oracle clone and build)"
+	@echo "  clean-native     remove native/prefix and native/target"
+	@echo "  clean-dist       remove dist/, build/ and the bundled artefacts copied into python/rsyscall/_native/"
+
+oracle:
+	scripts/oracle-build.sh
+
+native:
+	scripts/native-install.sh
+
+native-test:
+	cargo test --manifest-path native/Cargo.toml -p rsyscall-core
+
+venv:
+	scripts/venv-setup.sh
+
+preflight:
+	scripts/preflight.sh
+
+hello: preflight
+	source scripts/env.sh && "$$PY" scripts/hello.py
+
+baseline: preflight
+	source scripts/env.sh && BASELINE_OUT="$$ROOT/tests/baseline-$(BACKEND).txt" "$$PY" scripts/baseline.py $(PYTEST_ARGS)
+
+baseline-diff:
+	@diff <(sed 2d tests/baseline-c.txt) <(sed 2d tests/baseline-rust.txt) && echo "baselines identical (header line ignored)"
+
+test: preflight
+	source scripts/env.sh && "$$PY" -m pytest $(PYTEST_ARGS)
+
+probe:
+	source scripts/env.sh && for m in stdin stub stublong bootstrap; do python3 scripts/probes/probe_oracle.py "$$PREFIX/libexec/rsyscall" $$m; done
+
+probe-diff:
+	scripts/probe-compare.sh
+
+spec-check:
+	source scripts/env.sh && "$$PY" scripts/abi-layouts.py --check docs/spec/abi-layouts.generated.md
+	source scripts/env.sh && "$$PY" scripts/spec-vectors.py --check docs/spec/vectors/v0.json
+	python3 scripts/spec-lint.py
+
+clean-venv:
+	rm -rf .venv .venv-rust python/rsyscall/_raw*.so python/rsyscall/_raw*.c python/build python/*.egg-info
+
+clean-reference:
+	rm -rf reference
+
+wheel:
+	rm -rf dist build && uv build --wheel --out-dir dist .
+
+wheel-manylinux:
+	uvx --with patchelf --from auditwheel auditwheel repair --plat manylinux_2_17_x86_64 -w dist dist/rsyscall_ng-*-linux_x86_64.whl && rm dist/rsyscall_ng-*-linux_x86_64.whl
+	uvx abi3audit --strict --summary dist/rsyscall_ng-*-manylinux*.whl
+
+wheel-test:
+	scripts/wheel-test.sh
+
+sdist:
+	rm -f dist/rsyscall_ng-*.tar.gz && uv build --sdist --out-dir dist .
+
+sdist-test: sdist
+	scripts/wheel-test.sh "$$(ls -t dist/rsyscall_ng-*.tar.gz | head -1)"
+
+clean-native:
+	rm -rf native/prefix native/target
+
+clean-dist:
+	rm -rf dist build python/rsyscall/_native/librsyscall.so python/rsyscall/_native/rsyscall-* *.egg-info python/*.egg-info

rsyscall_ng-0.1.0/NOTICE

@@ -0,0 +1,71 @@
+rsyscall-ng -- provenance and licensing notice
+==============================================
+
+1. New code in this repository (everything outside python/, plus all changes
+   made here to python/) is Copyright (c) 2026 Carlos Andrés Planchón Prestes
+   and is released under the MIT License. See LICENSE.
+
+2. python/ is derived from the Python package of catern/rsyscall
+   (https://github.com/catern/rsyscall). It was imported with its full git
+   history using `git filter-repo --subdirectory-filter python
+   --to-subdirectory-filter python` from upstream commit
+   2a362099610a664caeb7f06dd805e5a0fb80cd08 (2022-07-25).
+
+   Copyright (c) 2018-2022 Spencer Baugh and contributors.
+
+   License: MIT, as declared by the upstream package metadata:
+     - python/setup.py: license='MIT' and the classifier
+       "License :: OSI Approved :: MIT License";
+     - the PKG-INFO of the rsyscall 0.0.3 source distribution published on
+       PyPI (https://pypi.org/project/rsyscall/0.0.3/), which declares
+       "License: MIT".
+   Upstream ships no LICENSE file; a request to add one is open at
+   https://github.com/catern/rsyscall/issues/11. The MIT License text that
+   applies to the upstream Python code is reproduced below.
+
+3. Deliberately NOT included in this repository: upstream c/ (librsyscall,
+   its assembly routines and the helper programs rsyscall-server,
+   rsyscall-bootstrap, rsyscall-stdin-bootstrap and rsyscall-unix-stub),
+   nixdeps/, docs/, research/ and the Nix build files at the upstream root.
+   The licensing of c/ is not declared anywhere upstream. This repository
+   only builds it locally, unmodified, from a clone placed under the
+   gitignored directory reference/ (see Makefile and scripts/), as a test
+   oracle for the differential test-suite. It is never redistributed here.
+
+4. "rsyscall" is the name of the upstream project. This repository is an
+   independent modernization effort and is not endorsed by upstream.
+
+5. native/ is new code under the MIT License (item 1). It reimplements the
+   native side of rsyscall from scratch as a clean-room work: it was written on
+   2026-09-29 from the specification in docs/spec/ alone, by an agent whose
+   read access excluded reference/, every C and assembly source and the Python
+   internals; the specification itself had been derived exclusively from the
+   MIT-licensed python/ tree (docs/spec/README.md §4). The reviewer, who had
+   read the upstream C earlier for an unrelated analysis, authored none of the
+   specification or of native/ and reviewed both against docs/spec/ only. The
+   upstream binaries built under reference/ served solely as a black-box test
+   oracle (recorded test outcomes and observed behaviour). See
+   native/README.md.
+
+----------------------------------------------------------------------
+MIT License (upstream python/ code)
+
+Copyright (c) 2018-2022 Spencer Baugh and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rsyscall_ng-0.1.0/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: rsyscall-ng
+Version: 0.1.0
+Summary: Process-independent, type-safe, low-level interface to Linux system calls: rsyscall modernized, with a clean-room Rust native side
+Author: Carlos Andrés Planchón Prestes
+License-Expression: MIT
+Keywords: linux,syscall,distributed,trio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Classifier: Framework :: Trio
+Classifier: Topic :: System :: Operating System Kernels :: Linux
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: cffi>=1.15
+Requires-Dist: trio>=0.25
+Requires-Dist: outcome>=1.3
+Requires-Dist: typeguard>=2
+Provides-Extra: rsysapps
+Requires-Dist: h11; extra == "rsysapps"
+Provides-Extra: net
+Requires-Dist: pyroute2; extra == "net"
+Dynamic: license-file
+
+# rsyscall-ng
+
+![rsyscall-ng: process-independent Linux syscalls for Python](https://raw.githubusercontent.com/carlosplanchon/rsyscall-ng/main/assets/banner.jpg)
+
+A modernization of [rsyscall](https://github.com/catern/rsyscall), the
+process-independent, type-safe, low-level interface to Linux system calls for
+Python. In rsyscall every syscall is a method on a *process object*, which may
+be the local interpreter, a child created with `clone`, or a process on a
+remote host; new processes start out sharing everything with their parent and
+are then shaped with ordinary syscalls (`unshare`, `execve`, ...) instead of
+`fork`/`posix_spawn`.
+
+[![CI](https://github.com/carlosplanchon/rsyscall-ng/actions/workflows/ci.yml/badge.svg)](https://github.com/carlosplanchon/rsyscall-ng/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/rsyscall-ng.svg)](https://pypi.org/project/rsyscall-ng/)
+[![Python versions](https://img.shields.io/pypi/pyversions/rsyscall-ng.svg)](https://pypi.org/project/rsyscall-ng/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/carlosplanchon/rsyscall-ng/blob/main/LICENSE)
+[![Platform: Linux x86_64](https://img.shields.io/badge/platform-Linux%20x86__64-blue.svg)](https://github.com/carlosplanchon/rsyscall-ng#quick-start)
+[![DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/carlosplanchon/rsyscall-ng)
+
+## What it looks like
+
+A process object runs system calls in the process it stands for. Here that is a
+child of the interpreter:
+
+```python
+import trio
+from rsyscall import local_process
+
+async def main():
+    child = await local_process.fork()        # a new process, driven from this one
+    # write(2) runs in the child, on a buffer allocated in the child's memory
+    await child.stdout.write(await child.ptr(b"Hello from the child!\n"))
+    echo = await child.environ.which("echo")  # looked up on the child's PATH
+    await (await child.exec(echo.args("...now it is echo"))).check()  # execve(2), then wait
+
+trio.run(main)
+```
+
+The same kind of object can stand for a process on another machine. Below, the
+Python code runs here, while the process, its `fork` and its `execve` run on
+`worker`:
+
+```python
+import trio
+from rsyscall import local_process
+from rsyscall.tasks.ssh import make_ssh_host
+
+async def main():
+    host = await make_ssh_host(local_process, lambda ssh: ssh.args("worker"))
+    _, worker = await host.ssh(local_process)      # a process on worker, driven from here
+    child = await worker.fork()                     # the fork happens on worker
+    uname = await child.environ.which("uname")      # found on worker's PATH
+    await (await child.exec(uname.args("-n"))).check()  # prints worker's hostname
+
+trio.run(main)
+```
+
+`worker` is any x86_64 Linux machine you can reach with `ssh worker` that has a
+POSIX shell and GNU coreutils. Nothing has to be installed there: a small static
+bootstrap helper travels over the same ssh connection. The function passed to
+`make_ssh_host` extends the `ssh` command line, so ssh options such as a jump
+host or connection sharing can go there. `scripts/hello.py` is the first example
+with more output; `make hello` and the CI run it.
+
+## Relation to upstream
+
+Upstream has been dormant since 2022-07-25 and its PyPI package no longer
+installs. rsyscall-ng keeps the upstream Python API (imported with its full git
+history under `python/`) and brings it to current Python (>= 3.12) and trio.
+The small native part (a syscall server, a `clone` trampoline, a futex helper
+and three bootstrap helpers, C + x86_64 assembly upstream) has been
+reimplemented in Rust under `native/`, clean-room from the specification in
+`docs/spec/`. The unmodified upstream C is still built locally, only as a
+*differential test oracle* (`BACKEND=c`).
+
+## Status
+
+- [x] upstream `python/` imported with history (commit `2a36209`, 2022-07-25)
+- [x] compatibility patches for Python 3.12+ / current trio and outcome
+- [x] test harness migrated off `trio.MultiError`
+- [x] baseline of the upstream test-suite recorded against the original C
+      backend (`tests/baseline-c.txt`)
+- [x] clean-room v0 specification of the native side (`docs/spec/`)
+- [x] Rust native side (`native/`): `librsyscall.so` and the three helper
+      executables, byte-compatible with the C oracle (`make baseline-diff` is
+      empty; `make probe-diff` differs only where the specification leaves
+      behaviour unspecified)
+- [x] PEP 517 packaging: `pip install .` and `make wheel` build an abi3 wheel
+      that bundles the Rust native side (`rsyscall/_native`); `make wheel-test`
+      checks the installed wheel against the recorded baseline on CPython 3.12,
+      3.13 and 3.14, and `make sdist-test` does the same for a wheel built from
+      the sdist outside the repository
+- [x] bootstrap helpers decoupled from Nix: `rsyscall.tasks.{stub,stdin_bootstrap,ssh}`
+      take them from `rsyscall._native` and OpenSSH from `PATH`; `test_stub`,
+      `test_stdinboot`, `test_persistent` and `test_ssh` are in the baseline, so the
+      differential test covers the helper executables
+- [x] continuous integration on GitHub-hosted Ubuntu 24.04 runners: crate
+      tests, the differential C-vs-Rust baseline recorded on the runner, and the
+      wheel and the sdist tested on CPython 3.12 to 3.14
+- [ ] aarch64 (later phase)
+
+## Layout
+
+| Path                       | What                                                        |
+|----------------------------|-------------------------------------------------------------|
+| `python/`                  | upstream Python package tree (`rsyscall`, `dneio`, `arepl`, `wish`, `rsysapps`) |
+| `pyproject.toml`, `setup.py`, `MANIFEST.in` | PEP 517 packaging of `python/` (setuptools + cffi); `setup.py` builds `native/` with cargo and bundles its artefacts |
+| `python/rsyscall/_native/` | `rsyscall._native`: where the bundled `librsyscall.so` and helper executables live, and how to find them |
+| `scripts/`                 | oracle build, venv setup, baseline runner and comparer, smoke test, wheel test, spec checks, black-box probes, CI runner setup |
+| `.github/workflows/ci.yml` | the CI workflow, described under "Continuous integration" |
+| `tests/baseline-c.txt`     | per-test status of the suite against the C backend          |
+| `docs/spec/`               | clean-room v0 specification of the native side (wire protocol, native ABI, bootstrap handshakes, generated layouts and vectors) |
+| `native/`                  | clean-room Rust reimplementation of the native side (`core/` logic and tests, `rsyscall/` cdylib and helper executables); see `native/README.md` |
+| `native/prefix/` (gitignored) | the Rust native side installed by `make native` with the oracle's layout |
+| `tests/baseline-rust.txt`  | the same suite recorded against the Rust backend; identical to the C one |
+| `reference/` (gitignored)  | pinned upstream clone and the locally built C oracle        |
+| `.venv/`, `.venv-rust/` (gitignored) | the virtualenv of each backend, created by `make venv` |
+| `dist/`, `.venv-wheel/` (gitignored) | wheels and sdists from `make wheel`; the throwaway venv of `make wheel-test` |
+
+## Quick start
+
+Requirements: Linux x86_64, git, [uv](https://docs.astral.sh/uv/), a C compiler
+(for the cffi extension), Rust 1.88 or newer with cargo (`native/` uses naked functions)
+and, for the C oracle only, autotools, libtool, pkg-config and the Linux kernel
+headers.
+
+```sh
+make oracle     # clone upstream at the pinned commit and build c/ into reference/prefix
+make venv       # .venv with an editable install of python/ built against the oracle
+make hello      # clone a child process, write to its stdout, exec `echo`
+make baseline   # run the suite and (re)generate tests/baseline-c.txt
+```
+
+The Rust native side is selected with `BACKEND=rust`, which switches the prefix
+(`native/prefix`), the virtualenv (`.venv-rust`) and the recorded baseline:
+
+```sh
+make native                                       # cargo build, install into native/prefix, ELF checks
+make venv BACKEND=rust && make hello BACKEND=rust
+make baseline BACKEND=rust && make baseline-diff  # tests/baseline-rust.txt vs tests/baseline-c.txt
+make probe-diff                                   # black-box probes of the helper executables, both backends
+make native-test                                  # the crate's own tests (cargo test -p rsyscall-core)
+python3 scripts/header-check.py                   # rsyscall.h against the spec's layout tables
+```
+
+In this development flow `scripts/env.sh` exports `RSYSCALL_NATIVE=prefix`: the
+cffi extension `rsyscall._raw` is linked through pkg-config against the selected
+backend's prefix, with its rpath baked in by `make venv` (plus `LD_LIBRARY_PATH`
+as a belt-and-braces measure, since both venvs share the in-tree extension), and
+`RSYSCALL_LIBEXEC_DIR` points `rsyscall._native` at that prefix's helper
+executables. Nothing from `native/` is copied into `python/` in this mode.
+
+## Installing and wheels
+
+Outside the development flow the default mode, `bundled`, applies: `setup.py`
+runs `cargo build --release` in `native/`, copies `librsyscall.so` and the three
+helper executables into `rsyscall/_native/` and links the extension with an
+`$ORIGIN/_native` rpath, so the installed package is self-contained and needs
+neither Nix nor a prefix:
+
+```sh
+uv pip install .        # or pip install .: builds native/ with cargo, nothing else to set up
+make wheel              # dist/rsyscall_ng-*.whl, abi3 (CPython 3.12+), from a clean dist/
+make wheel-manylinux    # check it (auditwheel, abi3audit) and retag it as manylinux_2_17 (uvx)
+make wheel-test         # install the newest wheel into .venv-wheel and exercise it from /tmp:
+                        # import, bundled helpers, smoke test, test-suite vs tests/baseline-rust.txt
+RSYSCALL_WHEEL_PYTHON=3.12 make wheel-test   # the same on another interpreter (3.12, 3.13, 3.14)
+make sdist              # source distribution: python/ plus the native/ sources and docs/spec/
+make sdist-test         # unpack it outside the repository, build a wheel as pip would
+                        # (isolated PEP 517 build, cargo included) and test it like wheel-test
+```
+
+The wheel is tagged `cp312-abi3`: the cffi extension uses only the stable ABI
+(`abi3audit` finds no violation), so one wheel serves every CPython from 3.12 on.
+Both the wheel and a wheel built from the sdist give the recorded baseline's
+per-test results on 3.12, 3.13 and 3.14. Building from the sdist needs, on the
+installing machine, cargo with Rust 1.88 or newer (the first release with naked
+functions; 1.87 fails), a C compiler and the Python headers (`python3-dev` on
+Debian and Ubuntu).
+
+`rsyscall._native.helper(name)` returns the path of a bundled helper executable
+(or of the one under `RSYSCALL_LIBEXEC_DIR`, when set) and `library_path()` the
+bundled `librsyscall.so`, or `None` when the extension was linked against a
+prefix. Wheels bundle only artefacts built from `native/`; the upstream C is
+never packaged.
+
+## Running tests
+
+```sh
+make test PYTEST_ARGS='-k clone'          # any pytest arguments
+RSYSCALL_TEST_OPTIONAL=1 make test        # collect even the modules whose environment is missing
+```
+
+Modules are ignored at collection time only when what they need is missing on
+this machine: a Nix store (`test_nix.py`); `ssh`, `sshd` and `ssh-keygen` on
+`PATH` or in `/usr/sbin`, `/usr/local/sbin`, `/sbin` (`test_ssh.py`,
+`test_persistent.py`); `/dev/fuse` (`test_fuse.py`); `pyroute2` and
+`/dev/net/tun` (`test_net.py`). `RSYSCALL_TEST_OPTIONAL=1` collects them
+regardless, and the fourth header line of a baseline records what was ignored
+and why. The baseline records the status of every collected test; it is a
+description of reality, not a promise that everything passes. `make baseline`
+runs every test in its own interpreter: the tests share the module-level
+`rsyscall.local_process`, whose state does not survive a test being killed by
+the timeout, so in a single process one hanging test would poison the rest.
+Tests also leave processes behind (they share the interpreter's memory and hold
+both ends of their syscall sockets), so `make baseline` and `make wheel-test`
+run each pytest in a session of its own and kill its whole process group
+afterwards (`scripts/pytest_session.py`).
+
+## Continuous integration
+
+`.github/workflows/ci.yml` runs on pushes to `main`, on pull requests, weekly
+and on demand, on GitHub-hosted Ubuntu 24.04 runners. `scripts/ci-setup.sh`
+installs autotools and the OpenSSH server and lifts Ubuntu's AppArmor
+restriction on unprivileged user namespaces, which the test-suite creates.
+
+- **differential** runs the crate tests, builds the Rust native side with its
+  ELF checks and the C oracle, runs the specification checks and the smoke
+  tests, and records both baselines on the runner. It fails unless the two are
+  identical. Differences from the committed baselines are only warnings,
+  because a few tests depend on the machine; the recorded baselines and the
+  per-test logs are uploaded as artifacts.
+- **dist** builds the manylinux abi3 wheel, checked by auditwheel and
+  abi3audit, and the sdist, and uploads them as the `dist` artifact.
+- **test-dist** installs the wheel on CPython 3.12, 3.13 and 3.14, and a wheel
+  built from the sdist, and compares each one's per-test results with the Rust
+  baseline recorded by the differential job.
+
+Actions are pinned to commit SHAs, with the release named in a comment.
+
+## Licensing
+
+New code, including all of `native/`, is MIT, Copyright (c) 2026 Carlos Andrés
+Planchón Prestes (see `LICENSE`). `python/` is MIT per upstream package
+metadata, Copyright 2018-2022 Spencer Baugh and contributors. Upstream `c/` is
+intentionally not part of this repository; `native/` was written from
+`docs/spec/` alone, without access to it. See `NOTICE` for details.