From 81e29bf75ae85ba9dd537189a937f4994ae540eb Mon Sep 17 00:00:00 2001 From: Miguel Jacq Date: Sat, 27 Dec 2025 20:39:12 -0600 Subject: [PATCH] Update Technical_Decomp_Diff --- Technical_Decomp_Diff.md | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/Technical_Decomp_Diff.md b/Technical_Decomp_Diff.md index ebb8989..8f538fa 100644 --- a/Technical_Decomp_Diff.md +++ b/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”. \ No newline at end of file +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//` + +#### Important semantic choice: + +The file index key is the absolute path. If duplicates appear, the first wins. \ No newline at end of file