fix: sort mount volumes by specificity to prevent parent mounts hiding children

When git repo mounts and regular file mounts have overlapping target
paths, broader parent mounts hide deeper child mounts because Docker
Compose applies volumes in array order.

- Add sort_volumes_by_specificity() to docker.py:
  - Sorts by target path depth (parent paths first, child paths last)
  - Logs warnings for duplicate targets
  - Handles :bind and :ro suffixes correctly

- Integrate into manifest flow (compile_compose):
  - Sorts manifest mounts + EXTRA_VOLUMES before writing compose

- Integrate into legacy flow (_modify_compose_file):
  - Sorts after appending extra_volumes to existing template volumes

- Add 6 unit tests covering parent/child ordering, stable sort,
  type suffixes, empty list, single volume, and duplicate warnings.

Quality gates: pytest (214 passed, 6 pre-existing), tsc --noEmit (clean)
This commit is contained in:
Alex Blank
2026-05-29 11:35:27 +02:00
parent 787e8844bc
commit 0952aa8217
10 changed files with 378 additions and 2 deletions
@@ -0,0 +1,19 @@
# Proposal: Mount Specificity Ordering
## Problem
When git repo mounts and regular file mounts have overlapping target paths, the broader mount hides the more specific one because Docker Compose applies volumes in array order.
Example: repo → `/workspace/x` (directory) hides file → `/workspace/x/y/config.json`.
## Solution
Sort all volume entries by target path depth before writing the compose file. Parent paths first, child paths last, so deeper mounts overlay correctly.
## Scope
- `manifest_compiler.py``compile_compose()`
- `tool_instances.py``_modify_compose_file()`
- Unit tests for overlap scenarios
## Impact
- Fixes silent mount hiding
- Deterministic ordering
- No user-facing API or schema changes