sow-tools/docs/consumer-contract.md

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:

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.