ADR-0815 follow-ups: fix the reprovision hint and amend the Address consequence

Open Beginner friendly
  • Is something wrong?
#3,618 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
82/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
backend

Research direction

Start with the authority_ssh_forward_unreported message at src/kdive/services/systems/authority_owned.py (around lines 139-145) and the systems.authorize_ssh_key docstring in src/kdive/mcp/tools/lifecycle/systems/registrar.py. Replace the reprovision sentence with tear-down-and-provision-new wording, keeping the reason and category, then grep the runbooks and tests for the old text. Append a dated ## Amendment to docs/adr/0815-remote-authority-system-ssh-port-is-reported-by-the-authority.md without changing the accepted text. Done when the old wording is gone, any affected test passes, and just lint and the ADR guards pass.

Written by the indexing model from the issue text.

Description

area:providers effort:S priority:P3 risk:night-watch status:ready type:docs

Problem

Two corrections are left over from ADR-0815 (remote authority System SSH port, #3585 / #3594):

  • (a) The authority_ssh_forward_unreported error tells the operator to "Reprovision it against an upgraded authority". An authority-owned System cannot be reprovisioned, so the instruction cannot be followed.
  • (b) ADR-0815's Consequences "Address" bullet says that a wrong instance ssh_addr makes systems.check_ssh_reachable fail with transport_failure. The #3594 live run showed otherwise, and the code agrees. systems.authorize_ssh_key is the call that fails transport_failure. The check_ssh_reachable job succeeds with reachable: false at layer: tcp_connect.

Evidence

  • (a) src/kdive/services/systems/authority_owned.py:139-145: the message for reason authority_ssh_forward_unreported ends "Reprovision it against an upgraded authority."
  • (a) src/kdive/mcp/tools/lifecycle/systems/registrar.py:462-467: the systems.authorize_ssh_key docstring says an authority-owned System "cannot be reprovisioned".
  • (b) docs/adr/0815-remote-authority-system-ssh-port-is-reported-by-the-authority.md:81-83: "a wrong one shows up as systems.check_ssh_reachable failing with transport_failure."
  • (b) src/kdive/jobs/handlers/connectivity/ssh_reachable.py:198-251: check_ssh_reachable_handler raises only for system_not_ready and ssh_not_provisioned. A probe that ran returns a verdict ("A probe that ran — reachable or not — is a success").
  • (b) src/kdive/jobs/handlers/connectivity/ssh_authorize.py:109-174: the authorize path raises ErrorCategory.TRANSPORT_FAILURE when the guest cannot be reached.
  • (b) The runbook already states the observed behaviour: docs/operating/runbooks/live-testing.md:445-450 (PR #3615). The live observation is in docs/workflow/proofs/2026-11-13-remote-authority-ssh-port-3594.md.

Expected

  • (a) The message says to tear the System down and provision a new System against an upgraded authority. Any wrapper docstring that repeats the old instruction is updated to match.
  • (b) ADR-0815 gains an appended amendment that corrects the "Address" consequence. The accepted text stays unchanged.

Proposed approach

  1. Reword the CategorizedError message in authority_owned.py. Keep the reason detail and the category unchanged. Search the MCP tool docstrings and the runbooks for any copy of "Reprovision it against an upgraded authority" and fix each one. Update any test that asserts the old text.
  2. Append an ## Amendment section to ADR-0815, dated and citing #3594 and the proof record. It should state that a wrong ssh_addr (or a closed range) shows as systems.authorize_ssh_key failing transport_failure and systems.check_ssh_reachable succeeding with reachable: false at layer: tcp_connect. Keep the status Accepted. Run just lint and the ADR guards.
Dominant language
Python
Stars
0
Forks
0
Avg merge
9h 13m
Merged PRs (30d)
197

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from randomparity/kdive

All issues in randomparity/kdive

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.