Spec library

How the project presents itself, wherever it speaks: README, docs, release notes, commit messages, issue replies, social accounts, conference talks. A spec, a page, or a post that contradicts one of these has to say so and argue the case; silence means the principle holds. Cite them by ID (I2, I5) in reviews. IDs are stable: retired principles keep their number rather than freeing it for reuse. netfyr replaces software that people depend on and that other people maintain. Most of what follows exists so that saying the first part never requires insulting the second.

Constraints every spec in this repo inherits. A spec that contradicts one of these has to say so and argue the case; silence means the principle holds. Cite them by ID (P4, P7) in specs and reviews. IDs are stable: retired principles keep their number rather than freeing it for reuse. netfyr replaces the host's network engine: the component that owns rtnetlink and turns configuration into interface state. NetworkManager and nmstate are the primary migration targets because that is where the users netfyr is built for are today. netplan and systemd-networkd hold the same role for other users and...

Implement JSON Schema-based validation for network device state, including field definitions, writability tracking, and device type inference. Without schema validation, typos in field names (e.g., `mtt` instead of `mtu`) or attempts to set read-only hardware properties would only surface as confusing backend errors or silent no-ops. Validating early, before any system changes, gives clear, actionable error messages. The schema also serves as the authoritative definition of the data model for each device type.

Implement the core data model for network device state and the YAML serialization format. This is the foundational crate that every other crate depends on. All layers of netfyr (policies, reconciliation, backend, CLI) operate on the same state representation. The data model must support ordered collections and multiple configuration sources per device . A `State` is the basic unit of configuration: one source's contribution to one device. Multiple sources (static user configuration, and dynamic providers such as DHCP, VPN, or IPv6 router advertisements) may each produce a `State` for the same ...

Query Linux interface state and execute the explicit operation plans defined by SPEC-005 through an asynchronous `NetworkBackend` boundary. Linux I/O belongs here; policy binding, priority merging, and address reorder decisions belong to reconciliation. The initial backend configures physical Ethernet interfaces and veth devices. It reports other interfaces without claiming to manage them.

Bind policy contributions to discovered devices, merge their fields by priority, and plan the changes needed to reach the effective desired state. SPEC-001 defines contributions and selectors; SPEC-003 produces those contributions. Several policies may configure one device. Reconciliation must retain their nonconflicting fields instead of choosing one whole policy and dropping the others. The decision function takes explicit configuration, observed state, and merge options. It performs no I/O. The caller loads policies, queries the backend, invokes the planner, and passes the resulting operati...

Implement the core in-memory representation of network device state. This is the foundational crate that every other netfyr crate builds on. Policies, reconciliation, backends, and user interfaces all operate on the same model, but this specification defines only that model. External document formats, schema lookup, validation, and conversion between documents and model values are defined by later specifications. A `State` is one source's contribution to one device. Multiple sources, such as static user configuration, DHCP, VPN, IPv6 router advertisements, and the kernel, may each produce a `S...

Provide reproducible tests of netfyr's observable behavior against an explicitly selected build and environment. Rust unit tests cover internal contracts, acceptance tests cover specification requirements through public interfaces, and integration tests verify those contracts against Linux. A cheap unit test does not replace an acceptance or real-backend check that the requirement needs. This spec adopts pytest for new network integration and acceptance tests under `tests/integration/`. It deliberately extends SPEC-000's shell-only integration convention: pytest supplies shared fixtures, param...

Set up the Rust workspace scaffolding, project metadata, and integration test infrastructure. This spec creates no library or binary crates -- those are added by subsequent specs as needed. It establishes the project foundation so that build system, testing conventions, and project metadata are in place before any feature work begins.

Every change to a netfyr repository must name the spec it implements, in a form a machine can check. Work is assigned spec by spec, but once a branch is merged nothing connects the resulting commits back to the spec they came from, so answering "what did this spec actually ship" means reading diffs and guessing. This spec defines the reference format, where it appears, how a spec is marked complete so the board can close it, and the enforcement that keeps all of it correct at commit time rather than at review time.