archvillainetteandClaude Opus 4.8
8344a02d7a
registry.westgate.pw/sow/crucible -> /deployment/crucible across build-image + release workflows, flake.nix image name, Dockerfile, docs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
51 lines
1.8 KiB
Markdown
51 lines
1.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.
|
|
|
|
## In CI (preferred)
|
|
|
|
Run the consumer job inside the pinned image and the binaries are on `PATH`:
|
|
|
|
```yaml
|
|
container:
|
|
image: registry.westgate.pw/deployment/crucible:<sha> # pinned, immutable
|
|
```
|
|
|
|
No host install, no `$HOME` layout, no developer machine assumptions.
|
|
|
|
## `NWN_ROOT` rule
|
|
|
|
Crucible **never guesses `NWN_ROOT` from `$HOME`** (this was a deploy-notes
|
|
pain point). The NWN install/data root is passed explicitly:
|
|
|
|
- env `NWN_ROOT=/path/to/nwn`, or
|
|
- flag `--nwn-root /path/to/nwn`.
|
|
|
|
A builder that needs `NWN_ROOT` and receives neither must fail closed with a
|
|
clear message, not fall back to a home-directory default.
|
|
|
|
## Determinism
|
|
|
|
Same inputs → identical output bytes. Consumers may checksum artifacts across
|
|
runs; non-determinism is a builder bug.
|