{
  description = "RDBMS Playground — Rust TUI dev environment + reproducible build";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
    rust-overlay = {
      url = "github:oxalica/rust-overlay";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, rust-overlay, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs {
          inherit system;
          overlays = [ (import rust-overlay) ];
        };

        # Single source of the Rust toolchain: the rustup toolchain file.
        # rust-overlay provisions the exact channel + components declared there,
        # so the dev shell and the build package share one pinned toolchain.
        rust = pkgs.rust-bin.fromRustupToolchainFile ./rust-toolchain.toml;

        # Read the package version straight from Cargo.toml so it never drifts
        # from the crate metadata (no hand-maintained duplicate here).
        cargoToml = builtins.fromTOML (builtins.readFile ./Cargo.toml);

        # System build inputs are deliberately tiny — this is a pure-Rust TUI:
        #   * libsqlite3-sys is built with the `bundled` feature, so SQLite is
        #     compiled from vendored C. That needs a C compiler, which the
        #     stdenv provides automatically (no entry required here).
        #   * arboard's clipboard backend is `x11rb` — a pure-Rust socket XCB
        #     client. It links no C X11 libraries, so none appear below. A live
        #     X server is only needed at *runtime* to copy; headless sessions
        #     fall back to OSC 52.
        # If a future dependency introduces a pkg-config / native-lib link, add
        # it here (and document why) rather than leaking it into the host env.
        nativeBuildInputs = [ ];
        buildInputs = [ ];

        # `nix build` → the release binary, built reproducibly from the pinned
        # toolchain and the committed Cargo.lock (importCargoLock fetches each
        # dependency by its lockfile checksum — offline, no cargoHash to churn).
        # CI's release job consumes this artifact; the gate's tests run
        # separately via `nix develop -c cargo test` (see below), so the package
        # build skips the suite — the nix sandbox has no HOME/X server and would
        # fight the project-dirs / clipboard paths the tests touch.
        rdbms-playground = pkgs.rustPlatform.buildRustPackage {
          pname = cargoToml.package.name;
          version = cargoToml.package.version;
          src = ./.;
          cargoLock.lockFile = ./Cargo.lock;
          inherit nativeBuildInputs buildInputs;
          doCheck = false;
        };
      in {
        packages.default = rdbms-playground;
        packages.rdbms-playground = rdbms-playground;

        devShells.default = pkgs.mkShell {
          buildInputs = buildInputs ++ pkgs.lib.optionals pkgs.stdenv.isDarwin [
            # macOS release builds (aarch64/x86_64-apple-darwin) link AppKit
            # (arboard) + libSystem; the Apple SDK provides those framework/
            # system-lib stubs as *system* paths (/usr/lib, /System/Library).
            # NOTE: the darwin stdenv still propagates a *nix-store* libiconv and
            # links it regardless of inputs, so the release workflow rewrites that
            # one load path to /usr/lib/libiconv.2.dylib (install_name_tool) and
            # re-signs — see release-macos / the macOS smoke-test. Adding
            # `pkgs.libiconv` here would only reinforce the wrong path, so don't.
            pkgs.apple-sdk
          ];
          nativeBuildInputs = nativeBuildInputs ++ [
            rust
            # Dev-disk maintenance: cargo never garbage-collects stale per-hash
            # build artifacts, so target/ creeps into the tens of GB (see
            # CLAUDE.md "Build hygiene"). cargo-sweep prunes them; run it
            # periodically between milestones.
            pkgs.cargo-sweep
          ] ++ pkgs.lib.optionals pkgs.stdenv.isLinux [
            # Cross-compilation for the non-macOS D1 targets: `cargo zigbuild`
            # uses Zig's bundled clang + libc as one universal cross cc/linker
            # (incl. the `cc`-crate compile of rusqlite's bundled SQLite C) for
            # Linux musl + Windows gnu/gnullvm. macOS builds natively with the
            # Apple toolchain on the Mac runner, so these are Linux-only.
            pkgs.cargo-zigbuild
            pkgs.zig
          ];

          shellHook = ''
            echo "RDBMS Playground dev shell ($(uname -s))"
            echo "  rust:   $(rustc --version | cut -d' ' -f1-2)"
            echo "  cargo:  $(cargo --version | cut -d' ' -f1-2)"
          '';
        };
      });
}