From a15e4d8739febbe332026d8e154915eba6710e62 Mon Sep 17 00:00:00 2001 From: ErenAri Date: Thu, 2 Jul 2026 02:42:36 +0300 Subject: [PATCH] docs: consolidate experimental tracks into docs/experimental.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README advertised three "experimental" tracks (virtme-ng lane, Firecracker backend, runtime probe/select/fetch/agent) plus a Web UI section at the same visual weight as the product surface, diluting the story the project actually leads with: CI gate -> command mode -> quirk library -> evidence. - new docs/experimental.md: all four tracks in one place, each with its status framing (controlled proofs, not the focus), make targets, and links to the detailed docs. Runtime decisioning keeps the explicit host-loading-disabled/gated-by-default language. - README: Implemented list drops the three experimental bullets for one pointer; Backend Lanes keeps QEMU + ARM64 and points at the doc; the Web UI / API + Runtime Decisioning sections collapse into a 5-line pointer; doc map updated. Net -61 lines. No capability changes — everything still works and stays documented; it just stops competing with the headline. Co-Authored-By: Claude Opus 4.8 --- README.md | 93 ++++++++------------------------------------ docs/experimental.md | 80 +++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 77 deletions(-) create mode 100644 docs/experimental.md diff --git a/README.md b/README.md index cf1fa5c..68380c2 100644 --- a/README.md +++ b/README.md @@ -276,13 +276,11 @@ Implemented: and unsupported program types. - Multi-artifact suite support for collections of BPF objects/programs. - JSON, Markdown, GitHub Action summary, and static compatibility-site output. -- Experimental `virtme-ng` upstream-kernel lane. -- Experimental Firecracker generated-initramfs backend. -- Experimental runtime probe/select/fetch/agent flow for verified artifact - decisioning. -Keep the runtime track framed as decisioning/proof unless you are running it in -a controlled environment. Host loading stays disabled/gated by default. +Experimental tracks (virtme-ng upstream lane, Firecracker backend, Web UI/API, +runtime decisioning) are consolidated in +[docs/experimental.md](docs/experimental.md) — kept as controlled proofs, not +the project's focus. ## Install @@ -508,27 +506,12 @@ make oss-evidence ## Backend Lanes -QEMU/KVM distro profiles: +QEMU/KVM distro profiles (the default and supported lane): ```bash make acceptance-dev-one ``` -Upstream-mainline smoke through `virtme-ng`: - -```bash -make doctor-virtme -make upstream-kernel-runnable -make acceptance-upstream-kernel -``` - -Firecracker generated-initramfs proof: - -```bash -make firecracker-preflight -make acceptance-firecracker-dev-one -``` - ARM64 smoke: ```bash @@ -539,6 +522,10 @@ make acceptance-arm64-smoke The ARM64 workflow is wired, but real ARM64 VM compatibility proof requires a native ARM64 KVM runner. +The experimental backends — upstream-mainline via `virtme-ng` and the +Firecracker generated-initramfs proof — live in +[docs/experimental.md](docs/experimental.md). + ## GitHub Action This repository includes a composite action that runs `bpfcompat` and appends @@ -583,59 +570,13 @@ Marketplace quick start: 3. Use the action in CI to produce JSON, Markdown, and job-summary evidence. 4. Treat exit code `2` as a compatibility gate failure. -## Web UI / API - -The embedded UI is useful for demos and local inspection: - -```bash -make serve -``` - -Open: - -- `http://127.0.0.1:8080/` -- `http://127.0.0.1:8080/results` - -The API has `/api/v1/...` routes with legacy `/api/...` compatibility. For -route details, see: - -- [`docs/openapi.yaml`](docs/openapi.yaml) -- [`docs/api-web-ui.md`](docs/api-web-ui.md) -- [`docs/env-reference.md`](docs/env-reference.md) - -Public demo mode can allow anonymous validation/read/runtime-select/fetch -without enabling host execution. Runtime execute remains separately gated by -`BPFCOMPAT_API_ENABLE_RUNTIME_EXECUTE` and an approval token. - -## Runtime Decisioning - -> **Status:** experimental, and not the project's current focus. Active -> development centers on the CI compatibility workflow: suites, kernel -> matrices, and reports. This track is kept as a controlled proof and may -> change or be removed. - -The runtime path is experimental and should be treated as a controlled proof: - -```bash -make runtime-selector-proof -make runtime-delivery-proof -``` - -The safer product boundary is: - -1. validate artifact variants in CI/VMs; -2. store signed compatibility metadata; -3. probe a target host; -4. select and fetch the best verified artifact; -5. leave host loading to an explicitly approved local agent path. - -Relevant docs: +## Web UI / API and Runtime Decisioning (experimental) -- [`docs/runtime-selector-simulation.md`](docs/runtime-selector-simulation.md) -- [`docs/production-runtime-agent-alpha.md`](docs/production-runtime-agent-alpha.md) -- [`docs/runtime-execute-policy.md`](docs/runtime-execute-policy.md) -- [`docs/security-model.md`](docs/security-model.md) -- [`docs/threat-model.md`](docs/threat-model.md) +Both tracks are kept as controlled proofs, not the product surface — the +supported product is the **CLI + GitHub Action in CI**. The embedded demo UI +(`make serve`), the HTTP API, and the frozen runtime probe/select/fetch/agent +flow (host loading disabled/gated by default) are documented together in +[docs/experimental.md](docs/experimental.md). ## Documentation Map @@ -648,10 +589,8 @@ User guide — start here: - [`docs/kernel-quirk-library.md`](docs/kernel-quirk-library.md) — curated library of known-tricky vendor kernels (version ≠ feature support) - [`docs/profile-catalog.md`](docs/profile-catalog.md) — kernel/distro profiles and image maintenance - [`docs/image-pipeline.md`](docs/image-pipeline.md) — where images come from, integrity, adding profiles -- [`docs/upstream-kernel-virtme-ng.md`](docs/upstream-kernel-virtme-ng.md) -- [`docs/firecracker-backend.md`](docs/firecracker-backend.md) - [`docs/rhcos-openshift.md`](docs/rhcos-openshift.md) — RHCOS/OpenShift (Ignition boot, operator-supplied image) -- [`docs/api-web-ui.md`](docs/api-web-ui.md) +- [`docs/experimental.md`](docs/experimental.md) — virtme-ng lane, Firecracker backend, Web UI/API, runtime decisioning Reference matrices (real, reproducible artifacts): diff --git a/docs/experimental.md b/docs/experimental.md new file mode 100644 index 0000000..e5b11f1 --- /dev/null +++ b/docs/experimental.md @@ -0,0 +1,80 @@ +# Experimental tracks + +Everything on this page works and has evidence behind it, but it is **not the +project's focus**. Active development centers on the CI compatibility +workflow: `.bpf.o` and command-mode validation, kernel matrices (including the +[quirk library](kernel-quirk-library.md)), suites, and reports. The tracks +below are kept as controlled proofs; interfaces may change or be removed. + +## virtme-ng upstream-kernel lane + +Boots **upstream mainline kernels** (kernel.org builds, not vendor images) +through `virtme-ng` for boundary sweeps — useful to bisect exactly which +upstream release introduced a feature, before checking which vendors backport +it. + +```bash +make doctor-virtme +make upstream-kernel-runnable +make acceptance-upstream-kernel +``` + +Details: [upstream-kernel-virtme-ng.md](upstream-kernel-virtme-ng.md). +Note: command mode supports the default `vm` runner only. + +## Firecracker generated-initramfs backend + +An alternative microVM backend that builds a minimal initramfs instead of +booting a cloud image. Faster per-boot, but it does not run *vendor* kernels — +which is the product's differentiator — so it stays a proof. + +```bash +make firecracker-preflight +make acceptance-firecracker-dev-one +``` + +Details: [firecracker-backend.md](firecracker-backend.md). + +## Web UI / API + +An embedded UI and HTTP API for demos and local inspection of results. The +supported product surface is the **CLI + GitHub Action in CI**; the UI is a +convenience, not a SaaS. + +```bash +make serve # http://127.0.0.1:8080/ and /results +``` + +The API has `/api/v1/...` routes with legacy `/api/...` compatibility. Public +demo mode can allow anonymous validation/read/runtime-select/fetch without +enabling host execution; runtime execute remains separately gated by +`BPFCOMPAT_API_ENABLE_RUNTIME_EXECUTE` and an approval token. + +Details: [api-web-ui.md](api-web-ui.md), [openapi.yaml](openapi.yaml), +[env-reference.md](env-reference.md). + +## Runtime decisioning (probe / select / fetch / agent) + +A frozen proof-of-concept for *using* compatibility evidence at deploy time: +probe a target host, select the best verified artifact variant, fetch it, and +leave host loading to an explicitly approved local agent path. Host loading +stays disabled/gated by default; treat the whole track as decisioning/proof +unless you run it in a controlled environment. + +```bash +make runtime-selector-proof +make runtime-delivery-proof +``` + +The safer product boundary this track demonstrates: + +1. validate artifact variants in CI/VMs; +2. store signed compatibility metadata; +3. probe a target host; +4. select and fetch the best verified artifact; +5. leave host loading to an explicitly approved local agent path. + +Details: [runtime-selector-simulation.md](runtime-selector-simulation.md), +[production-runtime-agent-alpha.md](production-runtime-agent-alpha.md), +[runtime-execute-policy.md](runtime-execute-policy.md), +[security-model.md](security-model.md), [threat-model.md](threat-model.md).