namei_ext

namei_ext is a research prototype for a sched_ext-style BPF extension point in the Linux VFS path-resolution layer.

The project is not a standalone filesystem. The intended design keeps VFS, dcache, inode, permission, and lower-filesystem semantics in the kernel, while BPF programs provide programmable path-resolution decisions for lookup and directory enumeration.

See docs/idea-story.md for the research story and docs/design.md for the mechanism design. The Linux kernel fork used for prototyping is tracked as the kernel submodule.

Repository Layout

The repository separates mechanism code, industrial experiments, performance benchmarks, and historical evidence:

kernel/                 modified Linux kernel submodule
bpf/policies/           eBPF name-resolution policies
runner/                 shared C harness for BPF, cgroup, and target lifecycle
experiments/            focused industrial case-study runners
tests/                  ABI, policy-load, semantic, and functional regressions
bench/                  VFS performance workloads
mk/experiments/         Make-owned KVM suites for individual case studies
mk/benchmarks/          Make-owned standard performance matrices
mk/suites.mk             suite registry and evidence-level aggregates
mk/kvm.mk                named KVM capture entrypoint and guest evidence
mk/results.mk           shared run lifecycle and raw-artifact validation
mk/multi_boot.mk        shared multi-boot mechanics and host provenance
analysis/               derived statistics and figures from raw observations
configs/publication/    explicit index of published formal result bundles
workloads/legacy/       evidence using the superseded workload numbering
results/                raw observations, logs, and run metadata

experiments/legacy_oracle/ retains the historical multi-workload ccache runner for reproducibility. New experiments must use a focused runner under experiments/ and shared mechanism helpers from runner/.

Make Entrypoints

Known validation and experiment entrypoints are owned by Make:

make phase1
make experiments
make current-experiment-gates
make formal-case-studies
make formal-performance
make kvm-agent-workspace-matrix
make experiment-agent-workspace-source-task-rq1
make experiment-agent-workspace-rq2
make experiment-agent-workspace-rq3
make experiment-application-file-sharing-rq1
make experiment-build-action-sandboxing-rq1
make experiment-toolchain-environment
make kvm-application-file-sharing-preflight
make kvm-build-action-sandboxing-preflight
make kvm-service-config-rotation-preflight
make experiment-service-config-rotation
make kvm-checkpoint-restore-preflight
make kvm-bench
make kvm-fxmark-rq2-preflight

make phase1 builds and checks the ABI, BPF programs, userspace tests, touched kernel objects, KVM boot, policy load/attach, and functional behavior. Host-only execution does not count as Phase 1 validation.

make experiments and make current-experiment-gates run development gates. Paper-facing collection uses make formal-case-studies and make formal-performance. Formal RQ1 case studies currently cover the Agent workspace lifecycle plus a released Click source task, application file sharing, Bazel action views, and toolchain selection. Formal RQ2 and RQ3 case studies include the matched Agent workspace namei_ext/FUSE lifecycle and namei_ext/Wrapfs-derived ownership matrices. Service Configuration Rotation remains registered as a blocked suite so its failed dependency preflights stay reproducible, but it is excluded from current and formal aggregates. The historical Redis/nginx ccache matrix remains reproducible through make legacy-build-cache; it is not a current-suite dependency and must not define the structure of new experiments.

Checkpoint/Restore and Migration currently has pinned DMTCP source and a focused implementation under experiments/checkpoint_restore/. The disclosed, one-line DMTCP restart-environment fix and source-native A-to-B pathvirt baseline have passed their host dependency preflight. The kvm-checkpoint-restore-preflight entrypoint now runs patched DMTCP PathTranslator, namei_ext, and the withdrawn fail-closed control in one modified-kernel boot. Two failed KVM dependency attempts are preserved with their exact diagnostics; the entrypoint has not yet completed successfully or authorized a formal matrix.

Canonical KVM case-study result roots contain run.json, observations.jsonl, command.txt, source inputs, main-repository and kernel commits and status, guest and launcher stdout/stderr, kernel identity and configuration, and dmesg. Formal targets reject a dirty main or kernel tree. Result roots are immutable by RUN_ID; artifact and correctness gates run while the result is running, before it can transition to completed.

Multi-boot benchmark matrices use the same namei_ext.run.v2 lifecycle and place kernel identity, configuration, logs, and raw cell records under one directory per boot. Suite Makefiles own only their workload matrix and correctness gates; mk/kvm.mk owns execution and mk/results.mk owns the minimum result contract. Multi-boot completion also requires exact agreement between the declared and observed matrix and in-guest kernel identity. Condition-level nested observation files are rejected unless the owning suite declares their exact count.

configs/publication/published-formal.json identifies result bundles intended for paper-facing publication. make result-contract requires each indexed bundle to include tracked top-level raw observations, source and kernel identities, input and artifact manifests, source-side oracle files referenced by run.json, and the derived summary. It reruns the indexed analyzer with its frozen seed and checks that the raw observations reproduce the tracked summary after removing machine-specific path fields. Failed or blocked preflight records are not publication bundles and remain outside this contract.