Skip to content

Phase 1 Milestone B: the container engine (P1-05 to P1-10) - #8

Merged
Axoineo merged 5 commits into
mainfrom
p1/milestone-b-engine
Nov 15, 2026
Merged

Axoineo merged 5 commits into
mainfrom
p1/milestone-b-engine

Conversation

@Axoineo

@Axoineo Axoineo commented Nov 15, 2026

Copy link
Copy Markdown
Owner

What changed

Milestone B of docs/phases/phase-1.md: everything needed to run a phone, below the command line. Five commits.

Task Commit What it adds
P1-05 a63d863 The Engine trait and its types in verone-core, and FakeEngine for tests
P1-06 6be9b0b runtime.rs: typed wrappers around the Docker command line
P1-07 071fccd host.rs: host checks against a replaceable view of the system
P1-08, P1-09, P1-10 3c20281 images.rs, engine.rs, adb.rs: pinned images, the container lifecycle, the adb helper, and integration tests
P1-08, P1-15 935c2ef verone doctor, verone image pull, verone image list

Why

Milestone C (the phone commands) is a thin layer over this engine. Getting boot, stop, restart and adb right, and proving them on real phones, is the core of Phase 1.

Acceptance tests

Run on the reference laptop (Arch Linux, kernel 7.3.4, Docker 29.9.3, Rust 1.99.1).

$ cargo fmt --check                              (exit 0)
$ cargo clippy --all-targets -- -D warnings      Finished
$ RUSTDOCFLAGS="-D warnings" cargo doc --no-deps Finished   (P1-05)
$ cargo test
  verone-cli unit tests        15 passed
  verone-cli binary tests       8 passed
  verone-core                  73 passed; 1 ignored
  verone-engine-container      76 passed

Integration tests on real phones:

$ VERONE_TEST_DOCKER=1 cargo test -p verone-engine-container --test integration
test the_runtime_and_host_are_usable ... ok
test a_phone_boots_restarts_stops_and_keeps_its_data ... ok
test a_gpu_boot_that_times_out_falls_back_to_software_once ... ok
test adb_reaches_the_phone_and_survives_a_restart ... ok
test an_optional_adb_port_is_published_on_the_loopback_address_only ... ok
test result: ok. 5 passed; finished in 198.07s

Measured during that run: first boot in GPU mode 23.7 s; return after an in-Android restart 21.1 s; clean stop 1.0 s with exit code 130; fallback boot in software 13.5 s.

Commands, run for real:

$ verone doctor            9 checks, all ok, exit 0
$ PATH=/nonexistent verone doctor
FAILED   Container runtime: the program 'docker' is not installed
error: 1 check failed; phones cannot run yet            exit 3
$ verone image pull        The Android 14 image is ready.   (no download; already present)
$ verone image list --json   reports the pinned digest and "present": true

How each task's "Done when" is met:

  • P1-05: the fake is driven through create, start, stop and destroy via the trait; docs build with warnings as errors.
  • P1-06: unit tests against a stub script; the integration test reads the real runtime's version.
  • P1-07: pass and fail tests for every row of the plan's table using fake system trees; verone doctor exits 0 here and 3 with no runtime.
  • P1-08: table lookup and unsupported version (exit 4); pull is a no-op when present; list reports the digest.
  • P1-09: boot under 60 s; status transitions; in-Android restart returns; stop ends with exit code 130 well within 20 s; a changed display size recreates the container with data intact; a timed-out GPU boot falls back to software once.
  • P1-10: Android release read through the helper is 14; still works after stop/start and after an in-Android restart without manual reconnection; port 5599 is published on 127.0.0.1 only.

Notes for the reviewer

  • doctor arrived early. It was planned as P1-15, but P1-07's acceptance test needs it. P1-15 has nothing left to do.
  • Commits are not strictly one per task. P1-08, P1-09 and P1-10 share engine.rs, so they are one commit; the commands are a second.
  • Publishing the optional adb port depends on a firewall kernel module (xt_tcpudp). On one run after a reboot Docker could not load it and the port test failed; on the final run it passed. The engine now adds a hint (sudo modprobe xt_tcpudp) to that error. Verone publishes no port by default, so ordinary phones are unaffected.
  • The software fallback applies to auto only. A phone explicitly set to GPU mode fails with guidance instead of silently switching. After a recorded fallback, auto goes straight to software on later starts.
  • erase_data is a method of ContainerEngine, not of the Engine trait. Whether it belongs in the trait is decided in P1-14, which uses it.
  • Integration tests are skipped unless VERONE_TEST_DOCKER=1 is set, so CI runs unit tests only. They boot phones one at a time and keep their data under target/tmp.
  • Rule change in the plan: one pull request per milestone with one commit per task, at the owner's request (in commit a63d863).
  • Crates added, all on the allow-list: serde and serde_json in the engine crate; tempfile as a dev-dependency.

🤖 Generated with Claude Code

Axoineo and others added 5 commits November 15, 2026 12:24
Define the Engine trait in verone-core with the operations every
engine provides: check_host, prepare_image, create, destroy, start,
stop, status, control_endpoint and capabilities, plus the types they
exchange (host checks, phone status, boot report, control endpoint,
capabilities).

Add FakeEngine, an in-memory engine that records calls, simulates
phone states and can be told to fail the next call, so front ends can
be tested without a container runtime.

Change the plan's rule 1 at the owner's request: one branch and pull
request per milestone, with one commit per task.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add typed wrappers around the Docker command line in
verone-engine-container: version, info, image presence, pull, create,
start, update of the restart policy, kill, remove, inspect, exec,
one-off runs and published ports. All calls go through the core
process runner, and JSON output is parsed into the fields Verone uses.

Unit tests run against a stub script standing in for the runtime.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add HostProbe to verone-engine-container. It checks that the runtime
is installed and reachable, that the kernel offers binder, that the
running kernel's modules are installed, that there is disk space where
the runtime stores images and where phone data lives, and that memory
is sufficient. It also reports which graphics mode 'auto' would pick
and whether adb and scrcpy are installed.

The probe's root folder, search path and free-space lookup can be
replaced, so every check is tested against a fake system tree.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add the image table with the Android 14 image pinned by digest, and
the pinned helper image used for file operations on root-owned data.

Add ContainerEngine, which implements the Engine trait on Docker:
- builds the container options from the phone profile and stores them
  in a label, so a changed profile recreates the container while the
  data stays;
- resolves the graphics mode itself: GPU when a usable render node
  exists, otherwise software, never a node driven by the nvidia driver;
- waits for Android to report a finished boot, and in auto mode falls
  back to software once if GPU mode does not come up;
- stops a phone by switching the restart policy off and powering
  Android off from inside, because the runtime's stop only kills it;
- erases phone data through the helper image.

Add an adb helper that verifies the connection before each use and
drops a stale one, and a hint for the case where the runtime cannot
publish the optional adb port.

Integration tests boot real phones when VERONE_TEST_DOCKER=1 is set.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add 'verone doctor', which prints every host check with its fix and
exits with code 3 if any check failed, and 'verone image pull' and
'verone image list'. All three support --json.

The doctor command was planned as P1-15. It is added here because the
acceptance test of P1-07 needs it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@Axoineo
Axoineo merged commit d7c791e into main Nov 15, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant