Phase 5: scaffold Crucible (sow-tools) — dispatcher + builder shims, container, PR-first CI, fail-closed (D11, D19).

2026-06-11 20:36:13 +02:00
commit 0d6eb2aeaa
28 changed files with 987 additions and 0 deletions
@@ -0,0 +1,50 @@
+# 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/sow/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.