docs: document [hash.NAME] domain sections

Add a config-file.md reference section for hash domains: the [hash.*]
wildcard defaults and concrete [hash.NAME] sections, covering function
(crc64/cityhash/xxhash/xxhash3), priority-based primary-domain selection,
and the step/size/seed/insert keys that are clamped to a single legal
value on this branch.  Explain that the multi-domain model is forward
scaffolding for csum-tree scanning and that only the highest-priority
insert domain is wired into the global hash function today.

Now that the prose lives in config-file.md, trim the redundant block
comment in the [hash.*] built-in schema down to a one-line pointer plus
terse per-key constraints, matching the house style of neighbouring
sections.  Also correct the inline function list to include xxhash3,
which the parser already accepts.

Assisted-by: Claude-Code:claude-opus-4-8
Signed-off-by: Zygo Blaxell <bees@furryterror.org>

diff --git a/docs/config-file.md b/docs/config-file.md
index 1fbdcfab8ca21805d21124a3c2950fc7f602212f..bef17ceaa0adfc218072b56c2decf5254f0af8ea 100644 (file)
--- a/docs/config-file.md
+++ b/docs/config-file.md
@@ -546,6 +546,101 @@ hash table catches up.
     back) and may significantly delay checkpoint advances when
     `state.hash.size` is large and `writeback-rate-max` is small.
 
+## [hash.*] and [hash.NAME] sections
+
+A **hash domain** defines one hash function used to fingerprint data blocks.
+Each `[hash.NAME]` section is one domain; the `NAME` suffix is an arbitrary
+label (it is *not* the function name, though the built-in domain happens to use
+`[hash.crc64]`).  At least one domain must be configured — bees fails to start
+with no `[hash.NAME]` section.
+
+The `[hash.*]` wildcard section sets defaults inherited by every named domain,
+exactly like `[scan.extent.*]` and `[filter.*]`.
+
+> **Scope on this release.**  The multi-domain model exists for forward
+> compatibility with csum-tree scanning, but only one domain does any work
+> today: bees uses the **highest-priority insert-enabled domain** as the single
+> global hash function for all scanning and lookup.  Every other domain is
+> parsed, validated, and held in reserve.  Several keys are therefore locked to
+> one legal value (see each key below); setting any other value is a hard
+> startup error rather than a silent default, so a future release can relax the
+> restriction without changing the meaning of an existing file.
+
+### Wildcard defaults: [hash.*]
+
+* **`function`**
+  The hash algorithm.  This key has **no default** — it is the defining
+  identity of a domain, so each concrete `[hash.NAME]` section must set its own.
+  Supported values:
+  * `crc64` — CRC-64; produces the same 64-bit table keys as bees v0.11, so it
+    is backward-compatible with an existing `beeshash.dat`.  This is the
+    function the built-in `[hash.crc64]` domain uses.
+  * `cityhash` — CityHash64.
+  * `xxhash` — XXHash64.
+  * `xxhash3` — XXHash3 (64-bit); faster than `xxhash` on modern hardware.
+  Changing the function changes every key written to the hash table, so a
+  filesystem's `beeshash.dat` is only meaningful under the function that wrote
+  it (see [Notes](#hash-domain-notes)).
+  The values `btrfs`, `crc32c`, `sha256`, and `blake2` are reserved for future
+  implementation and rejected with a clear message.
+
+* **`priority`**
+  Lookup priority.  The highest-priority insert-enabled domain becomes the
+  global hash function; ties are broken by config-file order.  `0` disables
+  lookup for the domain.
+  Default: `100`.
+
+* **`step`**
+  Distance in bytes between the start of one hash window and the next.
+  Must equal the btrfs checksum block size, `4096`.
+  Default: `4096`.
+
+* **`size`**
+  Number of bytes consumed by each hash window.
+  Must equal the btrfs checksum block size, `4096`.
+  Default: `4096`.
+
+* **`seed`**
+  Collision-domain IV used to partition otherwise-identical hashes into
+  separate domains.  Must be `0` on this release.
+  Default: `0`.
+
+* **`insert`**
+  Whether this domain publishes its hashes into `beeshash.dat`.  Must be `yes`
+  on this release (at least one insert-enabled domain is required).
+  Default: `yes`.
+
+### Named domain sections: [hash.NAME]
+
+A `[hash.NAME]` section defines a concrete domain and inherits every `[hash.*]`
+default.  In practice the only key a named section must set is `function`; the
+built-in configuration therefore reduces to:
+
+```ini
+[hash.crc64]
+    function = crc64
+```
+
+To select a different global function, define a domain with a higher priority
+than the built-in one — for example:
+
+```ini
+[hash.fast]
+    function = xxhash3
+    priority = 200
+```
+
+The `[hash.fast]` domain (priority 200) outranks the built-in `[hash.crc64]`
+(priority 100) and becomes the global hash function.
+
+### Hash domain notes
+
+* **The hash table is tied to its function.**  `beeshash.dat` stores 64-bit
+  keys produced by whichever function was active when each entry was written.
+  Switching `function` does not migrate existing entries--matches found before
+  the change will no longer line up.  Old entries will be evicted from
+  the table without matching new data.
+
 ## [thread] section
 
 The `[thread]` section sets how many worker threads bees runs and how aggressively it ramps up under system load.

diff --git a/src/bees-config-v1.cc b/src/bees-config-v1.cc
index a8feae0442c73038b7d8ae45feb868c9a4f50b55..6bb776b0e6b7e27a30e0708ba5fa183a31b26ed6 100644 (file)
--- a/src/bees-config-v1.cc
+++ b/src/bees-config-v1.cc
@@ -454,29 +454,23 @@ static const char bees_config_v1[] = R"--v1-config--(
 
 [hash.*]
 
-        # Step between successive hash windows in bytes.
-        # Must equal the btrfs checksum block size (4096).
+        # Window step; must equal the btrfs csum block size (4096).
         step = 4096
 
-        # Bytes consumed per hash window.
-        # Must equal the btrfs checksum block size (4096).
+        # Window size; must equal the btrfs csum block size (4096).
         size = 4096
 
-        # Seed / collision-domain IV for explicit domain partitioning.
-        # Must be 0.
+        # Collision-domain seed; must be 0 in this version.
         seed = 0
 
-        # Publish this domain's hashes into beeshash.dat.
-       # Must be yes.
+        # Publish this domain's hashes into beeshash.dat; must be yes in this version.
         insert = yes
 
-        # Lookup priority.  Highest value is used first.
-        # 0 disables lookup for this domain.
+        # Lookup priority; highest wins, 0 disables lookup for this domain.
         priority = 100
 
-# Legacy hash domain.  Inherits all [hash.*] defaults.
-# Produces the same 64-bit table keys as bees v0.11 (backward
-# compatible with existing beeshash.dat files).
+# Built-in domain; same 64-bit keys as bees v0.11.  function has no default,
+# so each [hash.NAME] sets its own: crc64, cityhash, xxhash, or xxhash3.
 
 [hash.crc64]