e290043089
- Adjust install_repos integration test to patch resolve_command_for_repo in the pipeline module and tighten DummyInstaller overrides - Rewrite recursive capability integration tests to focus on layer ordering and capability shadowing across Makefile, Python, Nix and OS-package installers - Extend recursive capabilities markdown with hierarchy diagram, capability matrix, scenario matrix and link to the external setup controller schema https://chatgpt.com/share/69399857-4d84-800f-a636-6bcd1ab5e192
153 lines
6.3 KiB
Markdown
153 lines
6.3 KiB
Markdown
# Capability Resolution & Installer Shadowing
|
||
|
||
This document explains how `pkgmgr` decides **which installer should run** when multiple installation mechanisms are available in a repository.
|
||
It reflects the logic shown in the setup-controller diagram:
|
||
|
||
➡️ **Full graphical schema:** [https://s.veen.world/pkgmgrmp](https://s.veen.world/pkgmgrmp)
|
||
|
||
---
|
||
|
||
## Layer Hierarchy (Strength Order)
|
||
|
||
Installers are evaluated from **strongest to weakest**.
|
||
A stronger layer shadows all layers below it.
|
||
|
||
```
|
||
┌───────────────────────────┐ Highest layer
|
||
│ OS-PACKAGES │ (PKGBUILD / debian / rpm)
|
||
└───────────▲───────────────┘
|
||
│ shadows lower layers
|
||
┌───────────┴───────────────┐
|
||
│ NIX │ (flake.nix)
|
||
└───────────▲───────────────┘
|
||
│ shadows lower layers
|
||
┌───────────┴───────────────┐
|
||
│ PYTHON │ (pyproject.toml)
|
||
└───────────▲───────────────┘
|
||
│ shadows lower layers
|
||
┌───────────┴───────────────┐
|
||
│ MAKEFILE │ (Makefile)
|
||
└────────────────────────────┘ Lowest layer
|
||
```
|
||
|
||
---
|
||
|
||
## Capability Matrix
|
||
|
||
Each layer provides a set of **capabilities**.
|
||
Layers that provide *all* capabilities of a lower layer **shadow** that layer.
|
||
|
||
| Capability | Makefile | Python | Nix | OS-Pkgs |
|
||
| -------------------- | -------- | ------------ | --- | ------- |
|
||
| `make-install` | ✔ | (optional) ✔ | ✔ | ✔ |
|
||
| `python-runtime` | – | ✔ | ✔ | ✔ |
|
||
| `binary/cli` | – | – | ✔ | ✔ |
|
||
| `system-integration` | – | – | – | ✔ |
|
||
|
||
✔ = capability available
|
||
– = not provided by this layer
|
||
|
||
---
|
||
|
||
## Scenario Matrix (Expected Installer Execution)
|
||
|
||
| Scenario | Makefile | Python | Nix | OS-Pkgs | Test Name |
|
||
| -------------------------- | -------- | ------ | --- | ------- | ----------------------------- |
|
||
| 1) Only Makefile | ✔ | – | – | – | `only_makefile` |
|
||
| 2) Python + Makefile | ✔ | ✔ | – | – | `python_and_makefile` |
|
||
| 3) Python shadows Makefile | ✗ | ✔ | – | – | `python_shadows_makefile` |
|
||
| 4) Nix shadows Py & MF | ✗ | ✗ | ✔ | – | `nix_shadows_python_makefile` |
|
||
| 5) OS-Pkgs shadow all | ✗ | ✗ | ✗ | ✔ | `os_packages_shadow_all` |
|
||
|
||
Legend:
|
||
✔ = installer runs
|
||
✗ = installer is skipped (shadowed)
|
||
– = layer not present in this scenario
|
||
|
||
---
|
||
|
||
## What the Integration Test Confirms
|
||
|
||
The integration tests ensure that the **actual execution** matches the theoretical capability model.
|
||
|
||
### 1) Only Makefile
|
||
|
||
* Only `Makefile` present
|
||
→ MakefileInstaller runs.
|
||
|
||
### 2) Python + Makefile
|
||
|
||
* Python provides `python-runtime`
|
||
* Makefile provides `make-install`
|
||
→ Both run (capabilities are disjoint).
|
||
|
||
### 3) Python shadows Makefile
|
||
|
||
* Python additionally advertises `make-install`
|
||
→ MakefileInstaller is skipped.
|
||
|
||
### 4) Nix shadows Python & Makefile
|
||
|
||
* Nix provides: `python-runtime` + `make-install`
|
||
→ PythonInstaller and MakefileInstaller are skipped.
|
||
→ Only NixInstaller runs.
|
||
|
||
### 5) OS-Pkg layer shadows all
|
||
|
||
* OS packages provide all capabilities
|
||
→ Only OS installer runs.
|
||
|
||
---
|
||
|
||
## Capability Processing Flowchart
|
||
|
||
```
|
||
┌────────────────────────────┐
|
||
│ Start │
|
||
└───────────────┬────────────┘
|
||
│
|
||
provided_capabilities = ∅
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────────────┐
|
||
│ For each installer in layer order (low→high) │
|
||
└───────────────────┬──────────────────────────┘
|
||
│
|
||
supports(ctx)?│
|
||
┌─────────┴──────────┐
|
||
│ no │
|
||
│ → skip installer │
|
||
└─────────┬──────────┘
|
||
│ yes
|
||
▼
|
||
caps = detect_capabilities(layer)
|
||
│
|
||
caps ⊆ provided_capabilities ?
|
||
┌─────────────┬─────────────┐
|
||
│ yes │ no │
|
||
│ skip │ run installer│
|
||
└─────────────┴──────────────┘
|
||
│
|
||
▼
|
||
provided_capabilities ∪= caps
|
||
│
|
||
▼
|
||
┌────────────────────────┐
|
||
│ End of installer list │
|
||
└────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Core Principle
|
||
|
||
**A layer is executed only if it contributes at least one capability that no stronger layer has already provided.**
|
||
|
||
---
|
||
|
||
## Link to the Setup Controller Diagram
|
||
|
||
The full visual schema is available here:
|
||
|
||
➡️ **[https://s.veen.world/pkgmgrmp](https://s.veen.world/pkgmgrmp)**
|