archvillainette
7cc53aeb68
build-binaries / build-binaries (push) Successful in 2m40s
Closes #86. Closes #85. These land together on purpose. Fixing the encoder alone changes nothing for the blobs already in the zone, because `emit` skips whatever is already present. ## #86 — the framing fix `klauspost/compress` omits the zstd `Frame_Content_Size` field for inputs under 256 bytes, which the format permits. Reference libzstd never does, so the NWN client — which sizes its output buffer from `ZSTD_getFrameContentSize` and has therefore never met a frame without one — rejected roughly 6% of our blobs outright. Any single one stops a sync dead, so no client could complete a sync of the live manifest. No encoder option changes this, so `compressBlob` re-headers the affected frames into the shape libzstd itself emits: `Single_Segment_flag` set, `Window_Descriptor` dropped, and the freed byte spent on a one-byte `Frame_Content_Size`. Same length in, same length out, and the same descriptor byte (`0x24`) the issue recorded from libzstd. `compressBlob` then asserts its own output. An encoder upgrade that finds another way to omit the field would otherwise reproduce #86 in silence, and a blob is skipped by every later emit once written. `emitter_version` goes to `2`, so `assemble` refuses to merge an index written by the encoder that omitted the field. **Proved against the reference decoder, not just a round trip.** A real emitted 175-byte blob: ``` Frames Skips Compressed Uncompressed Ratio Check Filename 1 0 48 B 175 B 3.646 XXH64 frame.zst c59d6620d4ffd4bf3fe73df43b19b7afcfe8fea4 - <- zstd -dc | sha1sum c59d6620d4ffd4bf3fe73df43b19b7afcfe8fea4 <- the blob's own name ``` Before the fix that `Uncompressed` column was blank. ## #85 — `nwsync verify` `crucible nwsync verify <manifest-sha1>` reads a manifest and its blobs back through the **public pull zone**, with no credential, because what matters is the bytes a client is served, edge behaviour included. Every distinct blob is decompressed and hashed; failures are reported per blob as missing / malformed framing / size mismatch / hash mismatch, and the exit code is 1. - `--sample N` makes a routine check cheap against a manifest that is ~69,000 blobs and 15 GB; the default is a full sweep. - `--base URL` / `NWSYNC_PULL_BASE` overrides the public host. - The manifest is checked against its own sha1 before a single blob is fetched. - `emit --verify` applies the same check where `emit` would otherwise trust presence, and replaces a stored blob that is not what its name claims. This is what makes the #86 blobs repairable. ## Why the existing checks missed this Both new checks assert the **frame property**, not just a round trip. The conformance suite (#59) compares decompressed bytes, so a frame that decodes correctly passes regardless of its header; and the earlier zone audit decompressed 68 blobs with the `zstd` CLI, a *more* capable decoder than the client's, which certified exactly the blobs the client rejects. ## Checks `make check` and `make smoke` green. Second commit is the fixes from a two-axis review of the first. ## Not in this PR Three follow-ups, filed separately: the backfill has not been run, replacing a blob does not purge the pull-zone edge cache, and #85's runbook line belongs to `sow-platform`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: #87 Co-authored-by: vickydotbat <vickydotbat@tutamail.com>
101 lines
4.4 KiB
Markdown
101 lines
4.4 KiB
Markdown
# sow-tools — Crucible
|
|
|
|
Crucible is the Shadows Over Westgate build/conversion/sync toolchain: one Go
|
|
module producing several small binaries plus a `crucible` dispatcher (D11). It is
|
|
the **only** repo that owns builder logic; the artifact repos (`sow-module`,
|
|
`sow-topdata`, `sow-assets-manifest`) invoke Crucible through wrapper scripts and
|
|
never embed a toolkit.
|
|
|
|
```text
|
|
Repos produce artifacts. sow-platform deploys artifacts.
|
|
Crucible is how the artifact repos turn source into artifacts.
|
|
```
|
|
|
|
## Binaries
|
|
|
|
| Binary | Dispatcher form | Owns |
|
|
| ------------------ | ------------------ | ----------------------------------------------- |
|
|
| `crucible` | — | dispatcher: `crucible <builder> [args]` |
|
|
| `crucible-depot` | `crucible depot` | content-addressed depot blob verify/move |
|
|
| `crucible-hak` | `crucible hak` | ERF/HAK pack/unpack + hak manifests |
|
|
| `crucible-module` | `crucible module` | build/extract/validate/compare the `.mod` |
|
|
| `crucible-nwsync` | `crucible nwsync` | NWSync blob emit + manifest assemble + verify |
|
|
| `crucible-topdata` | `crucible topdata` | compile 2da/tlk topdata + packages |
|
|
| `crucible-wiki` | `crucible wiki` | render + deploy mechanical wiki pages |
|
|
|
|
The dispatcher and the standalone shims share one registry
|
|
(`internal/dispatch`); the shims exist so consumer wrapper scripts can resolve a
|
|
single-token command. The full legacy `nwn-tool` command surface and where each
|
|
command lands is mapped in [`docs/command-surface.md`](docs/command-surface.md).
|
|
|
|
## Status (cutover performed)
|
|
|
|
The internal `app`/`pipeline`/`project`/`erf`/`gff`/`topdata`/`changelog`/
|
|
`validator` packages from `gitea/sow-tools` have been migrated into this tree, and
|
|
the `module`, `topdata`, `hak`, and `wiki` builders now **delegate to the migrated
|
|
`nwn-tool` command surface** (mapped in
|
|
[`docs/command-surface.md`](docs/command-surface.md)). `config` and `changelog`
|
|
are global commands on the dispatcher. `depot` has no migrated logic yet, so it
|
|
keeps the fail-closed path: exit `70`, never a faked artifact.
|
|
|
|
See [`docs/migration-from-nwn-tool.md`](docs/migration-from-nwn-tool.md) for what
|
|
was done and what remains (the consumer `--manifest/--source/--out` flag contract
|
|
is the open Phase-6 item).
|
|
|
|
## Quick start (no Nix)
|
|
|
|
Teammates without Nix don't build anything — they run the bootstrap wrapper,
|
|
which downloads the latest released `crucible` for your OS and runs it:
|
|
|
|
```bash
|
|
./crucible # interactive menu (pick a command)
|
|
./crucible module build
|
|
./crucible topdata validate
|
|
```
|
|
|
|
Windows (PowerShell):
|
|
|
|
```powershell
|
|
.\crucible.ps1 module build
|
|
```
|
|
|
|
The binary is cached under `~/.cache/crucible/<version>/` (`%LOCALAPPDATA%\crucible`
|
|
on Windows); `--repo-local` caches inside the repo instead. Private releases:
|
|
set `CRUCIBLE_TOKEN` or write the token to `~/.config/crucible/token`.
|
|
|
|
## Develop
|
|
|
|
Self-contained (D8) — a host with only Nix can run everything:
|
|
|
|
```bash
|
|
nix develop # Go + shellcheck + yamllint + make
|
|
make check # go vet + go test + shellcheck + yamllint
|
|
make build # build every cmd/* into ./bin (gitignored)
|
|
make smoke # build + assert the fail-closed contract
|
|
```
|
|
|
|
Binaries are **never committed** — they are CI artifacts (D19).
|
|
This retires the old habit of checking in `nwn-tool` / `sow-toolkit`.
|
|
|
|
## CI
|
|
|
|
PR-first (D7): checks run once on pull requests; the only publish event is a
|
|
`v*` tag (see `runbooks/ci-trigger-standard.md` in sow-docs,
|
|
https://git.westgate.pw/ShadowsOverWestgate/sow-docs).
|
|
|
|
- `ci.yml` — vet, test, shellcheck, yamllint, binary smoke, and cross-build all
|
|
targets once per pull request.
|
|
- `build-binaries.yml` — on a `v*` tag, cross-build and upload the binaries,
|
|
`SHA256SUMS`, and the wrappers to the Gitea release, then delete the assets
|
|
of every release except the newest two — Gitea keeps them forever otherwise,
|
|
and every binary is reproducible from its tag.
|
|
- `sync-wrappers.yml` — on a `main` push that touches `wrappers/`, auto-PR the
|
|
canonical wrappers to the consumer repos in `wrappers/consumers.txt`.
|
|
Consumer drift checks run after those PRs merge to `main`, not on the PRs
|
|
themselves, to avoid recursive cross-repo checks.
|
|
|
|
## Consumers
|
|
|
|
How the artifact repos resolve a Crucible binary is
|
|
documented in [`docs/consumer-contract.md`](docs/consumer-contract.md).
|