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.

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

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