Docs: Add ADR for Satellite Lifecycle States

[bupd]

• Closes Satellite Lifecycle States #268

Summary

• Adds ADR-0268 defining four lifecycle states for satellites: pending, online, stale, revoked
• Deletion handled as a separate boolean column, not a lifecycle state
• Documents both normal ZTR and SPIFFE onboarding flows
• Documents revoke/re-enable flow with heartbeat response behavior per state

---

Summary by cubic

Adds ADR-0268 defining four satellite lifecycle states (pending, online, stale, revoked) with deletion as a separate flag. It documents transitions, onboarding (ZTR/SPIFFE), revoke/re-enable behavior, heartbeat responses, and a validation plan to guide implementation.

• New Features
  • Defines states, transitions, and diagrams for lifecycle and onboarding (ZTR + SPIFFE).
  • Details heartbeat responses per state, including 200 + refresh directive when re-enabled.
  • Documents admin actions (revoke/re-enable) and the refresh route for new credentials.
  • Lists required DB schema and API changes and a background stale job, with validation steps.

^{Written for commit 49f3c1d. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation for Harbor Satellite lifecycle model, including state definitions and transitions.
  • Documented onboarding flows, revoke/re-enable operations, HTTP heartbeat behavior, and database schema specifications.
  • Included visual diagrams and UI implementation guidelines.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Introduces a new decision document (ADR 0268) that formally specifies the lifecycle model for Harbor Satellites. Defines four primary states (pending, online, stale, revoked) plus a separate deletion flag, documenting state transitions, validation requirements, onboarding flows, heartbeat responses, and database schema changes needed.

Changes

Cohort / File(s)

Summary

Satellite Lifecycle States Decision Document docs/decisions/0268-satellite-lifecycle-states.md

New ADR defining satellite lifecycle states with pending/online/stale/revoked status enum and deleted boolean flag. Includes state transition model, ZTR onboarding flows (normal and SPIFFE variants), revoke/re-enable flows, heartbeat response behaviors (200 for online/stale/re-enabled, 403 for revoked, 401 for deleted), database schema changes, and implementation checklist spanning 17 action items across database, handlers, endpoints, and UI components.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested labels

documentation

Suggested reviewers

• Vad1mo

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding an Architecture Decision Record (ADR) document for Satellite Lifecycle States, which aligns with the PR's objective of introducing explicit lifecycle states.
Linked Issues check	✅ Passed	The PR fully addresses all coding-related requirements from issue #268, including documenting state transitions, onboarding flows, heartbeat behaviors, and specifying all necessary database schema and API endpoint changes.
Out of Scope Changes check	✅ Passed	The PR only adds a single documentation file (ADR-0268) that is directly scoped to the requirements in issue #268 with no extraneous changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The PR description closely matches the template structure with Closes #268, a Summary section, and Additional context (auto-generated by cubic). All required elements are present and properly filled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codacy-production]

Codacy's Analysis Summary

3 new issues (≤ 0 issue)
0 new security issue

Review Pull Request in Codacy →

✨ AI Reviewer available: add the codacy-review label to get contextual insights without leaving GitHub.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/decisions/0268-satellite-lifecycle-states.md`:
- Around line 217-223: The Markdown table rows for the satellite lifecycle
states (rows containing `online`, `stale`, `revoked`, `pending`, `deleted`) use
compact pipe formatting and must be changed to the spaced pipe style required by
MD060; update each table line so there is a space before and after every pipe
delimiter (e.g., `| online | 200 OK | Normal heartbeat acknowledged |`) and
apply the same spacing fix to the other affected table block referenced (rows
with the same state names further down).
- Around line 79-84: The markdown lists under the "Implementation will be
validated by:" section (and the other similar lists later in the same document)
need blank lines before and after each list to satisfy markdown linting; update
the decision text so there is an empty line above the line "Implementation will
be validated by:"'s bulleted block and an empty line after the final bullet, and
apply the same spacing fix to the two other bulleted blocks referenced (the
later lists around the 97-100 and 111-114 areas) so every list is surrounded by
a blank line.

🧹 Nitpick comments (1)

docs/decisions/0268-satellite-lifecycle-states.md (1)

40-45: Reduce repetitive “Good, because …” phrasing.

LanguageTool flags repeated sentence starters; vary wording for readability.

✍️ Suggested rewording

-* Good, because operators get clear fleet-wide visibility into satellite health.
-* Good, because compromised or decommissioned satellites can be explicitly revoked.
-* Good, because terminology aligns with SPIFFE/PKI conventions used by the project.
-* Good, because soft delete preserves audit trail without complicating the state machine.
-* Good, because distinct HTTP responses (401/403) let the satellite react appropriately per state.
+* Benefit: operators get clear fleet-wide visibility into satellite health.
+* Also enables explicit revocation of compromised or decommissioned satellites.
+* Terminology aligns with SPIFFE/PKI conventions used by the project.
+* Soft delete preserves audit trail without complicating the state machine.
+* Distinct HTTP responses (401/403) let the satellite react appropriately per state.
...
-* Good, because `online` accurately reflects heartbeat-based observation rather than process state.
-* Good, because `revoked` aligns with SPIFFE/PKI terminology (you revoke certificates, you revoke identities).
-* Good, because deletion as a separate boolean keeps the state machine clean.
-* Good, because it maps closely to AWS IoT (PENDING/ACTIVE/INACTIVE/DISABLED).
+* `online` reflects heartbeat-based observation rather than process state.
+* `revoked` aligns with SPIFFE/PKI terminology (you revoke certificates/identities).
+* Deletion as a separate boolean keeps the state machine clean.
+* Maps closely to AWS IoT (PENDING/ACTIVE/INACTIVE/DISABLED).

Also applies to: 54-58

[cubic-dev-ai]

No issues found across 1 file