Skip to content
HedronitePublic

About

Protocol and drop-in kit for Nix that is pure, correct, dense, and fast. Flakes, packages, NixOS and Home Manager modules.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

163 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Nix-TOPS

Nix-TOPS product mark and wordmark

A protocol and drop-in kit for Nix that is pure, correct, dense, and fast.
Flakes, packages, NixOS and Home Manager modules, and the flake inside a Rust, Go, or web repo.

Nix Hedronite Protocol 0.2.0 License: MIT OR Apache-2.0 CI workflow: nix-tops CI workflow: spec

Quick start · What you get · How it works · Status · Protocol · Harness · Changelog

Built by Hedronite. Structure adapted from Rust-TOPS, Go-TOPS, and Web-TOPS.


Nix-TOPS (Nix Testing and Optimization Protocol Suite) is a protocol for Nix that is pure, correct, dense, and fast. It covers flakes, packages and overlays, NixOS and Home Manager modules and configurations, and the flake that sits in a Rust, Go, or web repository.

The gate evaluates every output on every declared system with warnings fatal, then builds, tests, and measures what the flake produces. This repository holds the spec, the schemas, the facet profiles, the laws as files, and the kit flake with the nixtops runner, a single Rust binary.

The package is unreleased (0.0.0) and has no tag. The runner covers the source and eval gates today; the sandbox checks, baseline and laws come in later milestones. No other repository has adopted it yet.

Pins

Plane Pin Where
Protocol 0.2.0 (draft) NIX_TOPS.md and the schemas
Package 0.0.0, unreleased crates/nixtops/Cargo.toml. No tag
Systems x86_64-linux, aarch64-linux, aarch64-darwin nix-tops.toml. x86_64-darwin is unsupported
Runner toolchain Rust 1.99.1, gated by Rust-TOPS rust-toolchain.toml, rust-tops.yaml
Facet profiles six profiles/
Laws 49 laws/, one TOML file per law

Quick start

From a clone of this repository, with flakes enabled:

nix run .#nixtops -- version
nix run .#nixtops -- check
nix run .#nixtops -- gate

check validates nix-tops.toml against the schema and the semantic rules. gate runs the enabled layers and writes report.json; report renders the last run, and outputs lists every output with its coverage level. init writes nix-tops.toml, the CI workflow and the AGENTS.md section into an adopting flake. baseline and laws print that they are not built yet and exit 4.

The spec checks run without Nix:

python3 -m unittest discover -s scripts/tests
python3 scripts/spec_check.py all
python3 scripts/rules_gen.py check

The schema check needs check-jsonschema 0.38.0, which needs Python 3.10 or later.

What you get

A flake on its own This kit today
Contract Whatever the repo documents Protocol 0.2.0, JSON Schemas, six facet profiles, and 49 laws as files
A runner nix flake check and the tools you wire nixtops version, doctor, check, init, gate, outputs, report, run as nix run .#nixtops
Eval gate Warnings scroll past Every output on every declared system, with abort-on-warn and import-from-derivation off
CI on this repo — The kit gates itself hard (nix-tops), plus kit, rust-tops, spec, fixtures and trial workflows

What you do not get

Claim Reality
A released kit you can pin The package is 0.0.0, untagged. Kit distribution for adopters is M2 work
Sandbox lint, baseline, or the laws layer lib.mkChecks (nixfmt, statix, deadnix, gitleaks), baseline and ratchet arrive at M2; the laws at M3
Line coverage, CRAP, or mutation Nix has no line coverage in this protocol. Coverage becomes output coverage, CRAP becomes closure and eval-cost budgets, and there is no mutation layer in 0.x. See §6
A drop-in for nixpkgs contribution checks nixpkgs-vet and nixpkgs CI do that for nixpkgs itself

How it works

The gate has two planes: hermetic checks in the Nix build sandbox, and a smaller set of checks that need the world outside it. One locked invocation: an adopter re-exports apps.<system>.nixtops and runs nix run .#nixtops -- gate, so no command resolves an unlocked reference. The evaluator that judges is the CppNix pinned in the kit's flake.lock.

What the protocol checks, as the layers land:

Layer How
Source Every .nix file tracked by git; flake.lock committed and current
Lint nixfmt (via nixfmt-tree), statix, deadnix, nixtops-lint, gitleaks, in the build sandbox
Eval Every output on every declared system, with abort-on-warn and import-from-derivation off
Build and test nix flake check, every package, dev shell and build root; nix-unit; NixOS VM tests
Output coverage Every exported output: evaluated, built, tested
Budgets Closure bytes per output; eval counters per output

A repo can adopt Nix-TOPS alongside its language protocol: the language protocol judges the code, and Nix-TOPS judges the flake (dev-flake facet).

Path Role
NIX_TOPS.md The protocol, draft 0.2.0
crates/nixtops/ The runner
flake.nix, nix/ The kit flake: packages.nixtops, apps.nixtops, dev shell, formatter
nix-tops.toml Nix-TOPS gating itself, hard
config/ The AGENTS.md section and the CI workflow template that nixtops init writes
laws/ One TOML file per law (49), and the table of nix diagnostics
profiles/ One floor profile per facet (six)
schema/ JSON Schemas at protocol 0.2.0
fixtures/ Fixture flakes the kit's own gate runs over
examples/quickstart/ The adopter flake of §4 and a stub kit
scripts/ Spec checks, generated rule copies, and the fixture and trial drivers
docs/evidence/ The gate-3 trial against eight pinned public flakes, and the warning-source fixtures
changelog.d/ Changelog fragments, one per protocol-change PR
AGENTS.md Editing harness for this repository (CLAUDE.md imports it)

Status

Draft. Protocol 0.2.0. Package 0.0.0, unreleased. No tag.

This repo is at milestone M1: the runner. The kit gates itself hard on gates 1 and 3 (source and eval) on x86_64 Linux and under Determinate Nix; the other layers and the laws are switched off with a reason until they are built. The kit has no lib output yet, so its own facets are package-set and dev-flake.

Milestone Contents
M0 spec (done) NIX_TOPS.md, schemas, six facet profiles (four launch, two specified and unproven), the laws as files, the AGENTS template
M1 runner (current) The kit flake and nixtops: version, doctor, check, init, gate for gates 1 and 3, report.json; the kit gates itself
M2 Sandbox checks (lib.mkChecks): nixfmt, statix, deadnix, gitleaks; baseline and ratchet; first adopter
M3 Laws v0.1: 29 of 49 judged; nixtops-lint; law fixtures
M4 Output coverage; closure and eval-cost budgets; VM tests; calibrated floors
M5 Adopters and the family toolchain
M6 Tier 2 layers and the exact-answer features
M7 Protocol 1.0

The full roadmap is in NIX_TOPS.md §19.

Related

  • Rust-TOPS: the original protocol.
  • Go-TOPS: the Go protocol. Nix-TOPS starts from its 0.3.0 fixes.
  • Web-TOPS: the web protocol.

Contributing

Read NIX_TOPS.md and AGENTS.md first. Before a PR is ready, run python3 scripts/spec_check.py all (the schema check needs check-jsonschema 0.38.0, which needs Python 3.10 or later), python3 -m unittest discover -s scripts/tests and python3 scripts/rules_gen.py check. Work on a branch and open a PR ready for review when the slice is complete, never a draft. A change to laws, schema, profiles, floors, budgets, eval options or normative spec text is a protocol change: it carries the protocol-change label, a changelog entry, and a protocol version bump.

Credits and license

Built by Hedronite. Structure adapted from Rust-TOPS, Go-TOPS and Web-TOPS. The laws draw on Common Mistakes AI Coding Agents Make in Nix (Hedronite sketch), with the corrections in Appendix B.

Licensed under MIT OR Apache-2.0, at your option. See LICENSE, LICENSE-MIT, and LICENSE-APACHE.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

About

Protocol and drop-in kit for Nix that is pure, correct, dense, and fast. Flakes, packages, NixOS and Home Manager modules.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages