docs: update ambient.md to match better what we have

Sponsored-by: author

1 files changed, 13 insertions, 81 deletions

diff --git a/ambient.md b/ambient.md
index afda670..8d20a59 100644
--- a/ambient.md
+++ b/ambient.md
@@ -6,7 +6,8 @@ simple, sane, safe, secure, speedy, and
 supercalifragilisticexpialidocious. There are many existing such
 systems, but we feel none of them are excellent.
 
-For now, it is a command line tool that runs a build locally, in a VM.
+For now, it is a command line tool that runs a build locally, in a VM,
+without network access.
 
 ## Continuous integration concepts
 
@@ -16,7 +17,7 @@ definitions for Ambient. The goal here is being clear and unambiguous
 in the Ambient context, not to define terminology in the wider
 community of software developers.
 
-Note: this is currently aimed at building, testing, and publishing
+Note: Ambient is currently aimed at building, testing, and publishing
 software, but not deploying it. That may change, but it's possible
 that deployment will need its own kind of system rather than forcing a
 CI system to do it badly.
@@ -27,7 +28,7 @@ Ambient, or several may be combined into one. For thinking and
 discussing the system and its software architecture, we pretend that
 they're all separate programs.
 
-* **artifact** -- a file produced by a build step
+* **artifact** -- a file produced by a build
 
 * **artifact store** -- where artifacts are stored after a build step
   is finished
@@ -144,14 +145,14 @@ These are not in any kind of order.
   hardware capacity allows.
 
 * We want it to be easy to provide build workers, without having to
-  worry about the security of the worker hots, or the security of the
+  worry about the security of the worker host, or the security of the
   build artifacts.
 
-* If a job is going to fail for a reason that can be predicted before
-  it even starts, the job should not start. For example, if a build
-  step runs a shell command, the syntax should be checked before the
-  job starts. Obviously this is not possible in every case, but in the
-  common case it is.
+* If a build is going to fail for a reason that can be predicted
+  before it even starts, the job should not start. For example, if a
+  build step runs a shell command, the syntax should be checked before
+  the job starts. Obviously this is not possible in every case, but in
+  the common case it is.
 
 * Build failures should be easy to debug. Exactly what this means is
   unclear at the time of writing, but it should be a goal for all
@@ -160,7 +161,7 @@ These are not in any kind of order.
 * It's easy to host both client and server components.
  
 * It's possible, straightforward, and safe, for workers to require
-  payment to run a job. This needs to be done in a way that is
+  payment to run a build step. This needs to be done in a way that is
   unlikely to anyone being scammed.
 
 * Is integrated into major git hosting platforms (GitHub, GitLab,
@@ -228,9 +229,8 @@ We build and test in a local virtual machine.
 The VM has no network access at all. We provide the VM the project
 source code via a read-only virtual disk. We provide the VM with
 another virtual disk where it can store any artifacts that should
-persist. Both virtual disks will use file system that can be produced
-and read entirely using tools that run outside the operating system
-kernel, to avoid triggering a kernel bug.
+persist. Both virtual disks will contain no file system, but a tar
+archive.
 
 We provide the VM with a pre-determined amount of virtual disk. The
 project won't be able to use more.
@@ -247,71 +247,3 @@ We run the VM with a pre-determined amount of disk, number of CPUs,
 amount of memory. We fail the build if it exceeds a pre-determined
 time limit. We fail the build if the amount of output via the serial
 console exceeds a pre-determined limit.
-
-# MVP for local job runner for Ambient
-
-I think the first implementation step for Ambient will need to be a
-command line tool to run a job locally, but safely and securely.
-Something along the following lines:
-
-* Tool is tentatively called `ambient-run`.
-* It is invoked like this: `ambien-run .` where the argument, `DIR`,
-  is the root of the source tree to be built.
-* At startup, `ambient-run` reads its configuration file, and
-  `DIR/.ambient-ci.yml`, where `DIR` is the command line argument.
-* The configuration specifies the path to the base image for the build
-  VM, in qcow2 format
-* The `.ambient-ci.yml` file specifies fields:
-  - `build`: shell snippet to run to do the build
-  - `test`: shell snippet to run automated tests after the build
-* The tool works like this:
-  - copy the base image to a temporary file
-  - create a workspace disk image where the directory specified on the
-    command line is copied
-  - boot build VM using QEMU, with a serial port, and no networking
-  - via serial port, log in as root, then run the `build` and
-    `test` shell snippets, as if prefixed by `#!/bin/bash\nset -euo pipefail\n`
-  - capture output from the snippets into `ambient-run` stdout and stderr
-  - if either snippet fails, terminate job run and destroy the VM and
-    don't run remaining snippet, if any
-
-The only output is the "build log" captured from the serial port. No
-artifacts are exported for the MVP.
-
-The base image needs to be specially prepared:
-
-* `root` can log in without a password
-* the image has all the build tools and dependencies needed
-  pre-installed
-
-The workspace disk:
-
-* ISO disk image (so that it can be created with genisoimage, without
-  root privileges)
-* contains tar archive of the directory given on the command line
-* tar archive is extracted to `/workspace` before the build starts
-* all files owned by `root:root` and with the same mode bits as in the
-  source tree
-  - `mkdir -p /workspace`
-  - `tar -xf /mnt/src.tar.xz -C /workspace`
-  - `chdown -R 0:0 /workspace`
-
-Control of build VM via serial console:
-
-- use expect(1) to log in and get to prompt
-- at prompt use expect(1) to send commands to mount workspace, and to
-  upload shell script to run job
-
-This should allow me to do a "smoke test" build like this for Subplot,
-assuming the base image has the Rust toolchain installed.
-
-~~~yaml
-build: |
-  RUSTFLAGS="-D warnings" cargo clippy --workspace --all-targets -- -Dclippy::all
-  cargo build --workspace --all-targets
-test: |
-  cargo test --workspace
-~~~
-
-This would not be enough in general, but would be enough as a proof of
-concept and to get the Ambient implementation started.