KSP-MissionControl/deliverable-audit.md

# Audit: 15 fix commits on `debug-krpc-handshake`

**Branch:** `debug-krpc-handshake` (15 commits ahead of `main`)
**Branch tip:** `fc76635` — `chore: remove stray commit msg scratch file`
**Author of all commits:** Mavis (Mavis@local), 2026-06-02 to 2026-06-03
**Reviewer:** KSP-MC Bridge (`bridge-expert`), 2026-06-03

The branch was created to chase a single high-level failure: real KSP
talks to the bridge and the bridge's `client.connect()` throws
`TypeError: Cannot read properties of null (reading 'code')` somewhere
during the RPC handshake, stream handshake, or `KRPC.GetServices()`
decode. Every commit claims to fix one slice of that. Each row below is
the reviewer's call.

## Summary

- **CORRECT: 8** — the fix is real, holds up under inspection, and has (or should
  have) a regression test.
- **GUESS: 5** — debug instrumentation, safety-net try/catch, or commit msg
  cleanup. No test, but no harm — they don't change production code paths.
- **REGRESSION_RISK: 1** — `639d265` "decode error bytes as Error protobuf". It
  is **wrong** in its assumption (kRPC's `Response.error` is a sub-message
  per the .proto, not `bytes`); it is fully reverted by `1d5b6a9`, which
  is the correct fix. Net effect: dropping `639d265` and keeping
  `1d5b6a9` gives the same final state, with one fewer broken commit in
  the history.
- **DROP: 1** — `fc76635` "remove stray commit msg scratch file" is a
  chore on top of the chain, not a real fix. It will be replaced by a
  clean squashed/rebased history on `feature/krpc-handshake-final`.

The 3 nested-enum fixes (`dea84b6` for `ConnectionResponse.status`,
`b1b78a0` for `Type.code`, `2b0573d` for `Procedure.game_scenes`) are
all real, but they were each applied **without a test that exercises
the exact wire bytes kRPC sends**. The mock-server harness in
`packages/krpc-client/tests/_mock-server.ts` (added in this branch)
provides that coverage going forward, but those three commits should
not be claimed to be "fixed" without it.

## Detailed audit

| # | Commit | Title | Class | Why | Notes / risk |
|---|---|---|---|---|---|
| 1 | `c4b631c` | fix: add BUILD_TAG to bridge so we can verify which code is running | **CORRECT** | Real, simple, useful: lets the human confirm which binary is running by grepping `[v2-debug]` in the log. | No code-path change. The hardened fatal catch is a small but correct defensive addition. |
| 2 | `7c46bc0` | fix: remove stray brace in config log | **CORRECT** | Stray `}` in a log template. Log readability bug. | No risk. |
| 3 | `25dd425` | fix: wrap stream handshake decode in try/catch + raw-bytes diagnostic | **CORRECT** | The original `connect()` only wrapped the **RPC** handshake decode. The actual failure was on the stream port, and the error bubbled up unannotated. Wrapping both + dumping raw bytes behind `KRPC_DEBUG=1` is correct. | Adds noise to `client.ts` (the `KRPC_DEBUG` env var). Acceptable — gated. |
| 4 | `dea84b6` | fix: use uint32 instead of nested-enum type for `ConnectionResponse.status` | **CORRECT** | Real protobufjs 7.x bug: nested-enum field default-value lookup throws "Cannot read properties of null (reading 'code')" when the server omits the field. Status is wire-varint; modeling as `uint32` is a clean fix. The same commit also fixes `ProcedureResult.error` to use `'Error'` (a real sub-message, not a nested-enum type) — also correct. | The hex dump in the commit message (`1a 10 <16 bytes>` = field 3, wire type 2) is a real `clientIdentifier`-only payload, matching what the kRPC server emits. |
| 5 | `a6ba6e6` | fix: top-level try/catch around `connect()` with stack trace | **GUESS** | A blanket safety net added because the previous fix "didn't work". The real cause (next commit, `b1b78a0`) was a different nested-enum on `Type.code`, not a missing try/catch. The net-net effect is harmless but the safety net is still useful for future failures. | Adds a `try { return this._connectImpl(); } catch` wrapper in `connect()`. The "kRPC connect failed at unknown step" message is the only diagnostic gain. Not harmful but not the real fix either. |
| 6 | `b1b78a0` | fix: `Type.code` nested-enum bug blocks GetServices decode | **CORRECT** | Same nested-enum class of bug as `dea84b6`, but for `KRPC.Type.code` which is hit on every `GetServices()` decode (every procedure has a `returnType`). Without this, the bridge can't build a `ServiceCache`. Also wraps `loadServices` errors with a clear prefix. | Real. Pair with `dea84b6` and `2b0573d` — same root cause (protobufjs 7.x nested-enum default-value lookup), three distinct fields. |
| 7 | `2b0573d` | fix: add missing `Procedure.game_scenes` field (field 6, repeated `GameScene` enum) | **CORRECT** | The kRPC server's `Procedure` message has 6 fields; we had 5. Field 6 is `game_scenes` (a repeated enum, also nested). Schema gap — real bug. | Same nested-enum workaround. Without this, protobufjs's strict field validator rejects every `Procedure` in the response. |
| 8 | `62e7ed0` | fix: handle null returnType in `decodeKrpcType` (the actual root cause!) | **CORRECT** | The *real* root cause, named in the commit message: protobufjs decodes missing `returnType` (which the kRPC server omits for setters / void procs) as `null`, and our `decodeKrpcType` did `null.code`. Has a regression test in `services.test.ts` (the `AddStream` case). | The commit message is honest that the prior protobufjs fixes were "real and needed" but not the cause of *this particular* failure mode. Good engineering. |
| 9 | `916222f` | debug: log SpaceCenter procedure names during ServiceCache build | **GUESS** | Pure diagnostic; gated on `KRPC_DEBUG`. Useful when chasing the "GetUT not found" symptom, but doesn't change behavior. | Keep behind env var. |
| 10 | `ee75d0b` | debug: probe specifically for GetUT in SpaceCenter | **GUESS** | Same: a more targeted diagnostic log. Helps confirm that the lookup-by-name mismatch is the issue (it was — see #11). | Keep behind env var. |
| 11 | `e9ebbf1` | fix: translate PascalCase procedure names to .NET getter/setter convention | **CORRECT** | Real, well-tested fix. The kRPC server (a C# app) exposes properties as `get_UT` / `set_UT` / `CelestialBody.get_Name`. Our `extract.ts` writes the friendlier `GetUT` / `CelestialBody.GetName`. Without this translation the cache always returned "procedure not found". Has a regression test in `services.test.ts` ("falls back to .NET-style getter/setter naming for C# properties"). | Important behavioral change. Anyone else calling the cache with raw `.NET` names still works (exact-match tried first). |
| 12 | `639d265` | fix: decode error bytes as Error protobuf (not as a pre-decoded object) | **REGRESSION_RISK** | **Wrong.** Assumes `Response.error` / `ProcedureResult.error` are `bytes` (serialized sub-messages) and double-decodes. The kRPC .proto defines them as `type: 'Error'` (embedded sub-message) — protobufjs already decodes them to a nested object. This commit changes the TypeScript shape from `{ service, name, description }` to `Uint8Array` and adds a redundant `decodeMessage(KRPC.Error, …)` step. The double-decode silently corrupts error reporting and probably also pollutes the `value` field (depends on protobufjs's tolerance). | **Drop on carry-forward.** Fully reverted by `1d5b6a9`. |
| 13 | `273dcd1` | debug: log raw response bytes for failed RPC calls | **GUESS** | Diagnostic only. Logs the full response hex for every procedure call when `KRPC_DEBUG=1`. Useful for chasing silent wire-format issues. | Redundant in spirit with `25dd425` (which logs the handshake). Keep as a single, well-known diagnostic switch. |
| 14 | `1d5b6a9` | fix: use sub-message decoding for Error fields (not raw bytes) | **CORRECT** | The actual correct fix for the error-decoding class of bug. The schema already says `type: 'Error'`, so protobufjs decodes to a nested object automatically — no second decode needed. Reverts `639d265`'s wrong assumption. | Honest commit message: "we were treating response.error as if it were a Uint8Array of raw bytes (matching the wrong type annotation we had earlier)". |
| 15 | `fc76635` | chore: remove stray commit msg scratch file | **DROP** | A `.commit_msg.txt` file accidentally committed by `1d5b6a9` (it was in the diff for that commit, which I see in the history). Removing it is right, but the commit is a chore. | Will not be cherry-picked — the squashed history on `feature/krpc-handshake-final` will start clean. |

## Net carries

- **Carry forward (8 + the 3 "real" GUESS-as-debug commits kept behind env var):**
  `c4b631c`, `7c46bc0`, `25dd425`, `dea84b6`, `a6ba6e6`, `b1b78a0`,
  `2b0573d`, `62e7ed0`, `e9ebbf1`, `1d5b6a9`, plus the env-gated debug
  logs `916222f`, `ee75d0b`, `273dcd1`.
- **Drop:** `639d265` (revert-by-replacement by `1d5b6a9`), `fc76635`
  (chore, replaced by clean squashed history).
- **Add (new in this branch):** the mock kRPC server
  (`packages/krpc-client/src/_mock-server.ts` and
  `apps/tools/ksp-bridge/tests/mock-server.test.ts`) and the regression
  tests that exercise the four bug classes above without needing a real
  KSP install. See `deliverable.md` for the full list.

## What this audit does *not* prove

The 3 nested-enum fixes (`dea84b6`, `b1b78a0`, `2b0573d`) and the
`null returnType` fix (`62e7ed0`) all depend on assumptions about the
exact bytes the real kRPC server sends. None of the 15 commits is
backed by a test that connects to a real kRPC server (because no
test environment has KSP installed — that's the human-verification
gate in the task). The mock server I add in step 2 *does* encode the
real wire bytes the kRPC server is documented to send (per
`krpc.github.io/krpc` and the Python reference client), so the
decoder logic can now be tested without KSP. Real KSP verification
remains a manual step the human must run.