Update Technical_Decomp_Diff

Technical_Decomp_Diff.md

@@ -14,7 +14,7 @@ Purpose: represents a prepared harvest bundle that diff can read from.
 
 `state_path` -> Path: dir / "state.json"
 
-#### Lifecycle / where it’s used:
+#### Lifecycle / where it's used:
 
 Constructed by _bundle_from_input(path, sops_mode=...) which accepts:
 
@@ -27,4 +27,32 @@ Constructed by _bundle_from_input(path, sops_mode=...) which accepts:
 
 #### Key design detail:
 
-This class is the bridge between "user supplied something" and “we have a real directory with files”.
+This class is the bridge between "user supplied something" and “we have a real directory with files”.
+
+_____________
+
+### FileRec (frozen dataclass)
+
+Purpose: a normalized record for one harvested file entry, used for diff indexing.
+
+#### Fields:
+
+- path: absolute destination path on the target system (e.g. /etc/nginx/nginx.conf)
+- role: which role captured it (e.g. nginx, etc_custom, users)
+- src_rel: relative path inside that role’s artifact tree (usually path.lstrip("/"))
+- owner, group, mode: file metadata captured during harvest (strings)
+- reason: why the file was captured (modified_conffile, systemd_dropin, etc.)
+
+#### Lifecycle / where it's used:
+
+Built by _file_index(bundle_dir, state) which walks all managed_files across:
+
+- services, package roles, users, apt_config, etc_custom, usr_local_custom, extra_paths
+- compare_harvests() compares:
+- existence (added/removed)
+- metadata differences
+- content hash differences by hashing the corresponding artifact file at: `artifacts/<role>/<src_rel>`
+
+#### Important semantic choice:
+
+The file index key is the absolute path. If duplicates appear, the first wins.