docs: ratify Kensa/OpenWatch responsibility boundary#413
Merged
Conversation
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).
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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, andfleet-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
deadman event feed
inventory, liveness loop, drift, fleet rollup, alert routing) on
its own long-lived bus
Three-bucket event taxonomy
TransactionStarted,PhaseCompleted,Committed,RolledBack,DeadmanTimerArmed,DeadmanTimerFiredHeartbeatPulse,DriftDetectedapi.EventKindtype)api.Event/api.EventKindenvelope itselfKensa-side action items recorded (not in this PR)
HeartbeatPulse/DriftDetected/EventFilter.HeartbeatInterval/
EventFilter.FleetIDsfrom Kensa's frozenapi/(before v1.0.0)Reachable(ctx, host)primitive (~mid-Slice B)Kensa.SubscribetoService.SubscribeWhat this enables
liveness loop, drift detector, fleet rollup, alert routing all sit
cleanly inside OpenWatch.
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
filename from their internal references
event-subscription plan is superseded, and a Reference section
points at this doc
boundary from the obsolete §3.4