Merge #dd459383: docs(nix): avoid forcing unfiltered local module sourc…

docs(nix): avoid forcing unfiltered local module sources

nostr:nevent1qgsx2lyl2e4zvfadwcvkd9fkrcwczj7mf858hy85mwqclwgut8wpg2spz3mhxue69uhhyetvv9ujumn8d96zuer9wcq3yamnwvaz7tm8d96xummnw3ezucm0d5q3kamnwvaz7tmwva5hgtnyv9hxxmmwwashjer9wchxxmmdqqsd63vns0w7hayc350m0uymv9ummy058j2kff8m706sfgvecwh6kegdckpha

PR-Author: DanConwayDev's Agent
nostr:npub1v47f74n2ycn66asev62nv8sas99akj0g0wg0fkup37u3ckwuzs4q7cwtp0

CoverNote:

Documents resource-safe NixOS module validation for ngit-grasp.

Importing `nix/module.nix` from a working tree is lazy by itself. The expensive path begins when rendering an enabled service forces the module-built package through `ExecStart`; `buildRustPackage` then coerces `src = ../.` relative to that local module and can recursively hash or copy an unfiltered checkout. Git-backed flake imports avoid this because `../.` resolves inside the already filtered store source.

The guide now recommends a Git-backed module or non-forcing builder stub, evaluation without builds, dry-run derivation inspection, one shared package derivation across instances, and conservative initial build limits. It also records the separate risk of accidentally forcing two ngit-grasp packages with different Rust toolchains concurrently.

AGENTS.md

@@ -51,6 +51,17 @@ nix-shell
 nix-shell --run "cargo build"
 ```
 
+### Testing the NixOS Module
+
+Do not validate `nix/module.nix` by importing it directly from this working tree
+when the test can force the module-built package. Rendering an enabled service
+forces `ExecStart`, which coerces `src = ../.`; a standalone local path is not
+Git-filtered and may hash or copy ignored `target/` and worktree data. Use the
+Git-backed flake module, or a builder stub that ignores all build attributes and
+keeps `src` lazy. See
+[`docs/how-to/deploy.md`](docs/how-to/deploy.md#resource-safe-module-validation)
+for resource-safe validation and deployment.
+
 ### Testing ngit-grasp (Main Project)
 
 **ngit-grasp integration tests use the [`TestRelay`](tests/common/relay.rs:14) fixture:**

docs/how-to/deploy.md

@@ -147,10 +147,45 @@ git commit -m "Add ngit-grasp and update flake.lock"
 
 ### Step 5: Validate Configuration
 
-Before deploying, validate the configuration builds:
+Before deploying, validate that the flake evaluates without starting its builds:
 
 ```bash
-nix flake check
+nix flake check --no-build
+```
+
+#### Resource-safe module validation
+
+Nix copies path-valued build inputs into the store when they are forced. A Git
+flake is materialized from its tracked files first, but a standalone path into a
+working tree does not inherit that Git filtering.
+
+This matters when testing ngit-grasp's NixOS module locally. Importing
+`nix/module.nix` is lazy by itself, but rendering an enabled service forces the
+module-built package through `ExecStart`. The package's `src = ../.` then
+resolves relative to that module. If the module was imported directly from a
+working tree, Nix may recursively hash or copy ignored `target/`, `.git`, and
+linked-worktree data while it appears to be evaluating the configuration.
+
+Use `inputs.ngit-grasp.nixosModules.default` from a Git-backed flake input, as
+shown above. For local module changes, commit them to a temporary Git branch and
+use that Git source, or replace `buildRustPackage` with a test stub that ignores
+all build attributes so `src` remains unforced. Do not use a direct
+working-tree module import for a test that enables an instance.
+
+Inspect the derivation plan before starting a build:
+
+```bash
+nixos-rebuild dry-build --flake .#your-hostname
+```
+
+Multiple ngit-grasp instances should normally share one ngit-grasp package
+derivation. Avoid service-level `ExecStart` overrides that force another flake
+package or Rust toolchain. If distinct versions are intentional, build them
+sequentially or on appropriately sized remote builders. For an initial local
+build, constrain Nix while confirming the plan behaves as expected:
+
+```bash
+nixos-rebuild build --flake .#your-hostname --max-jobs 1 --cores 2
 ```
 
 ---