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).
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user