# 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/).