randomparity / randomparity/kdive
Define the read scope for the Host Interface posture in byo_adopt_facts
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 1h 26m
- Merged PRs (30d)
- 311
Description
Follow-up from #1847 / PR #1890. Raised in adversarial review of ADR-0547.
## Problem
ADR-0547 decides that adopt records the host's Redfish **Host Interface** posture into
`systems.byo_adopt_facts` — whether the host OS can reach its own BMC, and with what
authentication. It does not say **who may read that back**, and neither does ADR-0540, which
claims the column.
The posture is not an ordinary inventory fact. `unauthenticated` is a statement that this physical
machine has an unauthenticated in-band path to its service processor, which is directly useful to
anyone who can get code onto it — and KDIVE's whole purpose is putting operator-supplied kernels
onto it. Whatever surface reflects `byo_adopt_facts` to an agent would be publishing that.
The redaction obligation ADR-0073 covers is the **credential**, and ADR-0547 already handles it
(the recorded fact carries authentication *modes* only; nothing from a `CredentialBootstrapping`
object is read). Read scope on the resulting non-secret fact is a separate question and is
currently unstated.
## Evidence
- `docs/adr/0547-host-interface-in-band-bmc-path.md` — Decision, question 3 (what is recorded);
the ADR-0073 note bounds what is read, not who may read it back.
- `docs/adr/0540-adopt-only-provisioning.md` — claims `systems.byo_adopt_facts jsonb` as "where
adopt records what it established"; no read-scope statement.
- The neighbouring surface division is already non-obvious and documented in
`docs/design/m4-byo-host.md`: neither `resources.list` nor `resources.describe` emits the
`cordoned` flag; only `resources.availability` does. So "which tool would surface an adopt fact,
if any" needs answering rather than assuming.
- `src/kdive/mcp/tools/catalog/_resource_envelopes.py` emits a fixed key set, so a namespaced key
routed through it would be dropped silently — the failure mode here is a fact that is neither
deliberately exposed nor deliberately withheld.
## Expected outcome
- A stated read scope for the Host Interface posture in `byo_adopt_facts`: which tool (if any)
surfaces it, and to which role. The plausible answer is operator-only — the same platform-role
gate `ops/` tools sit behind — with nothing on the agent-facing catalog surface, but it should
be decided rather than inherited.
- Whichever way it goes, a test that pins it, so the fact cannot start appearing in an envelope
through an unrelated change.
- If any agent-facing surface does carry it, the wrapper docstring and `Field` text state what it
means, per this repo's MCP surface rules.
Scope note: this is a read-scope decision on a fact #1823 writes. Sized to one PR alongside that
entry, or immediately after it.
Blocked by #1823
Contributor guide
Research direction
Start with docs/adr/0547-host-interface-in-band-bmc-path.md and docs/adr/0540-adopt-only-provisioning.md, then inspect docs/design/m4-byo-host.md and src/kdive/mcp/tools/catalog/_resource_envelopes.py. Trace the relevant MCP surfaces and existing role gates before deciding the read scope. Done means the scope is documented, a test pins exposure or withholding, and any agent-facing wrapper text is updated if needed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- authorization, backend, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100