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

**OPERATOR NOTE: Stop. Do not do it this way.**
**Use the pinned `prod.yml` version. That's what it's there for.**

~~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.~~

## Determinism

Same inputs → identical output bytes. Consumers may checksum artifacts across
runs; non-determinism is a builder bug.