diff --git a/docs/consumer-contract.md b/docs/consumer-contract.md index 3ae0316..491213d 100644 --- a/docs/consumer-contract.md +++ b/docs/consumer-contract.md @@ -22,19 +22,37 @@ If none resolve, the wrapper exits non-zero with a Phase 5 message. The wrappers prefer the single-token `crucible-` shim so `"$builder" args` quoting stays correct. -## In CI (preferred) +## Parity contract — wrappers are not authoritative for build inputs -**OPERATOR NOTE: Stop. Do not do it this way.** -**Use the pinned `prod.yml` version. That's what it's there for.** +A consumer build wrapper may only: -~~Run the consumer job inside the pinned image and the binaries are on `PATH`:~~ +1. **validate** — a pre-build gate that does not change output; +2. **publish** — a post-build step on a separate artifact; +3. **resolve the crucible binary** — the bootstrap above. -```yaml -container: - image: registry.westgate.pw/deployment/crucible: # pinned, immutable -``` +A wrapper MUST NOT fetch, resolve, generate, or stage any input Crucible reads to +produce the artifact. If Crucible needs an input, Crucible acquires it. This makes +the "no local-machine assumptions" + "same inputs → identical output" rules +explicit: local `crucible ` and CI `crucible ` against the same +committed config must produce identical bytes, with no CI-only pre-steps. -~~No host install, no `$HOME` layout, no developer machine assumptions.~~ +Builders read every input from the project tree. No NWN install is required. A +builder that one day needs NWN game data auto-detects the install (the NWN home +and Steam path are reliably discoverable), with an optional explicit override for +non-standard layouts — never a required hand-set env. + +## In CI + +Builds run the Crucible **binary** — from the `crucible.sh` / `crucible.ps1` +bootstrap (anonymous download) or, for Nix users, from the flake devshell pinned +by `flake.lock`. CI runs the _same_ `crucible ` as local dev, inside the +nix devshell (binary-cache fast). No build container, no token, no CI-only +pre-steps. + +The `registry.westgate.pw/deployment/crucible:` image is **deployment-only**: +`prod.yml` pins it so tools travel with the runtime host (`nwn.enable`), a +disabled placeholder until the NWN stack lands. It is **not** a build tool and no +build/CI job consumes it. ## Determinism