feat(apr-cli): CRUX-B-05 safetensors shard/unshard (apr shard + apr unshard)#1683
Merged
Conversation
noahgift
added a commit
that referenced
this pull request
May 15, 2026
…CI noise floor (#1692) `brick::brick_tests::tests::rmsnorm_brick_runs` started failing with `budget exceeded` on contended self-hosted runners — observed across at least 5 concurrent PRs (#1688, #1689, #1685, #1683, #1675) on 2026-05-15, including the ETXTBSY retry-window fix PR which has zero relation to brick code. A 4-element RmsNorm is microseconds of real compute. The previous 1ms budget (already labelled "more lenient" by a prior bump) sits inside the noise floor when the runner is concurrently building 10+ cargo workspaces sharing target dirs + L3 — wall time spikes 50–100×. 100ms preserves the guardrail (catches genuine 100s-of-ms perf regressions) without crossing the contention noise floor. Per Toyota Way memory rule: flakes are real defects, not items to mark `#[ignore]` or rerun-until-green. Verified: `cargo test -p aprender-serve --lib rmsnorm_brick_runs` → ok. Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Closes the safetensors shard/unshard parity gap with HuggingFace
`model.safetensors.index.json`:
- `apr shard FILE --max-shard-size SZ -o OUT/`
Splits a single safetensors file into N shards
`model-NNNNN-of-MMMMM.safetensors` + emits a deterministic
`model.safetensors.index.json` (alphabetically-sorted weight_map +
metadata.total_size).
- `apr unshard DIR -o merged.safetensors`
Walks `model.safetensors.index.json`, validates shard filenames
(no absolute paths, no `..`), and reconstructs a single safetensors
file whose tensor values are byte-identical to the original.
Round-trip identity, weight-map coverage, and total_size invariant ship
as in-tree falsifiers under `cargo test -p apr-cli --lib commands::shard`
(25 tests green: 3 FALSIFY-CRUX-B-05-001/002/003 + 22 supporting).
Contract promotion: contracts/crux-B-05-v1.yaml
v1.0.0-draft, status: draft, intake_status: partial
→ v1.1.0, status: partial_algorithm_level, intake_status: supported
3-surface drift:
- extended_commands.rs: new `Shard` + `Unshard` clap variants
- dispatch_analysis.rs: `dispatch_shard` / `dispatch_unshard`
- contracts/apr-cli-commands-v1.yaml: `shard`, `unshard` entries
- crates/apr-cli/tests/cli_commands.rs: registered_commands updated
- All `apr <cmd> --help` exit 0 (cli_commands.rs 8/8 green)
Naming: kept verbs orthogonal from the existing `apr merge` model
parameter-averaging command (average | weighted | slerp | ties | dare)
by introducing `apr unshard` instead of overloading `apr merge`. The
contract description was updated to reflect this.
CRUX M1 epic (#918) progress: K-11 (PR #1680, modelfile DSL) +
B-05 (this PR) = 2/6 stories. Remaining: C-04, C-11, C-13, I-04, K-02
all require a live aprender-serve endpoint and stay PARTIAL pending
that upstream.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
noahgift
force-pushed
the
feat/crux-b-05-safetensors-shard
branch
from
def7671 to
57e226e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
CRUX-B-05 safetensors shard/unshard via weight-map — HuggingFace
model.safetensors.index.jsonparity:apr shard FILE --max-shard-size SZ -o OUT/— split a singlesafetensors file into N shards named
model-NNNNN-of-MMMMM.safetensors,plus a deterministic alphabetically-sorted
model.safetensors.index.jsonwith
weight_map+metadata.total_size.apr unshard DIR -o merged.safetensors— reconstruct a singlesafetensors file from the sharded directory, with shard-path validation
(no absolute paths, no
..) and total_size cross-check.Round-trip identity, weight-map coverage, and total_size invariant ship
as in-tree falsifiers — 25 tests green under
cargo test -p apr-cli --lib commands::shard(3 FALSIFY-CRUX-B-05-001/002/003Naming choice: kept verbs orthogonal from existing
apr merge(model parameter averaging: average | weighted | slerp | ties | dare)by introducing
apr unshardinstead of overloading the verb. Contractdescription and FALSIFY tests updated accordingly.
Contract promotion
contracts/crux-B-05-v1.yaml:remains pending golden-set population.
3-surface drift compliance
crates/apr-cli/src/extended_commands.rs—Shard+Unshardclap variantscrates/apr-cli/src/dispatch_analysis.rs—dispatch_shard/dispatch_unshardcontracts/apr-cli-commands-v1.yaml—shard+unshardentriescrates/apr-cli/tests/cli_commands.rs—registered_commandsmirroredapr <cmd> --helpexit 0 verified (cli_commands.rs 8/8 green)CRUX M1 epic (#918) progress
Test plan
cargo test -p apr-cli --lib commands::shard— 25/25 green (3 falsifiers + 22 supporting)cargo test -p apr-cli --test cli_commands— 8/8 greencargo test -p apr-cli --lib— 5708/5708 greenpv validate contracts/crux-B-05-v1.yaml— 0 errors, 0 warningsapr shard model.safetensors --max-shard-size 8KB -o out/ && apr unshard out/ -o rebuilt.safetensors→ tensors byte-identicalcargo fmt --all -- --check(apr-cli unchanged)cargo clippy -p apr-cli --lib --no-deps -- -D warnings🤖 Generated with Claude Code