From 199871bf7efa9d2a943c4c2c448af3680da771ac Mon Sep 17 00:00:00 2001
From: Austin Horstman <khaneliman12@gmail.com>
Date: Fri, 2 Oct 2026 08:52:39 -0500
Subject: [PATCH] generators: document TOML date limitation in
 mkImpureConfigMerger

jaq 3.1.1 reads TOML through toml-span, which does not deserialize
date or time values. An existing TOML file containing one makes the
merge refuse, so activation fails on every switch until the value is
removed. The file itself is left untouched.

Document the limitation and test that the refused merge leaves the
file byte-identical. If a later jaq parses these values, they would
pass through JSON as strings, so the test is expected to fail then and
prompt a review of the documented behavior.
---
 modules/lib/generators.nix                    |  4 ++++
 tests/lib/generators/mkImpureConfigMerger.nix | 15 +++++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/modules/lib/generators.nix b/modules/lib/generators.nix
index 795e485342..11b6abc07f 100644
--- a/modules/lib/generators.nix
+++ b/modules/lib/generators.nix
@@ -930,6 +930,10 @@ in
     preserved. YAML is written in block style with `---` and `...` document
     markers.
 
+    As of `jaq` 3.1.1, TOML date and time values are not supported. An existing
+    TOML file containing such values causes activation to fail without modifying
+    the file. Subsequent activations will also fail while those values remain.
+
     :::{.warning}
     This function is **experimental**: its interface and generated script may
     change without notice in future releases, as edge cases around the
diff --git a/tests/lib/generators/mkImpureConfigMerger.nix b/tests/lib/generators/mkImpureConfigMerger.nix
index 08e9443eb4..313756a6e9 100644
--- a/tests/lib/generators/mkImpureConfigMerger.nix
+++ b/tests/lib/generators/mkImpureConfigMerger.nix
@@ -102,6 +102,12 @@ let
       key: nix
     ...
   '';
+
+  userDateToml = builtins.toFile "user-date.toml" ''
+    # Keep this file intact when jaq cannot parse its date value.
+    date = 1979-05-27T07:32:00Z
+    userSetting = 5
+  '';
 in
 {
   nmt.script = ''
@@ -178,6 +184,15 @@ in
     $TMPDIR/merge-toml
     assertFileContent $tomlSettings ${expectedToml}
 
+    # jaq 3.1.1 cannot parse TOML dates. If a newer jaq can, they would pass
+    # through JSON as strings and come back as TOML strings, so this failing
+    # means the documented limitation needs revisiting.
+    cat ${userDateToml} > $tomlSettings
+    if $TMPDIR/merge-toml > /dev/null 2>&1; then
+      fail "Merging TOML with a date value must fail activation"
+    fi
+    assertFileContent $tomlSettings ${userDateToml}
+
     substitute ${mergeYaml} $TMPDIR/merge-yaml --subst-var TMPDIR
     chmod +x $TMPDIR/merge-yaml
     yamlSettings=$TMPDIR/hm-user/.config/testmerger/settings.yaml