study-distribute-wg

Metadata

Description

## Objective
Study whether and how the WG Rust binary can be cross-compiled to per-target platform binaries and distributed via npm, so users can install/run WG without a Rust toolchain.

## Research questions
- Cross-compile targets: the set of host triples to ship (macOS arm64/x64, Linux x64/arm64, Windows x64, maybe musl). Tooling: cargo-zigbuild / cross / cargo-dist / GitHub Actions matrix. Static vs dynamic linking (glibc/musl); code-signing + notarization for macOS; Authenticode/Sigstore for Windows.
- npm packaging shape: an npm driver package that detects the host triple and dispatches to an optional-dependencies per-platform package (the common @scope/cli pattern), vs a postinstall binary download, vs a single package bundling all binaries. Pros/cons, offline use, integrity verification (checksums, provenance/SLSA), supply-chain safety.
- Precedent: the pi-worksgood embed model (worksgood-pi/embedded committed bytes) — can the same idea carry a binary, or does npm need real per-platform artifacts?
- Versioning/release: how wg version + compat consts map to npm semver; how `cargo install --path . --locked` relates to an npm-distributed binary; CI to publish on tag.
- Tradeoffs vs current `cargo install`: first-run speed, update cadence, signature/trust, size, and whether the npm binary is the same artifact or a thin wrapper.

## Inputs
- Cargo.toml, .github/workflows/ci.yml (current build/release), rust-toolchain.toml
- worksgood-pi/embedded (byte-embed precedent)
- npm/cross-compile tooling docs (cargo-zigbuild, cross, cargo-dist, per-platform optional-dependencies pattern) — web research

## Deliverable
docs/studies/wg-npm-distribution-design.md

## Validation
- [ ] Design doc committed at docs/studies/wg-npm-distribution-design.md
- [ ] Enumerates target triples + chosen cross-compile toolchain with rationale
- [ ] Picks an npm packaging shape (per-platform optional-deps vs postinstall vs single) with pros/cons and an integrity-verification story
- [ ] Addresses signing/notarization and supply-chain provenance
- [ ] Defines the CI release flow on tag and how wg version/compat maps to npm semver

Depends on

• done .assign-study-distribute-wg

Required by

• done .flip-study-distribute-wg
• done synthesis-roadmap-from

Log

• 2026-07-25T13:24:03.016332579+00:00 Task paused
• 2026-07-25T13:24:24.467598609+00:00 Task published
• 2026-07-25T19:09:30.084363040+00:00 Spawn failed (attempt 1/5): build-heavy admission budget full (1/1). exec_mode=default, executor=pi
• 2026-07-25T20:37:01.755844197+00:00 Spawned by coordinator --executor pi --model zai:glm-5.2 --isolation required-worktree
• 2026-07-25T20:37:15.843290109+00:00 Starting npm distribution design study. Inspecting inputs (Cargo.toml, ci.yml, rust-toolchain.toml, worksgood-pi/embedded).
• 2026-07-25T20:46:16.388744910+00:00 Deliverable committed: docs/studies/wg-npm-distribution-design.md (768 lines, 45KB) — c23fa516, pushed to origin/wg/agent-799/study-distribute-wg
• 2026-07-25T20:46:16.421398651+00:00 Validated: all 5 acceptance criteria met. (1) doc at path ✅ (2) §3 enumerates 5 target triples (ship as-is) + §4 picks native-runner matrix over cargo-zigbuild/cross/cargo-dist with ring/signing/glibc rationale ✅ (3) §5 picks Shape A per-platform optionalDependencies w/ decision matrix + rejects B/C, §6.5 gives 4-layer integrity story ✅ (4) §6 macOS Developer ID+notarytool+stapler, Windows Authenticode/Azure Trusted Signing, 5-layer provenance stack; flags the 2 real gaps ✅ (5) §8.3 CI npm-publish job on tag + §8.1 maps Cargo ver=tag=npm ver, compat consts stay runtime handshakes ✅. All cited file:line facts verified against source.
• 2026-07-25T20:46:35.869067439+00:00 Task pending eval (agent reported done; awaiting `.evaluate-*` to score)
• 2026-07-25T20:48:18.816669187+00:00 Consumed durable verdict verdict-evalp-3494829a29815cf50724c83f-evaluate-b051b232b0b7daba exactly once: score=0.93, outcome=done