Repository navigation
REQ 106
The lane shall run a declaration's fetch steps with the guest's network link on and without secrets, and its build steps with the declared secrets and with the guest's network link off from before the first build step starts until the instance is powered off.
Stage 1 (VITechnologies/projectbuddy#168) showed that the challenge workload needs the network only to fetch its dependencies, whose archives its lockfile pins by integrity hash, while its build, tests, and package run offline; its dependency install scripts download a native binary outside those pins. A build step with no network cannot fetch unpinned code or send a secret away. The engine cannot tell an install script from any other step without naming a package manager (REQ-001, REQ-090), so it fixes the boundary between a networked fetch phase without secrets and an offline build phase with secrets, and records each phase's argument vectors (REQ-092); the consumer's own gate decides, for example, whether a fetch step must disable install scripts. The hypervisor enforces the split on the lane's only network adapter (option N2, chosen on VITechnologies/projectbuddy#182; design in VITechnologies/projectbuddy#166), so the guest does not enforce it and the host gains no new network. The link does not come back after the build starts, because any unprivileged guest process can write a VirtualBox guest property (VITechnologies/projectbuddy#182), so no signal written in the guest can safely decide when the network returns. Residual risk: a fetch step can change files that a build step later runs with secrets, and the raw-value scan of REQ-093 does not detect an encoded secret in an output.
A projectbuddy/lane-workload@2 declaration gives fetch as zero or more steps and build as one or more steps, each step an argument vector, with a positive timeout for each phase, and is validated offline before any VM mutation (REQ-090). The fetch steps run as the workload account in one transient unit, with the link on and no declared secret in their arguments, environment, or standard input, and that unit's control group is empty before the build phase begins. Before the first build step starts, the host has turned the adapter's link off by the instance UUID and observed it off, and the guest has observed carrier loss. The build steps run as the workload account, without sudo, in one transient unit that receives the declared secrets on standard input only. Only after that unit has ended and its control group is empty does a root-owned launcher write the declared outputs and the build's exit status to a disk attached to the instance for that run, and power the guest off. The host reads the outputs from that disk only after observing the instance poweroff, without starting it again, and never turns the link on again. The evidence record lists each phase's argument vectors, the link state the host observed for it, and the secret names it received. Rejected: a declaration with no build step, a step given as one shell string, or a phase without a positive timeout is refused before any VM mutation; if the host cannot observe the link off, no build step starts and the run is failed; a build step that tries to reach a host listener that the fetch phase could reach gets no connection; a process left by a fetch step is gone before the first build step starts; a guest property written by a build step does not turn the link on; an instance that is not poweroff within the build timeout plus the host grace period is powered off by the host and recorded timeout, with no output retained; an output disk that holds anything other than the declared outputs and the exit status fails the run.
Planned, TEST-108; no lane executor exists yet.
Software-Requirements-Specification
High
Planned lane workload contract cases and lane network-split cases
scripts/lane/declaration.py (offline validation of lane-workload@2: the fetch and build phases, each step's argument vector, each phase's timeout, and maxOutputBytes) and scripts/lane/plan.py (the fetch and build steps, the link off from build on and never turned on again, the output disk at SATA port 1, and each guest unit's declared timeout), scripts/lane/output_disk.py (the output disk's format, and the root launcher that writes the build result and the declared outputs to it and powers the guest off), scripts/lane/supervisor.py (the guest supervisor: the fetch and build phases as the workload account in transient units, the secrets on the build unit's standard input only, each unit's control group emptied after it ends, the wait for carrier loss before the build unit starts, and the hand-off to the launcher), scripts/lane/placement.py (the host side that places the supervisor, the launcher, the spec, and the secrets file in the guest and runs the supervisor's fetch and start-build modes), and scripts/lane/outputs.py (the host's byte-for-byte check of that disk, streamed with VBoxManage mediumio cat without starting the instance), with docs/vm-provisioning/ubuntu-lane.md; the orchestration that runs the plan's steps in order is not implemented
Planned