From 27d1506b54dcc7460ade1aa1bfddf71fbe1a0100 Mon Sep 17 00:00:00 2001
From: Bernardo Magri <bernardo@bernardomagri.eu>
Date: Tue, 19 May 2026 18:28:54 +0100
Subject: [PATCH] chore(lib): drop dead helpers, document schema boundary
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two unused helpers and a missing comment in the lib/ surface, found
during the Pillar 8 sweep.

- `readState` in `lib/default.nix` was exported but has no external
  callers — only `readHomeState` and `readSystemState` use it
  internally. Removed from the export list; the function stays in the
  let-block (still wraps the two public readers).

- `getWithDefault` in `lib/state-schema.nix` was a complete dead
  function: declared as a path-walking fallback helper but never called
  anywhere in the tree. core/{system,home}/state.nix use inline
  `togglesState.<key> or schema.<scope>.<key>` instead. Removed.

- Added a header comment to `lib/state-schema.nix` explaining the
  schema's boundary — it lists every state.json field consumed by a
  Nix option, but state.json may also hold runtime-only fields
  (`welcome_done` from `nomarchy-welcome`) that are intentionally
  off-schema because no Nix option reads them. Future readers will
  otherwise think welcome_done is an orphan.

Logged a Later-column roadmap row for consolidating `flake.nix`'s
palette/themeNames re-imports with `nomarchyLib` so the theme list has
one source of truth instead of two.
---
 docs/ROADMAP.md      |  1 +
 lib/default.nix      |  1 -
 lib/state-schema.nix | 20 +++++++++-----------
 3 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index a3ea69d..c6c389a 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -39,6 +39,7 @@ Guardrails (apply when adding anything):
 - **Forgejo release pipeline.** `vYY.MM.x` tags matching the upstream NixOS channel; the pipeline pushes the three ISOs and an updated `flake.lock` snapshot.
 - **Optional `nomarchy-installer-vm`** rebuilt as a real flake app (not a one-off shell script) so users can install Nomarchy into a libvirt VM declaratively.
 - **Surface support module** via the relevant `nixos-hardware` profile + Surface kernel patches behind a `nomarchy.hardware.isSurface` toggle.
+- **Consolidate palette imports in `flake.nix` via `nomarchyLib`.** `flake.nix:79-80` re-imports `./themes/palettes` and recomputes `themeNames` even though `lib/default.nix` already exports both. Two computations, same result today — drift risk tomorrow. Import `nomarchyLib = import ./lib { inherit lib; }` once and use `nomarchyLib.{palettes,themeNames}` to make `lib/default.nix` the single source of truth for the theme list.
 
 ## 3. Pillar: Script & menu audit
 
diff --git a/lib/default.nix b/lib/default.nix
index 18c2feb..a90b941 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -98,7 +98,6 @@ let
 in {
   inherit
     palettes
-    readState
     readHomeState
     readSystemState
     resolveWallpaper
diff --git a/lib/state-schema.nix b/lib/state-schema.nix
index bc98b87..50bb2d5 100644
--- a/lib/state-schema.nix
+++ b/lib/state-schema.nix
@@ -1,5 +1,13 @@
 # Nomarchy State Schema
-# Defines the complete state shape with defaults for both home and system state
+#
+# Defines the default values for every state.json field that's consumed by a
+# Nix option. Read by core/{system,home}/options.nix (for `default = …`) and
+# by core/{system,home}/state.nix (for `or` fallbacks).
+#
+# state.json may also hold runtime-only fields that aren't declared here —
+# notably `welcome_done`, managed by `nomarchy-welcome`. Those are intentionally
+# off-schema because no Nix option reads them; the schema is the "consumed by
+# Nix" surface, not the full state.json shape.
 { lib }:
 
 {
@@ -54,14 +62,4 @@
     };
   };
 
-  # Get a value from state with fallback to default
-  getWithDefault = state: path: default:
-    let
-      pathList = lib.splitString "." path;
-      getValue = obj: remaining:
-        if remaining == [] then obj
-        else if builtins.isAttrs obj && builtins.hasAttr (builtins.head remaining) obj
-        then getValue obj.${builtins.head remaining} (builtins.tail remaining)
-        else default;
-    in getValue state pathList;
 }
-- 
2.49.1