Write for
the fold.
A fold engine you cannot inspect is a fold engine you cannot trust. The Hotfloor SDK will tell you what it did to every page in your resident set, fail your build before a customer finds the problem, and run the same benchmark harness we publish our own figures with.
01The CLI
Six commands, no ceremony
| Command | What it does |
|---|---|
nitro bench | Runs the NITROBENCH 4 profile set and writes a signed result file. |
nitro budget | Static block-budget check. Fails your build if a warez set cannot fit the target deck. |
nitro fold --explain | Prints why each page folded or did not. The only honest way to tune a resident set. |
nitro trace --floor | Measures what your build emits at idle, in counts per minute. |
nitro evict --replay | Replays a captured eviction trace against another generation. Works back to G2. |
nitro sign | Signs a profile for distribution. Keys are yours; we never see them. |
02The budget linter
Fail the build, not the deck
nitro budget reads a resident set, folds it statically against a target deck’s fold table, and returns non-zero if the set will not fit. Put it in your build. A warez set that overruns a customer’s blocks fails at the worst possible moment, which is mid-run, on their deck, at their trace level.
The static fold is conservative by design: it counts a page as folded only when it can prove the match, so the number it gives you is a floor, not a hope. Real residency is usually two to five per cent better.
Target every deck you claim to support, including the nx5-s. Sixteen blocks is where sets break, and it is the deck most of your users will be learning on.
$ nitro budget --target nx5-s --set ./sweep.set --strict reading 17 residents … 16 blocks available fold candidates 3,902 pages folded (proven) 2,118 pages (54.3%) resident cost 17.8 blocks of 16 FAIL E-BLK-12 over by 1.8 blocks largest resident sweep/sentry-b 4.1 blocks suggestion --target nx5-t, or split sweeper $ echo $? 12
03The fold explainer
$ nitro fold --explain --set ./ward.set --target nx5-x
ward/barrier-a pages 612
folded 588 shared with barrier-b, barrier-c
refused 18 alignment (pad to 64 B) E-FLD-04
refused 6 unique
ward/wrap-1 pages 344
folded 120 shared with wrap-2
refused 224 unique — constant table is per-instance
set ratio 1.68x (deck ceiling 1.72x)
hint hoist wrap-1/table to a shared segment: +0.09xWhy, not just how much
Every refusal comes with its reason. Most of them are one of two things: a segment that is not 64-byte aligned, or a constant table that has been written per-instance when it could have been hoisted into a shared segment. Both are cheap to fix and both are worth blocks.
nitro fold --explain is the only honest way to tune a resident set. Guessing at it from the ratio alone wastes an afternoon; reading the refusals takes ten minutes.
A set of genuinely unique residents folds to about 1.08× and there is nothing the tool or the deck can do about that. When that is the answer the explainer says so plainly rather than suggesting a micro-optimisation that will not help.
04The benchmark harness
The same one we publish with
nitro bench is NITROBENCH 4. Not a cut-down version of it — the harness, all forty-one profiles, and the signed run files behind every figure on our benchmarks page.
We publish it because a supplier’s own benchmark is worth exactly as much as its method is inspectable. Run it against our hardware, run it against anyone’s. If your numbers disagree with ours, the run files are signed and comparable and we would rather argue about a profile than be quietly disbelieved.
Results are written as a signed result file. Nothing is uploaded. There is no telemetry in the SDK, no phone-home in the runtime, and no account to create.
$ nitro bench --profile 12 --runs 12 --out ./run.nbr deck NX5/X firmware 4.1.2 profile 12 mixed set, 19 residents ambient 23.8 C enclosure closed warm-up 5 min (excluded) run 01 1,182 MB/s … run 12 1,176 MB/s median 1,180 MB/s spread 1,169–1,188 fold ratio 1.72x signed ./run.nbr
05ABI and deprecation
What we promise
- ABI supported
- current + previous minor
- Deprecation notice
- two minors, min. 9 months
- Profile format stability
- frozen since 3.0
- Replay compatibility
- back to G2
- Changelog
- day of release
- Signing keys
- yours, never ours
We ship a generation roughly every 9 months. That is good for hardware and hostile to anyone maintaining a build, so the ABI moves slower than the silicon on purpose: five generations have produced two breaking ABI changes, both announced two minors ahead.
Targets and their windows
| Gen | Deck | Blocks | Fold | Build target |
|---|---|---|---|---|
| G1 | NX1 | 12 | 1.12× | replay only |
| G2 | NX2 | 16 | 1.19× | replay, no new builds |
| G3 | NX3 | 20 | 1.33× | replay, no new builds |
| G4 | NX4 | 24 | 1.46× | supported |
| G5 | NX5 | 24 | 1.72× | supported |
06Error codes
Every code we emit
| Code | Meaning | What to do |
|---|---|---|
E-BLK-12 | Block budget exceeded at link time | Run nitro budget --target and cut the largest resident. |
E-FLD-04 | Fold table rejected a page: alignment | Pad the segment to 64 B. The linter warns about this. |
E-FLD-19 | Fold ratio fell below the declared floor | Your set is pathologically unique. Declare a lower floor or accept the blocks. |
E-EVT-07 | Eviction predictor starved of history | Expected on a cold jack. Ignore for the first 90 s. |
E-TRC-02 | Trace floor above the profile ceiling | A resident is chattering. nitro trace --floor --per-resident. |
E-ABI-01 | Profile built against an unsupported ABI | Rebuild. We support the current and previous minor, nothing older. |
The SDK is distributed as a signed archive through your yard’s supply desk alongside firmware, or from any deck’s service bus. It collects nothing, sends nothing and asks for nothing. There is no developer account and we do not want your email address.