From 1deaf0b2401a0d2d8992938dd0f5f4fd83e272d9 Mon Sep 17 00:00:00 2001 From: vasilito Date: Sun, 12 Jul 2026 01:21:06 +0300 Subject: [PATCH] phase 0: add COLLISION-DETECTION-STATUS.md audit Honest documentation of the actual state of collision detection: - Init-service path collisions: WORKING via lint-config - Package-vs-config runtime collision detection: NOT implemented (no code anywhere emits the [COLLISION-ERROR] markers that validate-collision-log.sh looks for) - Recipe installs manifest: limited utility because no recipe currently declares installs Phase 1 follow-up: implement runtime collision detection in local/sources/installer/src/ to match the broken AGENTS.md promise (already updated in the prior commit). --- local/docs/COLLISION-DETECTION-STATUS.md | 100 +++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 local/docs/COLLISION-DETECTION-STATUS.md diff --git a/local/docs/COLLISION-DETECTION-STATUS.md b/local/docs/COLLISION-DETECTION-STATUS.md new file mode 100644 index 0000000000..6623055560 --- /dev/null +++ b/local/docs/COLLISION-DETECTION-STATUS.md @@ -0,0 +1,100 @@ +# Collision Detection — Status + +**Generated:** 2026-07-12 (Phase 0 fix for G9) +**Status:** init-service path detection WORKS; runtime package-vs-config collision detection is NON-FUNCTIONAL. + +## Background + +The installer fork (`local/sources/installer/`) was originally described in +`local/AGENTS.md` and `AGENTS.md` (root) as including a `CollisionTracker` +module that detects when package staging overwrites config pre-install files +during `install_dir()`. Init-service collisions would always error; other +collisions would warn by default and error in strict mode (`REDBEAR_STRICT_COLLISION=1`). + +## Actual Status (verified 2026-07-12) + +A whole-tree search for "Collision" / "collision" finds **zero matches** in: + +- `src/cook/` (where AGENTS.md said `collision.rs` lived) +- `local/sources/installer/src/` (where it logically would belong today) + +The only collision-related tooling that exists and works is the **static +pre-build lint** at `scripts/lint-config-paths.sh`, which scans +`config/*.toml` `[[files]]` entries and rejects any `path = "/usr/lib/init.d/"` +or `path = "/usr/lib/environment.d/"` line: + +``` +$ bash scripts/lint-config-paths.sh +OK: No init service path violations in config files. +``` + +The companion `scripts/validate-collision-log.sh` exists but is a *post-build log +scanner*: it grep-fails if any cookbook log contains `[COLLISION-ERROR]` or +`[COLLISION-WARN]` markers, but no code anywhere emits those markers, so the +script always returns success in practice. + +`scripts/validate-file-ownership.sh` exists and reads the optional `installs` +field from recipe.toml `[package]` sections to detect overlap, but **no +recipe currently declares `installs`** in the codebase — so the script +effectively runs against an empty set. + +## What This Means Operationally + +- **Init-service path collisions** (`/usr/lib/init.d/` vs `/etc/init.d/`) + ARE detected at lint time via `make lint-config`. +- **Package-vs-config file collisions** for any other path + (e.g. a config `[[files]]` entry writing to `/usr/share/foo` while a + package also stages `/usr/share/foo/bar`) are NOT detected at build time, + install time, or post-build time. They produce a silent last-writer-wins + overwrite that AGENTS.md specifically warns about. + +This is a real regression in the build system's stated guarantees. It exists +because the original `CollisionTracker` was promised but never landed in the +installer fork. + +## Action Plan (Phase 1+) + +1. **Phase 1, immediate**: Stop overpromising collision detection in + `local/AGENTS.md`. Edit the "Collision Detection" section to remove the + claim that `src/cook/collision.rs` exists and that `REDBEAR_STRICT_COLLISION` + is wired. Replace with: "Init-service path collisions are detected at + build-config lint time via `scripts/lint-config-paths.sh`. General + package-vs-config file collisions are not currently detected; treat + config `[[files]]` paths as reviewed-by-hand." + +2. **Phase 1, follow-up** (decision gate): Decide whether to: + - **(a)** Implement runtime collision detection in + `local/sources/installer/src/` (replaces broken promise with working code). + Estimated cost: ~400-600 lines of Rust in the installer fork. + - **(b)** Promote `validate-file-ownership.sh` from optional to required + and require every recipe to declare its `installs`. Estimated cost: + heavy `recipe.toml` annotation across ~2800 recipes. + - **(c)** Accept the gap as known-good for now (current behavior) and + move to Phase 2. + + Recommend **(a)**. It's a one-time fix that matches the contract AGENTS.md + already promises. + +3. **Phase 2**: Wire the chosen implementation into `build-preflight.sh` so + the build refuses to proceed if collisions are detected. + +## Files Touched by This Status Note + +- `local/docs/COLLISION-DETECTION-STATUS.md` — this file +- `local/AGENTS.md` — pending: de-claim the installer's CollisionTracker +- `AGENTS.md` (root) — pending: same edit + +## Related Scripts + +| Script | State | +|--------|-------| +| `scripts/lint-config-paths.sh` | ✅ works; catches init-service + env.d path violations | +| `scripts/validate-collision-log.sh` | ⚠️ empty detection (looks for markers that no code emits) | +| `scripts/validate-file-ownership.sh` | ⚠️ limited utility (no recipes declare `installs`) | +| `scripts/validate-init-services.sh` | (untested this Phase 0) | + +## History + +- 2026-07-12: Status documented (Phase 0 audit by orchestration agent). +- Pre-existing: AGENTS.md claimed `collision.rs` exists in installer; actual + search found zero matches.