From 1bde5552c5068e2769088b950b20acd3b06881ca Mon Sep 17 00:00:00 2001
From: Antonio Gurgel <antonio@goorzhel.com>
Date: Sun, 3 Dec 2023 18:00:15 -0800
Subject: [PATCH] In ADRs, document assumptions and fix typos

---
 adr/1.md | 28 +++++++++++++++++++++++++---
 adr/2.md |  5 ++++-
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/adr/1.md b/adr/1.md
index f226dce..4d95f6f 100644
--- a/adr/1.md
+++ b/adr/1.md
@@ -7,7 +7,7 @@ As planned at `3b5168f`, I started using multiple service trees at commit
 at `./services` for those that used Helm's `Capabilities.APIVersions` to
 determine the presence of those CRDs.
 
-## Considered Options
+## Considered options
 
 ### Previous solution: per-variable trees
 Because I struggled with infinite recursion early on, I did this in a very dumb
@@ -31,7 +31,7 @@ But something struck me:
 
 ### New solution: ordered list of trees
 
-Here's a thought. Instead of
+Instead of
 
 ```nix
 systemServiceData = rake.leaves ./system;
@@ -51,7 +51,7 @@ services = flakeBuilders.services self.serviceData {
 };
 ```
 
-I do instead:
+I will do:
 
 ```nix
 stages = (ls ./services);
@@ -80,3 +80,25 @@ Since I don't know for sure how common this use case is, I may as well herd ever
 until someone complains.
 
 More to come after I actually write `buildServices` in `src/default.nix`.
+
+## Some other assumptions made
+
+### `./services` is where _all_ service modules go
+
+I don't expect there to be multiple service-tree roots, such as `./system`.
+
+Especially not with Haumea, whose recursive operation allows there to be zero
+or more directory layers between the root, the namespace directory, and the
+service module. In my case, there is one layer: the ordering directory.
+```
+services/00-istio/istio-system/base
+# root
+# ordering (arbitrary directory layer)
+# namespace (req'd by serviceLoader)
+# name (req'd by serviceLoader)
+```
+
+### Each service module's parent dir is its namespace
+
+This assumption has held fast since the beginning, and will continue to hold fast indefinitely.
+It's just common sense.
diff --git a/adr/2.md b/adr/2.md
index da1b81c..aead2c7 100644
--- a/adr/2.md
+++ b/adr/2.md
@@ -1,5 +1,7 @@
 # ADR 2: Using directory trees as data
 
+## Context
+
 In `a2abba2` or sometime around then, I borrowed Nixhelm's [leaf-raking paradigm](https://github.com/farcaller/nixhelm/blob/e0383f7c11000f8c141a7d26197ee402424b017d/flake.nix#L9-L23) (and named it after [Digga's](https://github.com/divnix/digga/blob/baa54f8641ee9128cdda8b508553284c331fc9f1/src/importers.nix#L61-L114)...although this is the first time I'm looking directly at it, and now I'm realizing I could have just borrowed that very code.)
 
 Example input and output, using `kubernetes@2de43d7`:
@@ -53,7 +55,7 @@ Raking a service tree like this reduces the need to litter the source tree with
 `default.nix` files (as seen in, e.g., [nixos-hardware](https://github.com/NixOS/nixos-hardware/tree/a89745edd5f657e2e5be5ed1bea86725ca78d92e)).
 However, it imposes assumptions about the source tree that ADR 1 rendered invalid.
 
-## Considered Options
+## Considered options
 
 ### Adapt existing code
 
@@ -82,6 +84,7 @@ nix-repl> serviceData."0-istio".istio-system."1-18-1"
 
 This leads to another conundrum: how now will I rake the data and pass it to the flake builders?
 
+Solution: don't bother raking the data in advance; use a flake-builder with a custom loader.
 
 ## Decision