Master implementation checklist: Tiny Core substrate → Flow Linux layer → eBPF

[godofecht]

This is the canonical implementation checklist for flow-kernel after moving away from a bespoke kernel and onto Tiny Core CorePure64 + Linux.

The goal is to keep the substrate tiny, let Linux own commodity kernel machinery, and concentrate Flow work on kernel-facing systems code and a first-class eBPF toolchain.

Phase 0 — land and validate the Tiny Core migration

• Review and merge codex/tiny-core-base
• Verify tinycore/fetch.sh against the pinned CorePure64 release
• Verify tinycore/run.sh boots successfully under QEMU
• Capture and assert the serial boot log in CI
• Confirm the Tiny Core kernel exposes required eBPF/BTF features
• Record the exact Tiny Core version, kernel version and checksums used by CI
• Add cache handling for downloaded Tiny Core artifacts
• Make CI fail clearly if upstream Tiny Core artifacts move or disappear
• Enable the GitHub Pages workflow and verify the project site deploys
• Add CI and Pages badges to the README

Phase 1 — define the Flow/Linux systems boundary

• Document the supported Linux ABI surface for Flow
• Add Linux scalar/integer/pointer ABI type mappings
• Add bindings for common syscalls needed by tiny services
• Define a stable Flow FFI pattern for libc-free Linux programs
• Add examples for write, exit, mmap, clock_gettime and file descriptors
• Support static/minimal Flow binaries suitable for CorePure64
• Add a tiny Flow hello-world service that runs under CorePure64
• Add a Flow process smoke test to QEMU CI
• Establish rules for code that belongs in flow-kernel vs flooooooooooow/flow

Phase 1.5 — deterministic Linux system-health sequence

• Define a machine-readable ordered boot-health contract
• Add fatal kernel-log signature detection
• Run a diagnostic init as PID 1 in QEMU
• Verify stage ordering from captured serial output
• Produce a machine-readable JSON health report
• Verify procfs/sysfs/device nodes and writable userspace; detect and record devtmpfs support separately
• Verify CPU and memory accounting
• Verify clock/timer monotonicity
• Verify entropy/RNG availability
• Verify process creation and exit status
• Verify signal delivery
• Verify pipe/IPC operation
• Verify filesystem create/read/write/rename/link operations
• Verify block-device discovery
• Verify loopback/network-stack availability
• Probe DNS/resolver health without making external-network health a boot prerequisite
• Verify namespace exposure
• Verify cgroup capability and mountability
• Verify BPF kernel capability evidence at runtime
• Run the libc-free Flow executable within the diagnostic sequence
• Record per-stage timing and last-known-good stage
• Distinguish required failures from advisory/degraded checks
• Archive the full serial log, health report, kernel manifest and diagnostics evidence in CI
• Add regression comparison against a known-good health-report baseline
• Add clean reboot and poweroff diagnostics

Phase 2 — introduce a real Flow eBPF compilation target

• Define --target bpfel / equivalent compiler target contract in Flow
• Decide the canonical lowering path: Flow → MLIR/LLVM → eBPF
• Add eBPF-specific target data layout and integer/pointer rules
• Reject unsupported language features at compile time
• Enforce bounded loops or verifier-safe lowering
• Enforce verifier-safe stack usage
• Enforce verifier-safe pointer provenance
• Prevent unsupported dynamic allocation
• Prevent exceptions/unwinding/runtime dependencies
• Emit standalone eBPF ELF object files
• Add an object inspection test using llvm-objdump / llvm-readelf
• Add a minimal verifier-load test in CI

Phase 3 — eBPF program model and helpers

• Add a Flow representation for eBPF program sections
• Support SEC("...")-equivalent section assignment from Flow
• Add helper function declarations with type-safe signatures
• Add map declarations as first-class Flow constructs or typed bindings
• Support array maps
• Support hash maps
• Support per-CPU maps
• Support ring buffers
• Support perf event buffers if still useful
• Add map lookup/update/delete wrappers
• Add verifier-safe nullable pointer handling
• Add compile-time restrictions for helper availability by program type

Phase 4 — BTF and CO-RE

• Emit or preserve BTF metadata where required
• Add BTF type bindings for kernel structures
• Add a vmlinux.h-style generation/import path for Flow
• Support field access with CO-RE relocations
• Support type existence/field existence relocations where practical
• Add CI coverage across at least two Linux kernel versions
• Add a compatibility test proving one Flow eBPF object can load across those kernels

Phase 5 — tracing hooks

• Tracepoint program example
• Raw tracepoint example
• kprobe example
• kretprobe example
• fentry example
• fexit example
• uprobes for user-space Flow/native programs
• Ring-buffer event streaming into a Flow userspace consumer
• Add end-to-end tracing CI smoke test

Phase 6 — networking hooks

• XDP program support
• XDP pass/drop example
• XDP packet parsing helpers with verifier-safe bounds checks
• TC ingress support
• TC egress support
• Socket filter support
• cgroup socket hooks where useful
• Add virtual-network QEMU CI for XDP/TC smoke tests
• Benchmark Flow-generated eBPF against equivalent C/libbpf programs

Phase 7 — loader and userspace control plane

• Decide whether the initial loader uses libbpf, bpftool or a minimal native loader
• Add a minimal loader API usable from Flow
• Load eBPF objects
• Pin/unpin maps and programs
• Attach/detach programs from supported hooks
• Read/write maps from Flow userspace
• Consume ring-buffer events from Flow userspace
• Expose verifier logs cleanly when loading fails
• Add deterministic cleanup for attached programs and pinned objects

Phase 8 — Tiny Core packaging

• Define the minimal CorePure64 extension set needed for development
• Define a smaller runtime-only extension set
• Package Flow kernel-facing tools as Tiny Core .tcz extensions
• Package the Flow eBPF loader/runtime as a .tcz
• Add reproducible extension build scripts
• Add checksums and dependency metadata
• Produce a bootable QEMU image with Flow tooling preloaded
• Add release artifacts for the Tiny Core image/extension bundle

Phase 9 — hardening and performance

• Add verifier-negative tests for invalid Flow eBPF programs
• Add compiler diagnostics that explain verifier constraints before load time
• Fuzz eBPF lowering
• Fuzz map and packet access boundaries
• Add instruction-count reporting
• Add stack-depth reporting
• Add generated-object size reporting
• Benchmark load time
• Benchmark packet throughput for XDP examples
• Benchmark tracing overhead
• Track differences against clang/libbpf baselines
• Ensure no accidental Python/runtime dependency is required in deployed artifacts

Phase 10 — developer experience

• Add flow ebpf build
• Add flow ebpf load
• Add flow ebpf attach
• Add flow ebpf detach
• Add flow ebpf inspect
• Surface verifier logs in normal Flow diagnostics
• Add concise examples for each supported hook class
• Add architecture diagrams to the GitHub Pages site
• Add benchmark tables to the GitHub Pages site
• Add generated API/reference docs for eBPF helpers and maps

Phase 11 — release criteria

• Tiny Core boot is reproducible in CI
• A Flow userspace service runs under CorePure64
• A Flow source file compiles to verifier-accepted eBPF
• Tracepoint example works end to end
• XDP example works end to end
• Maps work end to end
• Ring-buffer events reach a Flow userspace process
• CO-RE/BTF compatibility is demonstrated across kernel versions
• CI covers boot, build, verifier load and at least one live attach path
• Documentation and GitHub Pages reflect the actual supported state
• Publish a first tagged flow-kernel release

Current diagnostic baseline

Known-good QEMU profile: Tiny Core CorePure64 17.1, Linux 6.18.35-tinycore64, x86_64 TCG, 256 MiB. The latest strict run passed the complete required system-health sequence, regression comparison, reboot and poweroff paths. DNS remains an intentional advisory/degraded result in the rdinit diagnostic environment. Runtime BPF capability is proven; upstream BTF/config metadata retrieval remains unresolved and is deliberately tracked separately above.

Guiding constraint

Do not reimplement Linux kernel infrastructure unless there is a Flow-specific research reason to do so. Linux owns boot, VM, scheduling, interrupts, drivers, networking and the eBPF VM/verifier. flow-kernel should own the Flow-facing systems layer, eBPF compilation/runtime integration, tiny userspace services and reproducible Tiny Core packaging.

[godofecht]

Phase 1 implementation tranche is now on codex/tiny-core-base.

Implemented:

• Linux x86_64 ABI contract and exact-width Flow mappings (docs/linux-abi.md)
• raw libc-free syscall bindings for write, exit, mmap, and clock_gettime (linux/x86_64/abi.flow)
• syscall usage examples including fd handling (docs/syscalls.md)
• static -nostdlib Flow service build path (examples/build-hello.sh + examples/start.S)
• minimal Flow hello service (examples/hello.flow)
• CI injection of the static Flow ELF into CorePure64 and QEMU execution as PID 1
• CI checks for no program interpreter and no unresolved symbols
• strict Tiny Core eBPF/BTF config assertions

Current verification run: https://github.com/flooooooooooow/flow-kernel/actions/runs/32033100401

I am deliberately leaving the execution-dependent checklist boxes unticked until that live run proves them.

[godofecht]

The previously unreviewable codex/tiny-core-base branch is now caught up with main and tracked by draft PR #4. That PR is the Phase 0 migration/review surface; keep this master issue open for the remaining eBPF, packaging, hardening, DX and release phases.