feat: add deployment foundation and cross-device handoff

2026-09-25 08:49:19 +08:00
parent 8ccb8b7c15
commit e965b0943d
77 changed files with 8018 additions and 0 deletions
@@ -0,0 +1,50 @@
+# Environment lock and draft
+
+`plan-environment` accepts strict JSON `{ "lock": <Lock> }`, collects local
+preflight observations itself, and emits a non-executable draft. It does not
+accept caller-supplied host observations, download anything, run apt, configure
+sources or start services.
+
+Lock fields, all required:
+
+- protocolVersion: 1.
+- repository: exactly `https://download.docker.com/linux/ubuntu`.
+- suite: jammy, noble or resolute; architecture: amd64 or arm64.
+- releaseDigest: `sha256:` plus 64 lowercase hex digits, supplied by the caller.
+- packages: exactly docker-ce, docker-ce-cli, containerd.io,
+  docker-buildx-plugin and docker-compose-plugin, once each.
+- Each package has name, version, filename, digest and size. Version is explicit
+  digit-leading Debian-style syntax (optional numeric epoch), at most 128 bytes;
+  digest uses the above SHA-256 format; size is 1 through 512 MiB.
+- Filename must equal
+  `dists/<suite>/pool/stable/<architecture>/<name>_<version-without-epoch>_<architecture>.deb`.
+  Encoded paths, absolute paths, alternate domains, query strings and traversal
+  are not accepted. docker-ce and docker-ce-cli must use the same version.
+
+This is a deliberately limited Docker lock format, not a complete Debian version
+parser. A Linux host's observed distribution/suite and architecture must match;
+unknown observations remain blockers. On a non-Linux machine a syntactically
+valid lock can be reviewed, but unsupported-platform blockers remain.
+
+## Digests and remaining trust boundary
+
+lockDigest binds Go JSON encoding of the validated Lock in struct/array order.
+observationDigest binds Go JSON encoding of the collected Report. These are
+content hashes, not signatures, stable host IDs, freshness tokens or authorization.
+The local observation is not atomic and changes (including free disk space) can
+change its hash. No writing consumer may treat it as an approved plan.
+
+The draft returns requestedPackages, not a complete APT dependency transaction.
+It never proposes automatic removal or upgrade of existing installations.
+RepositoryAuthenticated and executable are always false. There is no signature
+verification, Release-to-Packages-to-deb digest chain verification, metadata
+freshness policy, artifact download, package dependency resolution, or installation
+executor yet. Matching a URL allowlist and a caller-provided hash proves none of
+those. No actual versions are recommended or locked from live metadata in this batch.
+
+Blockers explicitly retain these gaps along with host/network/runtime checks.
+Potential APT database changes, dependency changes, service starts and network
+rule effects are reported. Exit 0 only means a draft was produced.
+
+Reference for package names and repository layout:
+[Docker Ubuntu installation](https://docs.docker.com/engine/install/ubuntu/).