kover-RFC-001 — Koder Kover: an instrumented comparison cockpit

Status: Draft / exploratory. This RFC records an architecture conversation (2026-05-30). It proposes a new products/dev/ product — Koder Kover — whose purpose is to turn a vague human report ("X is slower / behaves differently than Y") into a reproducible, instrumented A/B capture that the Stack's AI (Kortex / the coding agent) can analyse directly. The protocol and collection layers it needs are ~70% already built under infra/observe/ and specs/ipc/; the novel work is the record/replay mirror mode, the desktop cockpit, and the Kortex handoff. Working name "Kover" — see the naming gate (§9, R-naming).

1. Problem & thesis

1.1 The concrete pain

Some operations are slower in Kruze (products/horizontal/kruze, the Koder desktop browser, CEF-based) than in Google Chrome. Some of that is Kruze's own UI; some is web-page rendering. Today, for the owner to get the AI to diagnose and fix this, they must describe the difference in prose — which is expensive, lossy, and slow. Multiply that across every "feels wrong vs the reference tool" report and it becomes a structural drag on Stack development.

Caveat that frames the Kruze case (from KRUZE-181): Kruze's web engine is Chromium, embedded via CEF in OSR / windowless mode (Chromium paints to a texture that Flutter composites). So a Kruze-vs-Chrome A/B does not compare web engines — it measures the cost of Kruze's Flutter + CEF-OSR shell (the extra copy/composite path that native Chrome lacks). Quantifying and regression-tracking that delta is the goal; a genuinely different engine comparison needs Firefox/Gecko. Kover reuses the KRUZE-181 comparative driver (products/horizontal/kruze, kbench/comparative) for this — see §2.

1.2 The thesis

Kover transforms "describe the bug to the AI" into "hand the AI a reproducible, instrumented A/B capture."

Instead of narrating "Kruze feels slower", the owner runs Kruze and Chrome in mirror, performs the operation once in the primary, and Kover:

1. captures the same input and replays it into the secondary (the similar

   program), so both run the same scenario;

2. instruments both — traces, per-process resource usage, screenvideo

   audio, error/log streams — through a well-specified connector protocol;

3. computes the diff and pipes the whole bundle (two traces + two

   videos + resource graphs + the diff) through the Koder Observability channels to Kortex for analysis.

The AI then receives structured evidence, not a paragraph. That is the whole point — and it generalises far beyond Kruze-vs-Chrome to any "Koder component vs reference program" comparison.

1.3 Non-thesis (what Kover is not)

• Not a new observability backend. infra/observe/ already is that

  (logsmetricstraces, OTLP, self-hosted). Kover is a producer/cockpit on top of it, never a replacement (reuse-first).

• Not a new wire protocol invented from scratch. The connector protocol

  is a profile over specs/ipc/protocol.kmd + the observability instrumentation-contract.kmd (§4).

• Not a general-purpose window manager. Embedding foreign desktop

  windows is explicitly out of the robust path (§7.2, the feasibility cliff) — Kover mirrors them instead.

2. What already exists — the reuse map

Per reuse-first.kmd, the design starts from "what does the Stack already have?". The answer is: most of the plumbing.

Reading: L0–L2 are consume/profile, not build. L3–L5 are the real engineering. This keeps Kover small and prevents it from re-implementing observability — the single biggest design risk for a product in this space.

Existing A/B engine (reuse): products/horizontal/kruze's kbench/comparative (KRUZE-181) already drives Kruze+Chrome over a corpus via CDP with render (FCPLCPFPS) + memory (PSS/RSS per process tree) + CPU metrics. KOVER-003 reuses it as the phase-1 A/B engine rather than building a parallel runner. First run (2026-05-30, idle VM) produced a real Chrome baseline; the Kruze-headless-under-driver path is the open phase-1 blocker (owned by the kruze component).

3. Layer architecture

┌─────────────────────────────────────────────────────────────┐
│ L4  Kover cockpit (Flutter desktop: Linux/macOS/Windows)     │
│     panes: [web via CEF] [terminal] [desktop mirror] + HUD   │
│     layout substrate: Koder Grid                             │
├───────────────┬───────────────┬─────────────────────────────┤
│ L3 record/    │ L3 mirror mode│ L1 per-process resource +   │
│    replay DSL │ (tiered inject)│    perf sampler             │
├───────────────┴───────────────┴─────────────────────────────┤
│ L2 capture (kcap: screen/video/audio) → Kover store          │
├──────────────────────────────────────────────────────────────┤
│ L0 Kover connector protocol  =  profile over                 │
│      specs/ipc/protocol.kmd  +  instrumentation-contract.kmd  │
├──────────────────────────────────────────────────────────────┤
│ L1 collection  =  infra/observe (mon/wire/apm/log/probe), OTLP│
├──────────────────────────────────────────────────────────────┤
│ L5 handoff: bundle (2 traces + 2 videos + resource + diff)   │
│      → Koder Observability channels → Kortex                  │
└──────────────────────────────────────────────────────────────┘

4. L0 — the Kover connector protocol (profile)

Specified normatively in specs/kover/protocol.kmd. Summary of the design decisions this RFC ratifies:

• D-protocol-1 — Profile, don't invent. The connector wire format is

  specs/ipc/protocol.kmd (JSON-RPC 2.0 over the platform transports). Kover adds a method/namespace profile (kover.*) and a payload schema, not a new transport or framing.

• D-protocol-2 — Bidirectional by construction. Active = JSON-RPC

  request/response (Kover pulls info, sends commands). Passive = JSON-RPC notifications (the program pushes unsolicited info). Both directions are the IPC spec's existing patterns.

• D-protocol-3 — Categories of information. The protocol defines a fixed

  taxonomy (error, log, metric, trace, event, resource, input, media-ref) each with a typed schema + required metadata. Telemetry categories (logmetrictrace) reuse the instrumentation-contract.kmd schemas verbatim — Kover does not define a second log schema.

• D-protocol-4 — Error identity reuses the Stack format. The "ERR-…"

  title idea from the proposal is superseded by the existing specs/errors/user-facing-messages.kmd scheme <PRODUCT>-<CATEGORY>-<CODE>-<SEQ> (e.g. KRUZE-UI-503-001). Kover consumes that ID; it does not mint a competing one.

• D-protocol-5 — Native in the SDKs. Koder components get the connector

  for free: the profile is implemented once in engines/sdk/koder_kit (Dart) and engines/sdk/go so every Koder app/daemon is buildable with a Kover connector natively (the proposal's "implement in the libs/SDKs" point). Non-Koder programs implement the public profile to connect, or are observed externally (L1 mon process sampling + L2 capture + OS-input, no connector required).

• D-protocol-6 — First reference consumers. Concrete early adopters that

  validate the profile: Kruze (CEFCDP, the phase-1 AB subject) and Koder Box (infra/net/box, kbox — the OCI container runtime). kbox already emits container stats (CPU% via two-sample cgroup deltas, NetworkIO, streaming JSON); wrapping those as Kover resourcemetric event lets Kover monitor the box and its containers from outside — a clean demonstration of the passive connector over processes Kover did not launch (owner, 2026-05-30). Filed as KOVER-012.

5. L2 — capture & data plane

Specified in specs/kover/capture.kmd. Decisions:

• D-capture-1 — Reuse kcap. Screenvideoaudio capture is

  engines/media/capture, not a new capture stack.

• D-capture-2 — Storage on the object plane, not a bespoke DB. The

  proposal's "own database for media" is refined: metadata/records in the Kover store (kdb), bytes on the object-storage plane (stack-RFC-006, kdb-obj/kdrive). Video in a transactional DB is a physics violation (RFC-006 §1).

• D-capture-3 — Retention is tiered. Raw captures short-lived, derived

  artifacts (diffs, summaries) longer — mirror error-reporting-retention.

• D-capture-4 — Consent + redaction are mandatory, up front. Screen/video

  of a real session will contain PII and credentials. Capture is evidence, not telemetry, so observability-first §8 (no PII in telemetry) is not directly violated — but the L5 handoff to Kortex must pass an explicit consent gate and a redaction pass. This is specified, not deferred.

6. L3 — scenario DSL + mirror mode (the new core)

Specified in specs/kover/scenario-dsl.kmd. The key insight:

Mirror mode and the reproducible-scenario DSL are the same machinery viewed at two times. Both = capture user input → serialise to a typed format → re-execute. The difference is when: live into a second program (mirror) vs later from a file (reproducible scenario).

6.1 Tiered input injection (the viability axis)

Replay reliability depends entirely on how input reaches the target. Design in tiers, and surface the tier to the user (headless-self-check / honest-reporting):

T1 is where the Kruze-vs-Chrome use case lives, and it is the cheap, reliable seed (§10 phase 1). T2 is the long tail; ship it labelled as approximate.

6.2 DSL — reuse, don't greenfield

The scenario DSL is not invented from zero. Two anchors: infra/observe/probe already has a Chromium scenario format, and regression-tests.kmd wants record→golden→replay. Kover's DSL is either a KMD profile or an extension of probe's scenario format, aligned so that a recorded Kover scenario is directly usable as a regression test. That closes a valuable loop: reproduce a bug once → it is a permanent test.

7. L4 — the cockpit UI

Flutter desktop (LinuxmacOSWindows) — matches the dev-product convention (products/dev/grid/engine/desktop is the reference Flutter desktop app). One window, multiple panes, a live telemetry HUD, and a master start/stop-collection toggle (the proposal's switch).

7.1 Panes

• Web pane → reuse Kruze (CEF). Trivial; CDP already exposed via

  --cdp-port.

• Terminal pane → Koder Grid is already a tiling session

  multiplexer with an embedded terminal (xterm/flutter_pty). Use Grid as the layout substrate and terminal host (the proposal's Grid suggestion — endorsed).

• Desktop-program pane → see §7.2.

7.2 The feasibility cliff — mirror, don't embed

Embedding (reparenting) a foreign desktop window cross-platform is painful, and on Wayland it is essentially disallowed (no XEmbed). Decision D-ui-1: Kover does not reparent foreign windows — it mirrors them (capture + input forward), reusing kcap (L2) and the Eye-style mirror pattern. Conveniently this is the same infrastructure as T2 mirror injection (§6.1), so the two hardest requirements collapse into one mechanism.

7.3 Operating modes — cockpit vs ambient daemon (Koder Kodix)

Embedding/mirroring programs into the cockpit is the explicit mode: the operator stages a comparison. There is a second, more powerful mode — the ambient daemon — and it is a Koder Kodix platform capability, not a Kolide-only one (owner, 2026-05-30).

The idea: once the connector protocol (§4) and collection (§2) are wired into Koder Kodix (`infra/linux