archvillainetteandClaude Fable 5
fab911d97a
Nothing consumes registry.westgate.pw/deployment/crucible: prod.yml no longer reserves a slot for it and no runtime or recovery path pulls it. Binaries, wrappers, and the Nix input are the supported ways to run Crucible. Delete the image workflows (build/publish/test), the Dockerfile, and the make image target; update docs to match. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
61 lines
2.8 KiB
Markdown
61 lines
2.8 KiB
Markdown
# Crucible consumer contract
|
|
|
|
How the artifact repos (`sow-module`, `sow-topdata`, `sow-assets-manifest`)
|
|
locate and invoke a Crucible builder. The goal: **no local-machine assumptions**
|
|
(Phase 5 exit criterion). A consumer either finds a Crucible binary or fails
|
|
closed — it never fakes an artifact.
|
|
|
|
## Resolution order (single-token command)
|
|
|
|
Each consumer wrapper resolves its builder to one executable token, in order:
|
|
|
|
1. **Explicit override** — `$SOW_MODULE_BUILD` / `$SOW_TOPDATA_BUILD` /
|
|
`$CRUCIBLE` (a path or name), if set and executable. Back-compat with the
|
|
pre-Crucible skeletons.
|
|
2. **Standalone Crucible binary** — `crucible-module` / `crucible-topdata` /
|
|
`crucible-hak` / `crucible-depot` on `PATH`.
|
|
3. **Legacy name** — `sow-module-build` / `sow-topdata-build` on `PATH`
|
|
(pre-D11; kept so nothing breaks during cutover).
|
|
|
|
If none resolve, the wrapper exits non-zero with a Phase 5 message. The
|
|
`crucible` dispatcher (`crucible module …`) is for humans and CI introspection;
|
|
wrappers prefer the single-token `crucible-<name>` shim so `"$builder" args`
|
|
quoting stays correct.
|
|
|
|
## Parity contract — wrappers are not authoritative for build inputs
|
|
|
|
A consumer build wrapper may only:
|
|
|
|
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.
|
|
|
|
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 <build>` and CI `crucible <build>` against the same
|
|
committed config must produce identical bytes, with no CI-only pre-steps.
|
|
|
|
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 <build>` 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:<sha>` image is **retired**
|
|
(2026-07-17): nothing consumed it, `prod.yml` no longer reserves a slot for
|
|
it, and CI no longer builds or publishes it. Binaries, wrappers, and the Nix
|
|
input are the only supported ways to run Crucible.
|
|
|
|
## Determinism
|
|
|
|
Same inputs → identical output bytes. Consumers may checksum artifacts across
|
|
runs; non-determinism is a builder bug.
|