Introduction

NXD is a pre-release infrastructure reconciler for Nix-authored desired state. It evaluates consumer-owned Nix modules into canonical JSON, plans changes, applies persisted plans, and verifies results through typed providers.

Current verified gates include:

• standalone extraction;
• core canonical contracts and fixture reconciliation;
• built-in PVE BackupJob reconciliation;
• a synthetic external-provider protocol trial.

Production use is not generally supported yet. Follow the compatibility matrix and feature evidence before relying on any behavior.

Quick start with disposable fixtures

This tutorial uses checked-in synthetic fixtures only. It does not contact a real provider.

nix develop
cargo run -- validate --config-json tests/fixtures/canonical/minimal-site.json --format json
cargo run -- plan synthetic/example --config-json tests/fixtures/canonical/minimal-site.json --format json

For the Gate C backup-job fixture:

cargo run -- validate --config-json tests/fixtures/infrastructure/backup-job-site.json --format json

For Nix-authored sites, use the shared model and let NXD project canonical resources:

{
  nxd = {
    stack.name = "example";
    site.guests.web = {
      cluster = "lab";
      node = "pve-a";
      vmid = 120;
      tags = [ "production" ];
    };
    providers.pve.lab = {
      endpoint = "https://pve.example.invalid:8006";
      credentialBinding = "secret/pve-api";
    };
    secrets.bindings.pve-api = {
      resolver = "sops-age";
      document = "sites/example/pve.yaml";
      key = "token";
    };
    operations.production.includeTags = [ "production" ];
  };
}

Export it through nxd.lib.evalConfiguration as nxdConfigurations.<site>, then run nxd validate --source .#nxdConfigurations.<site>. Validation does not contact provider endpoints or resolve secret values.

Do not substitute production endpoints into fixture files. Real endpoint runs require an accepted runbook and explicit owner authorization.

Validate configuration

Use validate to parse and validate canonical JSON without contacting a provider:

nxd validate --config-json tests/fixtures/infrastructure/backup-job-site.json --format json

Validation proves local shape and reference constraints. It does not prove live provider compatibility, credentials, trust material, or target identity.

Architecture overview

NXD follows this boundary:

Nix modules -> canonical JSON -> validation -> plan -> persisted apply -> verify

Consumer repositories own topology, inventory, policy, and reviewed state. NXD owns schemas, planning, provider execution, reports, and reusable contracts.

See docs/nxd-integration-design.md for the full accepted design.

Safety model

NXD separates planning from mutation:

• plan observes state and writes a reviewable proposal;
• apply executes exactly one persisted plan;
• verify checks live postconditions without producing mutation actions.

Secrets are represented by bindings in configuration and resolved only at runtime. Secret values must not appear in Nix, canonical JSON, plans, logs, events, argv, URLs, or committed documentation.

Plan cleanup is explicit and recoverable. nxd clean is a dry run unless --apply is supplied, and even then it archives only expired plans without approval, journal, or pin evidence. It never deletes reviewed evidence. Use --pin <plan> before long-lived review, --unpin <plan> when that protection is no longer needed, and --recover <archived-plan> to restore an archived plan. Recovery does not bypass plan expiry, compatibility, or approval checks.

Interactive durable enrollment workflows (deploy, switch --reenroll, and install/convert intents) ask once for the exact enrollment plan and a displayed, bounded same-session continuation across selected targets. The continuation is freshly planned, persisted, digested, and validated against the authorized scope before approval evidence is written. Any changed source, target, action, provider, secret, dependency, or risk stops for explicit review. Non-interactive and separate plan/apply workflows continue to require approval evidence for each plan digest.

Default plan output and interactive approval prompts render a target-grouped summary of pending work, listing destructive and identity-critical actions first and naming exact resources touched. --verbose renders the full action graph with identifiers and dependency edges.

CLI reference

Generated from the released Clap command model. Do not edit by hand.

Provider resource reference

Generated from the released linked-provider metadata. Do not edit by hand.

Shared Nix option reference

Generated from nix/modules/authoring/. Do not edit by hand.

NXD derives canonical IDs, provider resources, associations, operation sets, and allowlisted PVE host-state files. It refuses duplicate IDs, unknown or unused reserved operation tags, unsupported host-state paths, and empty operation policy.

Compatibility matrix

See docs/compatibility.md in the repository source. Released manuals will include a generated compatibility matrix from release metadata.

Incident response

See docs/runbooks/incident-response.md in the repository source.

Do not include secrets, private endpoints, raw production journals, or unredacted infrastructure captures in public reports.

Release readiness

See docs/release/release-policy.md and docs/release/supply-chain.md.

NXD is pre-release. Release signing, SBOM, and provenance automation are planned pre-alpha work.

Security policy

See SECURITY.md in the repository root for current reporting instructions.

Common failures

Validation fails

Check for unknown fields, duplicate resource IDs, unresolved references, and invalid provider configuration.

Apply refuses a plan

Apply may refuse expired, stale, wrong-provider, incompatible, or changed-input plans. Re-run plan after investigating the refusal.

Provider operation is ambiguous

Mutation disconnects and timeouts are ambiguous. Do not blindly retry mutation. Observe current state and replan.

Contributing

Read CONTRIBUTING.md, AGENTS.md, and docs/README.md before proposing a change.

Non-trivial work requires accepted artifacts, tests, evidence, and review.