flowchart TB
  testing["SMH-PLAN-DFOG846Z"] -->|"test infrastructure"| musl["SMH-PLAN-CMYCUMRB"]

flowchart TB
  b1["1 musl development default"] --> b2["2 Cross-distro runtime proof"]
  b2 --> b3["3 musl benchmark gate"]
  b3 --> b4["4 ARM64 runtime proof"]
  b4 --> b5["5 Archives and checksums"]
  b5 --> b6["6 Unified CI target policy"]

---
id: SMH-PLAN-CMYCUMRB
type: plan
title: "Portable Linux Releases with musl"
spec: SMH-SPEC-SPEC0001
status: draft
depends_on: [SMH-PLAN-DFOG846Z]
---

# Portable Linux Releases with musl

## Intent

One Linux application target per CPU architecture, independent of installed glibc.
Development, tests, benchmarks, and releases use musl; no dev/release libc split.
Implement the specification's Linux portability and versioned-archive requirements.
No distro-specific binaries; no GNU Linux application variant.

## Decisions

- Targets: `x86_64-unknown-linux-musl` and `aarch64-unknown-linux-musl`.
- Fully static native linkage, including musl; reject ELF interpreter and shared-library requirements.
- Cargo owns automation; `xtask` delegates cross-builds to `cargo-zigbuild` and Zig.
- Portable CPU baselines; reject ambient native-CPU flags and isolate wasm guest flags.
- Linux application builds, lint, tests, docs, benchmarks, and release artifacts target musl by default.
- Cargo, rustc, build scripts, proc macros, and `xtask` may use GNU host tooling; plugin guests retain their wasm target.
- GNU and Alpine environments verify the same musl artifact, not different application builds.
- Existing GNU instruction pins remain a temporary migration reference, then leave the active gate after approved musl calibration.
- No speed claim, allocator substitution, or automatic budget re-pin.
- Static linkage removes libc requirements, not kernel, terminal, DNS configuration, TLS trust, or external-tool requirements.
- Bundled-libc security updates require rebuilt artifacts; track Zig/musl versions alongside Rust and dependency provenance.
- Preserve Windows, macOS, and OpenBSD scope; this plan delivers only Linux artifacts.

## Dependencies

Testing Methodology supplies regression-first tests and binary/PTY harnesses.
Release Readiness consumes these verified Linux artifacts; unrelated release requirements remain there.

```mermaid
flowchart TB
  testing["SMH-PLAN-DFOG846Z"] -->|"test infrastructure"| musl["SMH-PLAN-CMYCUMRB"]
```

## Behaviors

1. **Daily x86_64 development runs the musl application.**
   Extend `xtask/src/main.rs` build, dev, quality, and release commands to select musl consistently, with locked builds and existing argument passthrough.
   Use `cargo-zigbuild` and Zig for target linking; provision pinned tools and caches through Cargo automation inside repository build directories.
   Keep host-tool and wasm guest builds separate; ensure tests, docs, and benchmarks cannot silently fall back to GNU application artifacts.
   Inspect ELF architecture, CPU baseline, interpreter, and required libraries; run help/version and the development launcher without glibc.
   Reject leaked host flags, missing tools, unsupported target options, and non-static output with actionable errors.

2. **Same binary works on Alpine and a GNU distro.**
   Extend `smith-cli/tests/e2e_*.rs` drivers to accept an explicit binary path; never accidentally test Cargo's GNU binary.
   Exercise eval, RPC, auth storage, session inspection, replay, file/process tools, and PTY terminal restoration with isolated files and scripted local services.
   Validate DNS and HTTPS trust behavior through `smith-harness` HTTP tests; document glibc/NSS differences rather than promise arbitrary enterprise resolver parity.
   Run target-built `smith-harness/tests/wasm_host.rs` against the echo component, proving Wasmtime JIT and sandbox behavior on musl.
   Touch `smith-harness`, `smith-core`, and `smith-alloc` only for evidenced compatibility defects, regression first.

3. **Benchmarks gate the deployed libc.**
   Update `smith-bench`, `xtask` perf/platform reporting, and `.ci/perf.kdl` to measure musl application and benchmark binaries in the canonical CI environment.
   Compare GNU reference and musl candidate from identical source, Rust toolchain, profile, and inputs; record target, linker, and libc differences explicitly.
   Revalidate floor models and judgments; require reproducible instruction counts before proposing musl pins.
   Present numeric pins and platform identity for human approval before changing `smith-bench/budgets.toml` or switching the active gate.
   Retain the ±2 % instruction band and exact allocation/type-size bounds; other platforms report without gating.
   Retire the GNU application benchmark lane after approved migration, not as a permanent development target.

4. **ARM64 development and release pass the same runtime contract.**
   Reuse target-aware build, ELF checks, quality commands, and binary drivers for ARM64.
   Require native ARM64 runtime evidence on musl and GNU environments before publishing that target.
   Cross-compilation success alone is not runtime proof; unavailable ARM64 execution blocks that release target.

5. **Users receive verified archives and checksums.**
   Package one versioned archive per Linux architecture through `xtask` release automation, using the same target/toolchain policy as development.
   Include expected binary and required embedded assets; generate SHA-256 checksums.
   Extract each archive into an isolated directory and rerun artifact acceptance against its binary.
   Record target, source revision, Rust, Zig, musl, and cargo-zigbuild versions with release evidence.
   Refuse stale artifacts, failed acceptance, and mismatched checksums.

6. **CI enforces one Linux application target policy.**
   Update `.ci/check.kdl`, `.ci/e2e.kdl`, `.ci/nightly.kdl`, and `.ci/report.kdl` to run their application builds and gates against musl; host-tool gates remain host-native.
   Add `.ci/musl.kdl` for cross-distro artifact acceptance, delegating to canonical Cargo commands.
   Separate target/toolchain caches; retain GNU-based runner images only where useful, not GNU application quality lanes.
   Gate release publication on both target proofs, archives, checksums, approved musl instruction pins, and existing quality gates.
   Keep public submission/publication authorization separate from implementation; no infrastructure changes assumed.

Each behavior consumes the previous behavior's verified artifact or reusable acceptance driver.

```mermaid
flowchart TB
  b1["1 musl development default"] --> b2["2 Cross-distro runtime proof"]
  b2 --> b3["3 musl benchmark gate"]
  b3 --> b4["4 ARM64 runtime proof"]
  b4 --> b5["5 Archives and checksums"]
  b5 --> b6["6 Unified CI target policy"]
```

## Boundaries

- `SMH-PLAN-RELS0001` remains unchanged; musl tooling owns Linux linkage, not its proposed mold table.
- Tool provisioning must not modify user tool directories, shell configuration, or system packages without exact-change approval.
- Root Cargo, Cargo config, toolchain, specs, and RULES edits require separate one-shot approval if needed.
- No new minimum glibc requirement; Linux kernel and CPU requirements follow tested dependency support and release documentation.
- No retries, live credentials, weakened sandbox, suppressed warnings, or skipped runtime coverage to make a target pass.

## Exit

- [ ] Linux development, quality gates, tests, docs, benchmarks, and releases use musl application targets.
- [ ] Both Linux architectures produce fully static, portable-CPU musl binaries.
- [ ] Each artifact passes binary workflows on musl and GNU environments.
- [ ] Native ARM64 evidence and target-built Wasmtime execution pass.
- [ ] Extracted archives pass acceptance and published checksum verification.
- [ ] Cargo-owned tooling and CI reject invalid or unverified artifacts.
- [ ] Approved musl instruction pins gate reproducibly; GNU application benchmark lane is retired.
- [ ] Existing lint strictness, allocation/type-size bounds, and wasm guest behavior hold.

## Stop conditions

Required dependency cannot support static musl safely.
Required architecture lacks runtime verification.
DNS, TLS, terminal, plugin, or session behavior regresses.
Tooling needs an unapproved protected-file or machine-level change.
Musl benchmark pins lack reproducible measurements or explicit numeric approval.