Skip to content

docs: ratify Kensa/OpenWatch responsibility boundary#413

Merged
remyluslosius merged 2 commits into
mainfrom
docs/kensa-openwatch-boundary
May 28, 2026
Merged

docs: ratify Kensa/OpenWatch responsibility boundary#413
remyluslosius merged 2 commits into
mainfrom
docs/kensa-openwatch-boundary

Conversation

@remyluslosius
Copy link
Copy Markdown
Contributor

Summary

Records the Kensa/OpenWatch boundary both teams ratified on 2026-05-25.
Supersedes the 2026-04-14 coordination memo's §3.4 only (event
subscription for Heartbeat); the rest of that memo remains
authoritative.

What changed in our understanding

The 2026-04-14 memo planned for OpenWatch to subscribe to a
Kensa-published event stream for HeartbeatPulse, DriftDetected, and
fleet-monitoring concerns. That plan doesn't match what the Kensa API
can actually support: Kensa is one-shot, single-host, stateless
between invocations. Periodic fleet-wide pulses require a long-running
process with an inventory and a scheduler — which is OpenWatch.

The locked boundary

  • Kensa = pure single-host measurement engine + transaction /
    deadman event feed
  • OpenWatch = full orchestration / monitoring plane (scheduler,
    inventory, liveness loop, drift, fleet rollup, alert routing) on
    its own long-lived bus

Three-bucket event taxonomy

Bucket Events Who emits
A TransactionStarted, PhaseCompleted, Committed, RolledBack, DeadmanTimerArmed, DeadmanTimerFired Kensa
B HeartbeatPulse, DriftDetected OpenWatch (using shared api.EventKind type)
C api.Event / api.EventKind envelope itself Stays in Kensa

Kensa-side action items recorded (not in this PR)

  • Remove HeartbeatPulse / DriftDetected / EventFilter.HeartbeatInterval
    / EventFilter.FleetIDs from Kensa's frozen api/ (before v1.0.0)
  • Wire deadman subsystem to publish on the event bus
  • Build Reachable(ctx, host) primitive (~mid-Slice B)
  • Wire Kensa.Subscribe to Service.Subscribe

What this enables

  • Slice B planning can start against a locked boundary. Scheduler,
    liveness loop, drift detector, fleet rollup, alert routing all sit
    cleanly inside OpenWatch.
  • Cross-team scoping conversations have one authoritative reference.

Files

  • docs/KENSA_OPENWATCH_BOUNDARY.md (new, 244 lines, 9 sections)
  • .gitignore (widens existing !docs/KENSA_OPENWATCH_COORDINATION_* to !docs/KENSA_OPENWATCH_* so future boundary/coordination docs land cleanly)

Test plan

  • Both teams (OpenWatch + Kensa) can cite this doc by stable
    filename from their internal references
  • §3.4 of the 2026-04-14 memo can stay in-place; only its
    event-subscription plan is superseded, and a Reference section
    points at this doc
  • Slice B specs can reference this doc instead of re-deriving the
    boundary from the obsolete §3.4

The 2026-04-14 coordination memo's §3.4 planned for OpenWatch to
subscribe to a Kensa-published event stream for HeartbeatPulse,
DriftDetected, and fleet-monitoring concerns. That plan doesn't match
what the Kensa API can actually support: Kensa is one-shot,
single-host, and stateless between invocations; pulses are inherently
periodic and fleet-scoped.

Records the boundary both teams ratified on 2026-05-25:

  Kensa     = pure single-host measurement engine + transaction /
              deadman event feed
  OpenWatch = full orchestration / monitoring plane (scheduler,
              inventory, liveness loop, drift, fleet rollup, alert
              routing) on its own long-lived bus

Three-bucket event taxonomy:

  A) Kensa-emitted, OpenWatch-consumed:
     TransactionStarted, PhaseCompleted, Committed, RolledBack,
     DeadmanTimerArmed, DeadmanTimerFired
     (the last two have a Kensa wiring gap — declared and fired but
     not published to the bus; planned Kensa item)

  B) OpenWatch-owned (emitted by OpenWatch on its own bus):
     HeartbeatPulse, DriftDetected
     (declared in OpenWatch's package against Kensa's api.EventKind
     type — shared wire vocabulary, no dead constants in Kensa)

  C) The shared envelope:
     api.Event + api.EventKind type definitions stay in Kensa

Kensa-side action items recorded (not in this PR):
  - Remove HeartbeatPulse / DriftDetected / EventFilter.HeartbeatInterval
    / EventFilter.FleetIDs from Kensa's frozen api/ (before v1.0.0)
  - Wire deadman subsystem to publish on the event bus
  - Build Reachable(ctx, host) primitive (~mid-Slice B)
  - Wire Kensa.Subscribe to Service.Subscribe

Supersedes the 2026-04-14 memo's §3.4 only; the rest of that memo
remains authoritative. Adds a .gitignore exception so docs/KENSA_OPENWATCH_*
files are tracked (widens the existing COORDINATION_* exception).
@github-actions github-actions Bot added documentation Improvements or additions to documentation size/L labels May 26, 2026
@remyluslosius remyluslosius merged commit fe723ba into main May 28, 2026
21 checks passed
@remyluslosius remyluslosius deleted the docs/kensa-openwatch-boundary branch May 28, 2026 01:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/L

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant