Keep supported module implementations in-tree

README.md

@@ -3,7 +3,8 @@
 This repository holds Replit's Nix modules.
 
 * Each module is located as a folder under `pkgs/modules`
-* `pkgs/modules/default.nix` specifies a list of the active modules, some of which are parameterized with the version of the runtime or compiler
+* `pkgs/modules/default.nix` registers every shipped implementation, some of which are parameterized with the version of the runtime or compiler
+* Docker and Zig 0.11 remain compatibility-only implementations: included in the bundle but excluded from `activeModules` and `activeDeploymentModules`, as before
 
 To list all active modules, you can do:
 
@@ -24,12 +25,29 @@ Output might look like:
 }
 ```
 
-To list all modules (including historical modules):
+To list all modules (including compatibility implementations and retired-ID aliases):
 
 ```
 nix eval .#modules --json | jq
 ```
-This will take a while.
+### Supporting and retiring versions
+
+Every shipped module implementation lives in this checkout. Module definitions
+must not import outputs from an older nixmodules flake. Runtime packages can use
+explicit, locked upstream inputs: Docker and Zig retain their previous toolchain
+pins through `nixpkgs-docker`, `nixpkgs-zig`, and `zig-overlay`. Their definitions
+use the current module schema; moving them here does not upgrade their runtimes.
+
+When adding a version, prefer another registration of a parameterized module.
+To keep an older version supported, retain its package pin and registration.
+To retire an implementation, remove its registration and unused definition and
+package inputs, then optionally add an upgrade alias for its old ID. An alias is
+not a supported version of the old runtime. Removing the alias stops accepting
+that ID in new bundles; neither operation changes previously published bundles.
+
+Implementation IDs must be unique. Aliases must resolve to an implementation,
+must not form cycles, and must not shadow an implementation. CI checks these
+invariants and evaluates both development and deployment module maps.
 
 Retired module IDs remain available through `pkgs/upgrade-map`: they resolve to
 newer modules without keeping the retired implementations in the bundle.
@@ -43,7 +61,7 @@ runtime and tools with this bundle and may need code or dependency changes.
 
 For each of the following examples, the build result will be found in a file or directory named `result`.
 
-To build all active modules (this will take a while, and a lot of disk space):
+To build the full bundle, including compatibility modules (this will take a while, and a lot of disk space):
 
 ```
 nix build .#bundle

flake.nix

@@ -9,6 +9,10 @@
   inputs.nixpkgs-nodejs.url = "github:nixos/nixpkgs/5873d3da531a3a8320c9e639e2147eccbe7f2d0d";
   inputs.nixpkgs-node24.url = "github:nixos/nixpkgs/dc0146be65ada0333393ac87b6ff45a4a8e9b722";
   inputs.nixpkgs-php.url = "github:nixos/nixpkgs/8c259fc0dd1f3ccc1aaf4f9156ab16b7328b5a4f";
+  inputs.nixpkgs-docker.url = "github:nixos/nixpkgs/fcb54ddcc974cff59bdfb7c1ac9e080299763d2d";
+  inputs.nixpkgs-zig.url = "github:nixos/nixpkgs/ecb441f22067ba1d6312f4932a7c64efa8d19a7b";
+  inputs.zig-overlay.url = "github:mitchellh/zig-overlay/ee376d4012e3c853123ca7083af852313235407c";
+  inputs.zig-overlay.inputs.nixpkgs.follows = "nixpkgs-zig";
   inputs.fenix.url = "github:nix-community/fenix";
   inputs.fenix.inputs.nixpkgs.follows = "nixpkgs";
   inputs.nil.url = "github:oxalica/nil";
@@ -22,7 +26,7 @@
   inputs.replit-rtld-loader.url = "github:replit/replit_rtld_loader";
   inputs.replit-rtld-loader.inputs.nixpkgs.follows = "nixpkgs";
 
-  outputs = { self, nixpkgs, nixpkgs-23_05, nixpkgs-24_11, nixpkgs-25_05, nixpkgs-master, nixpkgs-staging, nixpkgs-nodejs, nixpkgs-node24, nixpkgs-php, prybar, java-language-server, nil, fenix, replit-rtld-loader, ... }:
+  outputs = { self, nixpkgs, nixpkgs-23_05, nixpkgs-24_11, nixpkgs-25_05, nixpkgs-master, nixpkgs-staging, nixpkgs-nodejs, nixpkgs-node24, nixpkgs-php, nixpkgs-docker, nixpkgs-zig, zig-overlay, prybar, java-language-server, nil, fenix, replit-rtld-loader, ... }:
     let
       mkPkgs = nixpkgs-spec: system: import nixpkgs-spec {
         inherit system;
@@ -50,6 +54,18 @@
       pkgs-php = import nixpkgs-php { system = "x86_64-linux"; };
       pkgs-nodejs = import nixpkgs-nodejs { system = "x86_64-linux"; };
       pkgs-node24 = import nixpkgs-node24 { system = "x86_64-linux"; };
+      # Keep the shipped toolchains pinned while moving their module definitions in-tree.
+      pkgs-docker = import
+        (nixpkgs-docker.legacyPackages.x86_64-linux.applyPatches {
+          name = "nixpkgs-unstable-patched";
+          src = nixpkgs-docker;
+          patches = [ ];
+        })
+        { system = "x86_64-linux"; };
+      pkgs-zig = import nixpkgs-zig {
+        system = "x86_64-linux";
+        overlays = [ zig-overlay.overlays.default ];
+      };
       nodejs-22 = pkgs-nodejs.nodejs_22;
       nodejs-24 = pkgs-node24.nodejs_24;
       deno-src = pkgs-nodejs.fetchFromGitHub {
@@ -136,6 +152,18 @@
       packages.x86_64-linux = import ./pkgs {
         inherit pkgs self;
       };
+      checks.x86_64-linux.module-registry =
+        assert import ./scripts/module-registry-test.nix;
+        assert builtins.attrNames self.modules == builtins.attrNames self.deploymentModules;
+        assert builtins.attrNames self.activeModules == builtins.attrNames self.activeDeploymentModules;
+        assert builtins.all
+          (id:
+            builtins.hasAttr id self.modules
+            && builtins.hasAttr id self.deploymentModules
+            && !(builtins.hasAttr id self.activeModules)
+            && !(builtins.hasAttr id self.activeDeploymentModules))
+          [ "docker" "zig-0.11" ];
+        pkgs.writeText "module-registry-check" "ok";
       devShells.x86_64-linux.default = pkgs.mkShell {
         packages = with pkgs; [
           python310
@@ -158,6 +186,7 @@
         inherit deno uv;
         inherit nodejs-22 nodejs-24;
         inherit pkgs-php;
+        inherit pkgs-docker pkgs-zig;
       }
     );
 }