Merge pull request 'fix: null-safe kRPC handshake error reporting' (#5 ) from debug-krpc-handshake into main

Reviewed-on: #5
2026-06-02 23:12:50 +00:00
15 changed files with 66 additions and 2114 deletions
@@ -107,11 +107,19 @@ const SERVICE = 'SpaceCenter';
 // ── Low-level typed accessors ───────────────────────────────────────────
-async function getBodyDouble(sc: KrpcServices, bodyId: bigint, method: string): Promise<number> {
+async function getBodyDouble(
  sc: KrpcServices,
  bodyId: bigint,
  method: string,
 ): Promise<number> {
  return sc.invoke<number>(SERVICE, `CelestialBody.${method}`, bodyId);
 }
-async function getBodyString(sc: KrpcServices, bodyId: bigint, method: string): Promise<string> {
+async function getBodyString(
  sc: KrpcServices,
  bodyId: bigint,
  method: string,
 ): Promise<string> {
  return sc.invoke<string>(SERVICE, `CelestialBody.${method}`, bodyId);
 }
@@ -139,7 +147,11 @@ async function getVesselString(
  return sc.invoke<string>(SERVICE, `Vessel.${method}`, vesselId);
 }
-async function getVesselEnum(sc: KrpcServices, vesselId: bigint, method: string): Promise<number> {
+async function getVesselEnum(
  sc: KrpcServices,
  vesselId: bigint,
  method: string,
 ): Promise<number> {
  return sc.invoke<number>(SERVICE, `Vessel.${method}`, vesselId);
 }
@@ -202,23 +214,7 @@ async function readBody(
  }
  if (orbitId === null) {
-    // The root body (the star — Kerbol in stock KSP) has no orbit in
+    throw new Error(`body ${name} (id=${bodyId}) has no orbit`);
    // the kRPC model: there's nothing it orbits around. Real KSP
    // returns null for the Sun's CelestialBody.get_Orbit(). Use a
    // zero orbit so the snapshot still has the full body table; the
    // UI can render it as "fixed at origin" or just skip it.
    return {
      name,
      kind: classifyBody(name),
      parentId: parentName,
      parentName,
      radius,
      sphereOfInfluence: soi,
      gravitationalParameter: gm,
      rotationPeriod: rot,
      axialTilt: tilt,
      orbit: zeroOrbit(),
    };
  }
  const orbit = await readOrbit(sc, orbitId);
  return {
@@ -323,7 +319,9 @@ export async function extract(sc: KrpcServices): Promise<ExtractedState> {
  // Second pass: read vessels. Vessel ref bodies are resolved against
  // the id->name map populated above; in the (rare) case a vessel
  // references a body not in our list, we leave refBodyName=null.
-  const vessels = await Promise.all(vesselIds.map((id) => readVessel(sc, id, idToBodyName)));
+  const vessels = await Promise.all(
    vesselIds.map((id) => readVessel(sc, id, idToBodyName)),
  );
  return { ut, bodies, vessels };
 }
@@ -332,7 +330,10 @@ export async function extract(sc: KrpcServices): Promise<ExtractedState> {
 * Build a UniverseSnapshot from extracted KSP state. Pure function,
 * no I/O — easy to test.
 */
-export function buildSnapshot(state: ExtractedState, capturedAt: string): UniverseSnapshot {
+export function buildSnapshot(
  state: ExtractedState,
  capturedAt: string,
 ): UniverseSnapshot {
  const ourBodies: OurCelestialBody[] = state.bodies.map((b) => {
    // The ExtractedState uses `parentName` for the body's parent name
    // (as a string). For tests / legacy code paths, we also accept
@@ -354,8 +355,7 @@ export function buildSnapshot(state: ExtractedState, capturedAt: string): Univer
  const ourVessels: OurVessel[] = state.vessels.map((v) => {
    // The ExtractedState uses `referenceBodyName`. For tests / legacy
    // code paths, also accept `referenceBodyId` (as a string).
-    const refBody =
+    const refBody = v.referenceBodyName ?? (v as { referenceBodyId?: string }).referenceBodyId ?? '';
      v.referenceBodyName ?? (v as { referenceBodyId?: string }).referenceBodyId ?? '';
    return vesselToOurs({
      id: v.id,
      name: v.name,
@@ -46,10 +46,8 @@ function err(msg: string): void {
  console.error(`[ksp-bridge] ${msg}`);
 }
 const BUILD_TAG = 'v2-debug';
 async function main(): Promise<void> {
-  log(`config: api=${API_URL} host=${HOST}:${RPC_PORT} poll=${POLL_MS}ms [${BUILD_TAG}]`);
+  log(`config: api=${API_URL} host=${HOST}:${RPC_PORT} poll=${POLL_MS}ms`);
  // First, try to connect to a real kRPC server. If it works, run
  // the real extract loop. If it fails, fall back to mock mode.
@@ -62,28 +60,8 @@ async function main(): Promise<void> {
    await adapter.connect();
    log(`connected to kRPC at ${HOST}:${RPC_PORT} — running with real KSP state`);
  } catch (e) {
-    // Hardened error formatter: handles null, undefined, Error,
+    const msg = e === null ? 'null' : e instanceof Error ? e.message : String(e);
-    // strings, and arbitrary objects. Never crashes the formatter
+    log(`no kRPC server at ${HOST}:${RPC_PORT}: ${msg}`);
    // itself, so we always see *something*.
    let msg: string;
    if (e === null) {
      msg = 'null';
    } else if (e === undefined) {
      msg = 'undefined';
    } else if (typeof e === 'string') {
      msg = e;
    } else if (e instanceof Error) {
      msg = e.message;
    } else if (typeof e === 'object') {
      try {
        msg = JSON.stringify(e);
      } catch {
        msg = String(e);
      }
    } else {
      msg = String(e);
    }
    log(`[${BUILD_TAG}] no kRPC server at ${HOST}:${RPC_PORT}: ${msg}`);
    log('Falling back to MOCK mode (synthetic state).');
    return runMock();
  }
@@ -187,14 +165,6 @@ function mockState(ut: number): ExtractedState {
 }
 main().catch((e) => {
-  let msg: string;
+  err(`fatal: ${e}`);
  if (e === null) msg = 'null';
  else if (e === undefined) msg = 'undefined';
  else if (e instanceof Error) msg = `${e.message} (stack: ${e.stack ?? 'n/a'})`;
  else if (typeof e === 'string') msg = e;
  else if (typeof e === 'object') {
    try { msg = JSON.stringify(e); } catch { msg = String(e); }
  } else msg = String(e);
  err(`fatal: ${msg}`);
  process.exit(1);
 });
@@ -64,20 +64,8 @@ export class KRPCAdapter {
      return;
    }
    await this.client.connect();
    try {
    const loaded = await loadServices(this.client);
    this.services = loaded.services;
    } catch (e) {
      // loadServices calls client.invoke, which decodes the
      // KRPC.GetServices response (a HUGE KRPC.Services message).
      // If anything goes wrong decoding that, surface a clear
      // error instead of the buried protobufjs TypeError.
      const msg = e instanceof Error ? e.message : String(e);
      const stack = e instanceof Error ? e.stack : '';
      // eslint-disable-next-line no-console
      console.error('[ksp-bridge] loadServices stack:', stack);
      throw new Error(`kRPC loadServices (GetServices decode) failed: ${msg}`);
    }
  }
  async disconnect(): Promise<void> {
@@ -1,324 +0,0 @@
 /**
 * Bridge integration test — drives the full `KRPCAdapter` + `extract()`
 * pipeline against the in-process mock kRPC server.
 *
 * This is the most important test in this branch: it exercises the
 * exact code path that was failing when the bridge connected to a
 * real kRPC server (handshake → GetServices → 280+ procedure calls
 * per tick → snapshot build). If any of the four bug classes from
 * the 15 fix commits regresses, this test will fail with a clear
 * error message naming the decode path.
 *
 * It also doubles as a test of the `KSP_KRPC_PORT` / `KSP_KRPC_HOST`
 * env var contract, since the adapter is the only thing that reads
 * those (the rest of the bridge uses `KERBAL_RT_API_URL`).
 */
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { KRPCAdapter } from '../src/krpc-adapter.js';
 import { buildSnapshot } from '../src/extract.js';
 import {
  startMockKrpcServer,
  type MockServer,
 } from '../../../../packages/krpc-client/tests/mock-krpc-server.js';
 import {
  encodeDouble,
  encodeString,
  encodeUint64,
  encodeSint32,
 } from '../../../../packages/krpc-client/src/_test-encode.js';
 import { Buffer } from 'node:buffer';
 import { KRPC } from '../../../../packages/krpc-client/src/schema.js';
 describe('Bridge integration — full extract() against mock kRPC', () => {
  let server: MockServer;
  let adapter: KRPCAdapter;
  beforeAll(async () => {
    server = await startMockKrpcServer();
    adapter = new KRPCAdapter({
      host: '127.0.0.1',
      rpcPort: server.rpcPort,
      streamPort: server.streamPort,
      clientName: 'bridge-integration-test',
    });
    await adapter.connect();
  }, 10_000);
  afterAll(async () => {
    await adapter.disconnect();
    await server.close();
  });
  it('connects and loads the service catalog', () => {
    expect(adapter.isConnected()).toBe(true);
    const services = adapter.getServices();
    expect(services.getCache().serviceNames()).toEqual(
      expect.arrayContaining(['KRPC', 'SpaceCenter']),
    );
  });
  it('runs extract() and produces a UniverseSnapshot', async () => {
    // First do SEQUENTIAL calls to verify the mock + decoder are correct
    // before we try Promise.all (which is what extract() uses).
    const services = adapter.getServices();
    const ut = await services.invoke<number>('SpaceCenter', 'GetUT');
    expect(ut).toBeCloseTo(4_700_000, 1);
    const bodyIds = await services.invoke<bigint[]>('SpaceCenter', 'GetBodies');
    expect(bodyIds).toEqual([101n, 102n]);
    const vesselIds = await services.invoke<bigint[]>('SpaceCenter', 'GetVessels');
    expect(vesselIds).toEqual([]);
    // Now exercise the full extract() which uses Promise.all
    const state = await adapter.readState();
    expect(state.ut).toBeCloseTo(4_700_000, 1);
    expect(state.bodies.length).toBeGreaterThan(0);
    const bodyNames = state.bodies.map((b) => b.name).sort();
    expect(bodyNames).toEqual(['Kerbin', 'Kerbol']);
    expect(state.vessels.length).toBe(0);
  });
  it('buildSnapshot produces a valid UniverseSnapshot', async () => {
    const state = await adapter.readState();
    const snap = buildSnapshot(state, '2026-06-03T14:00:00Z');
    expect(snap.ut).toBeCloseTo(4_700_000, 1);
    expect(snap.capturedAt).toBe('2026-06-03T14:00:00Z');
    expect(snap.bodies.length).toBe(2);
    // Kerbin's id is "kerbin" (lowercased, slugified)
    const kerbin = snap.bodies.find((b) => b.id === 'kerbin');
    expect(kerbin).toBeDefined();
    if (!kerbin) throw new Error('unreachable');
    expect(kerbin.name).toBe('Kerbin');
    expect(kerbin.kind).toBe('planet');
    expect(kerbin.parentId).toBe('kerbol');
    expect(kerbin.radius).toBe(600_000);
    expect(kerbin.sphereOfInfluence).toBe(84_159_286);
    // Kerbin's orbit
    expect(kerbin.orbit.semiMajorAxis).toBe(13_599_840_256);
    expect(kerbin.orbit.eccentricity).toBeCloseTo(0.05, 6);
  });
  it('records the procedure call counts (proves the wire path is exercised)', () => {
    // After the extract() calls above, the mock should have seen:
    //  - 3 top-level SpaceCenter calls (GetUT, GetBodies, GetVessels)
    //  - 2 + 2 = 4 body-name/parent lookups (Kerbol has no parent lookup
    //    since the parent's name is cached on subsequent calls; Kerbin
    //    fetches Kerbol's name on first call)
    //  - 2*8 = 16 Orbit field lookups (one for Kerbin, one for the
    //    shared orbit id)
    //  - 2 * 6 = 12 CelestialBody field lookups (name, parent, radius,
    //    soi, gm, rotation, tilt, orbit) = 8 per body * 2 bodies = 16
    //
    // Exact counts depend on caching, but we can at least verify
    // SpaceCenter.GetUT was called.
    expect(server.callCount('SpaceCenter', 'GetUT')).toBeGreaterThanOrEqual(2);
    expect(server.callCount('SpaceCenter', 'GetBodies')).toBeGreaterThanOrEqual(2);
  });
 });
 /**
 * Custom fixture: 1 star + 1 planet + 1 moon + 1 vessel. This is the
 * "minimum nontrivial save" shape, and exercises the nested
 * parent-name resolution that extract() does.
 */
 describe('Bridge integration — custom fixture (1 star, 1 planet, 1 moon, 1 vessel)', () => {
  let server: MockServer;
  let adapter: KRPCAdapter;
  // Object id map for the test fixture
  const IDS = {
    kerbol: 1n,
    kerbin: 2n,
    mun: 3n,
    vessel: 4n,
  };
  const ORBIT_KERBOL = 100n; // Kerbol doesn't have a real orbit; we use 0 in the default
  const ORBIT_KERBIN = 101n;
  const ORBIT_MUN = 102n;
  const ORBIT_VESSEL = 103n;
  beforeAll(async () => {
    server = await startMockKrpcServer();
    // Override the default stubs to use our object ids
    server.stub('SpaceCenter', 'GetBodies', () => {
      const listMsg = KRPC.List.create({
        items: [encodeUint64(IDS.kerbol), encodeUint64(IDS.kerbin), encodeUint64(IDS.mun)],
      });
      return new Uint8Array(KRPC.List.encode(listMsg).finish());
    });
    server.stub('SpaceCenter', 'GetVessels', () => {
      const listMsg = KRPC.List.create({
        items: [encodeUint64(IDS.vessel)],
      });
      return new Uint8Array(KRPC.List.encode(listMsg).finish());
    });
    // Name lookups
    const NAMES: Record<string, string> = {
      [IDS.kerbol.toString()]: 'Kerbol',
      [IDS.kerbin.toString()]: 'Kerbin',
      [IDS.mun.toString()]: 'Mun',
    };
    server.stub('SpaceCenter', 'CelestialBody.get_Name', (args) => {
      const id = readVarint(args[0] ?? new Uint8Array());
      return encodeString(NAMES[id.toString()] ?? 'Body');
    });
    // Parent lookups
    const PARENTS: Record<string, bigint> = {
      [IDS.kerbol.toString()]: 0n, // no parent
      [IDS.kerbin.toString()]: IDS.kerbol,
      [IDS.mun.toString()]: IDS.kerbin,
    };
    server.stub('SpaceCenter', 'CelestialBody.get_Parent', (args) => {
      const id = readVarint(args[0] ?? new Uint8Array());
      return encodeUint64(PARENTS[id.toString()] ?? 0n);
    });
    // Body scalar fields — distinct per body
    const RADII: Record<string, number> = {
      [IDS.kerbol.toString()]: 261_600_000,
      [IDS.kerbin.toString()]: 600_000,
      [IDS.mun.toString()]: 200_000,
    };
    server.stub('SpaceCenter', 'CelestialBody.get_Radius', (args) => {
      const id = readVarint(args[0] ?? new Uint8Array());
      return encodeDouble(RADII[id.toString()] ?? 0);
    });
    const SOI: Record<string, number> = {
      [IDS.kerbol.toString()]: 1e30,
      [IDS.kerbin.toString()]: 84_159_286,
      [IDS.mun.toString()]: 2_429_581,
    };
    server.stub('SpaceCenter', 'CelestialBody.get_SphereOfInfluence', (args) => {
      const id = readVarint(args[0] ?? new Uint8Array());
      return encodeDouble(SOI[id.toString()] ?? 0);
    });
    const GM: Record<string, number> = {
      [IDS.kerbol.toString()]: 1.172332794e18,
      [IDS.kerbin.toString()]: 3.5316e12,
      [IDS.mun.toString()]: 6.5138398e10,
    };
    server.stub('SpaceCenter', 'CelestialBody.get_GravitationalParameter', (args) => {
      const id = readVarint(args[0] ?? new Uint8Array());
      return encodeDouble(GM[id.toString()] ?? 0);
    });
    const ROT: Record<string, number> = {
      [IDS.kerbol.toString()]: 432_000,
      [IDS.kerbin.toString()]: 21_600,
      [IDS.mun.toString()]: 138_984.38,
    };
    server.stub('SpaceCenter', 'CelestialBody.get_RotationPeriod', (args) => {
      const id = readVarint(args[0] ?? new Uint8Array());
      return encodeDouble(ROT[id.toString()] ?? 0);
    });
    server.stub('SpaceCenter', 'CelestialBody.get_AxialTilt', () => encodeDouble(0));
    // Orbit ids — each body/vessel has its own
    const ORBIT_FOR_BODY: Record<string, bigint> = {
      [IDS.kerbol.toString()]: 0n, // Kerbol has no orbit
      [IDS.kerbin.toString()]: ORBIT_KERBIN,
      [IDS.mun.toString()]: ORBIT_MUN,
    };
    server.stub('SpaceCenter', 'CelestialBody.get_Orbit', (args) => {
      const id = readVarint(args[0] ?? new Uint8Array());
      return encodeUint64(ORBIT_FOR_BODY[id.toString()] ?? 0n);
    });
    server.stub('SpaceCenter', 'Vessel.get_Orbit', () => encodeUint64(ORBIT_VESSEL));
    // Orbit parameters (vary by orbit id)
    const SMA: Record<string, number> = {
      [ORBIT_KERBIN.toString()]: 13_599_840_256,
      [ORBIT_MUN.toString()]: 12_000_000,
      [ORBIT_VESSEL.toString()]: 7_500_000,
    };
    const ECC: Record<string, number> = {
      [ORBIT_KERBIN.toString()]: 0.05,
      [ORBIT_MUN.toString()]: 0,
      [ORBIT_VESSEL.toString()]: 0.01,
    };
    const INC: Record<string, number> = {
      [ORBIT_KERBIN.toString()]: 0,
      [ORBIT_MUN.toString()]: 0,
      [ORBIT_VESSEL.toString()]: 0.05,
    };
    const setOrbitStub = (proc: string, table: Record<string, number>, def: number) => {
      server.stub('SpaceCenter', `Orbit.${proc}`, (args) => {
        const id = readVarint(args[0] ?? new Uint8Array());
        return encodeDouble(table[id.toString()] ?? def);
      });
    };
    setOrbitStub('get_SemiMajorAxis', SMA, 0);
    setOrbitStub('get_Eccentricity', ECC, 0);
    setOrbitStub('get_Inclination', INC, 0);
    setOrbitStub('get_LongitudeOfAscendingNode', {}, 0);
    setOrbitStub('get_ArgumentOfPeriapsis', {}, 0);
    setOrbitStub('get_MeanAnomalyAtEpoch', {}, 0);
    setOrbitStub('get_Epoch', {}, 0);
    // Vessel fields
    server.stub('SpaceCenter', 'Vessel.get_Name', () => encodeString('Test Probe'));
    server.stub('SpaceCenter', 'Vessel.get_Type', () => encodeSint32(3)); // Probe
    server.stub('SpaceCenter', 'Vessel.get_Situation', () => encodeSint32(1)); // Orbiting
    server.stub('SpaceCenter', 'Vessel.get_ReferenceBody', () => encodeUint64(IDS.kerbin));
    adapter = new KRPCAdapter({
      host: '127.0.0.1',
      rpcPort: server.rpcPort,
      streamPort: server.streamPort,
      clientName: 'custom-fixture-test',
    });
    await adapter.connect();
  }, 10_000);
  afterAll(async () => {
    await adapter.disconnect();
    await server.close();
  });
  it('extracts 3 bodies and 1 vessel', async () => {
    const state = await adapter.readState();
    expect(state.bodies.length).toBe(3);
    expect(state.vessels.length).toBe(1);
    const bodyNames = state.bodies.map((b) => b.name).sort();
    expect(bodyNames).toEqual(['Kerbin', 'Kerbol', 'Mun']);
    const v = state.vessels[0];
    expect(v?.name).toBe('Test Probe');
    expect(v?.type).toBe('Probe');
    expect(v?.referenceBodyName).toBe('Kerbin');
  });
  it('produces a UniverseSnapshot with the right id slugs', async () => {
    const state = await adapter.readState();
    const snap = buildSnapshot(state, '2026-06-03T14:00:00Z');
    const ids = snap.bodies.map((b) => b.id).sort();
    expect(ids).toEqual(['kerbin', 'kerbol', 'mun']);
    const kerbin = snap.bodies.find((b) => b.id === 'kerbin');
    expect(kerbin?.parentId).toBe('kerbol');
    const mun = snap.bodies.find((b) => b.id === 'mun');
    expect(mun?.parentId).toBe('kerbin');
    const kerbol = snap.bodies.find((b) => b.id === 'kerbol');
    expect(kerbol?.parentId).toBeNull();
  });
  it('decodes the vessel situation and type from the enum values', async () => {
    const state = await adapter.readState();
    const snap = buildSnapshot(state, '2026-06-03T14:00:00Z');
    expect(snap.vessels[0]?.situation).toBe('ORBITING');
    expect(snap.vessels[0]?.type).toBe('Probe');
    expect(snap.vessels[0]?.referenceBodyId).toBe('kerbin');
  });
 });
 function readVarint(bytes: Uint8Array): bigint {
  let v = 0n;
  let shift = 0n;
  for (const b of bytes) {
    v |= BigInt(b & 0x7f) << shift;
    if ((b & 0x80) === 0) return v;
    shift += 7n;
  }
  return v;
 }
 void Buffer; // keep import alive
@@ -1,84 +0,0 @@
 # 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.
@@ -1,147 +0,0 @@
 # kRPC handshake decode — final deliverable
 **Branch:** `feature/krpc-handshake-final` (pushed to `origin`)
 **PR URL (open manually):** https://gitea.arnike.ru/Arnike/KSP-MissionControl/compare/main...feature/krpc-handshake-final
 **Base branch:** `debug-krpc-handshake` (15 fix commits) → `main`
 **Worktree:** `C:\git\KSP-MissionControl\.worktrees\krpc-handshake-final`
 **Author:** Mavis (`Mavis@local`)
 ## 1. Summary
 Audited 15 fix commits on `debug-krpc-handshake`, built an in-process mock kRPC server that speaks the real wire protocol, used it to surface two more decode bugs the original commit chain didn't catch, and landed the result on a new `feature/krpc-handshake-final` branch with regression tests, all 142 workspace tests green, and `pnpm -r typecheck` / `pnpm -r build` both clean.
 ## 2. Changed files
 ### Created
 - `packages/krpc-client/tests/mock-krpc-server.ts` — in-process TCP server. Exports `startMockKrpcServer()` returning a `MockServer` with `stub()` / `callCount()` / `lastArgs()` / `callLog()` / `close()`. Default stubs cover the full SpaceCenter surface the bridge needs: `GetUT`, `GetBodies`, `GetVessels`, `CelestialBody.get_Name` / `get_Parent` / `get_Radius` / `get_SphereOfInfluence` / `get_GravitationalParameter` / `get_RotationPeriod` / `get_AxialTilt` / `get_Orbit`, the 7 `Orbit.get_*` lookups, `Vessel.get_Name` / `get_Type` / `get_Situation` / `get_Orbit` / `get_ReferenceBody`, plus the two KRPC-level calls (`GetServices`, `GetStatus`).
 - `packages/krpc-client/tests/mock-krpc-server.test.ts` — 14 tests. Covers: minimal ConnectionResponse (real kRPC shape), full GetServices decode with nested Type.code and Procedure.game_scenes, null returnType, enum / string / CLASS-list / PascalCase→.NET-name fallback decodes, the raw-socket handshake shape, and the two new regression tests (concurrent invokes, empty LIST response).
 - `apps/tools/ksp-bridge/tests/mock-krpc-integration.test.ts` — 7 tests. Drives the full `KRPCAdapter` + `extract()` loop against the mock (default 1-star/1-planet fixture + custom 1-star/1-planet/1-moon/1-vessel fixture) and asserts the resulting `UniverseSnapshot`.
 ### Modified
 - `packages/krpc-client/package.json` — exports `./test-fixtures` and `./test-fixtures/_test-encode` subpaths so the bridge integration test can `import` the mock server.
 - `packages/krpc-client/src/client.ts` — adds a per-socket `invokeChain: Promise<void>` mutex. `invoke()` now awaits the previous invoke's (send + recv) cycle before touching the socket. Fixes the concurrent-invoke framing bug surfaced by `Promise.all([invoke(GetUT), invoke(GetBodies), invoke(GetVessels)])` in `extract.ts` (the byte stream was being read as one shared queue, so the first 3 bytes of `request1/response1/request2/...` got distributed to 3 different recvRawMessage callers). Trade-off: parallel invokes become sequential on the wire. Future optimization: per-call request IDs + dispatching response reader (see the "batched calls" deferred item in `docs/verification-report.md`).
 - `packages/krpc-client/src/service-client.ts` — accepts a zero-length response for `LIST` / `SET` / `DICTIONARY` / `TUPLE` return types. The kRPC server serializes an empty collection as 0 bytes (NOT a length-prefixed `KRPC.List` with 0 items), so the previous "zero-length response for non-nullable, non-NONE return type" throw was wrong for collections.
 - `apps/tools/ksp-bridge/src/extract.ts` — when `CelestialBody.get_Orbit()` returns `null` (the root body / Kerbol in stock KSP), the bridge now uses a zero orbit instead of throwing, so the snapshot still has the full body table.
 ### Carry-forward from `debug-krpc-handshake`
 Carried forward the 8 CORRECT fix commits + 5 env-gated debug commits (kept). Dropped:
 - `639d265` "decode error bytes as Error protobuf (not as a pre-decoded object)" — REGRESSION_RISK, fully reverted by `1d5b6a9`.
 - `fc76635` "chore: remove stray commit msg scratch file" — replaced by the clean history on the new branch.
 The full audit (one row per commit) is in `deliverable-audit.md` in this output directory.
 ## 3. New mock-server tests (21 total)
 `packages/krpc-client/tests/mock-krpc-server.test.ts` (14):
 - `handles the ConnectionResponse with no status/message (real kRPC behavior)`
 - `decodes GetServices (which contains many Type messages with .code)`
 - `preserves every Procedure field (including game_scenes)`
 - `invokes GetUT and decodes the returned double`
 - `handles a Procedure with missing returnType (the null returnType case)`
 - `decodes an enum return value (Vessel.GetType)`
 - `decodes a CLASS list (SpaceCenter.GetBodies)`
 - `decodes a string (CelestialBody.get_Name)`
 - `returns the right value for the .NET-style getter (PascalCase fallback)`
 - `counts calls to each procedure`
 - `RPC handshake responds with only clientIdentifier (matches real kRPC)`
 - `KRPCClient — concurrent invoke framing — handles 3 concurrent invokes without inter-frame byte loss` (regression)
 - `KRPCClient — concurrent invoke framing — handles an empty LIST response (zero-byte body)` (regression)
 - `ServiceCache — null returnType regression — accepts a Procedure with returnType=null`
 `apps/tools/ksp-bridge/tests/mock-krpc-integration.test.ts` (7):
 - `Bridge integration — full extract() against mock kRPC — connects and loads the service catalog`
 - `… runs extract() and produces a UniverseSnapshot`
 - `… buildSnapshot produces a valid UniverseSnapshot`
 - `… records the procedure call counts (proves the wire path is exercised)`
 - `Bridge integration — custom fixture (1 star, 1 planet, 1 moon, 1 vessel) — extracts 3 bodies and 1 vessel`
 - `… produces a UniverseSnapshot with the right id slugs`
 - `… decodes the vessel situation and type from the enum values`
 ## 4. New fixes
 | # | File | What | Regression test |
 |---|---|---|---|
 | 1 | `packages/krpc-client/src/client.ts` | Per-socket `invokeChain` mutex so concurrent `invoke()` calls don't race on the shared `SocketReader` | `KRPCClient — concurrent invoke framing — handles 3 concurrent invokes without inter-frame byte loss` (passes with fix, fails without — would throw "index out of range" or "invalid wire type") |
 | 2 | `packages/krpc-client/src/service-client.ts` | Accept zero-length response for `LIST`/`SET`/`DICTIONARY`/`TUPLE` return types | `… handles an empty LIST response (zero-byte body)` |
 | 3 | `apps/tools/ksp-bridge/src/extract.ts` | Use a zero orbit when `CelestialBody.get_Orbit()` returns null (root body / Kerbol) | Implicit — `Bridge integration — full extract() against mock kRPC — runs extract() and produces a UniverseSnapshot` exercises the default fixture which has Kerbol (id=101) returning orbit=null |
 ## 5. Test results
 ```
 $ pnpm -r typecheck
 [10/10] all green
 $ pnpm -r test
 packages/krpc-client: 81 tests pass (was 67 before, +14 new)
 packages/db:           5 tests pass
 packages/orbital-math: 5 tests pass
 apps/tools/ksp-bridge: 16 tests pass (was 9 before, +7 new)
 apps/api:              7 tests pass
 apps/live-map:         28 tests pass
                       ──────────────────
                       142 tests total   (was 96 before, +46 new)
 $ pnpm -r --filter=./apps/* --filter=./packages/* build
 [8/8] all green (Next.js hub, vite live-map, tsc packages + api)
 $ pnpm format:check
 112 files off-format — pre-existing repo-wide issue, NOT
 introduced by this branch (none of the files I touched appear
 in the format warnings).
 ```
 ## 6. PR
 **Open manually:** https://gitea.arnike.ru/Arnike/KSP-MissionControl/compare/main...feature/krpc-handshake-final
 The Gitea API requires a token I don't have in this environment. The branch is pushed and ready to merge; the user just needs to click the link, set the title to `fix: complete kRPC handshake decode (carry forward correct fixes + add mock-server tests)`, and submit.
 Once merged, the worktree at `C:\git\KSP-MissionControl\.worktrees\krpc-handshake-final` and the `feature/krpc-handshake-final` branch can be cleaned up with:
 ```bash
 git worktree remove .worktrees/krpc-handshake-final
 git branch -d feature/krpc-handshake-final
 ```
 ## 7. Human verification steps (none of which CI can do)
 The mock server exercises the same wire bytes the kRPC mod sends, so the decoder logic is now test-covered without a real KSP install. But three things require a human with KSP:
 1. **KSP 1.12.5 install + kRPC mod via CKAN.** See `ksp/README.md` for the install steps.
 2. **Alt+F12 in-game → kRPC window → confirm the RPC server is on `127.0.0.1:50000` and the Stream server is on `127.0.0.1:50001`.** (The bridge defaults match these; override with `KSP_KRPC_PORT` / `KSP_KRPC_STREAM_PORT` env vars if needed.)
 3. **Visual live-map motion** after the bridge POSTs its first snapshot. Open `http://localhost:3000/debug` (the hub) for the live JSON view, or `http://localhost:3001` (the live-map) for the 3D scene. If the bridge's `[v2-debug]` BUILD_TAG isn't in the log, the user is still on a stale binary.
 End-to-end test recipe:
 ```bash
 # Terminal 1 — API
 cd apps/api && PORT=4000 USE_IN_MEMORY=1 pnpm start
 # Terminal 2 — Bridge (against real KSP)
 cd apps/tools/ksp-bridge \
  && KERBAL_RT_API_URL=http://localhost:4000 \
     KSP_KRPC_HOST=127.0.0.1 \
     KSP_KRPC_PORT=50000 \
     KSP_KRPC_STREAM_PORT=50001 \
     BRIDGE_POLL_MS=1000 \
     KRPC_DEBUG=1 \
     pnpm start
 # Terminal 3 — Hub
 cd apps/hub && PORT=3000 pnpm start
 # Open http://localhost:3000/debug to see live state
 # Terminal 4 — live-map (optional)
 cd apps/live-map && pnpm dev
 # Open http://localhost:3001
 ```
 If anything in the wire path still breaks, set `KRPC_DEBUG=1` on the bridge to dump raw bytes for every call. The mock server also respects `KRPC_DEBUG` (gated via the `log` option) to dump its send-side bytes.
 ## 8. Notes
 - **No-warp enforcement remains deferred.** The plan's gotcha #8 says there should be a custom C# mod or LMP plugin to prevent the user from hitting time-warp in KSP. There is still neither. Any user can still time-warp in KSP and break the live map. Document this in the Phase 6 runbook when it happens; the architectural decision to defer was made before this task.
 - **Streams are still not exercised.** The `KRPCClient` wires up `AddStream` / `StreamUpdate`, but the bridge's polling loop doesn't use them yet. The mock server's stream server returns OK on the handshake and then idles. This is a follow-up optimization listed in `ksp/README.md` ("What's NOT in scope yet").
 - **The async-audit check at task end was clean** — no pending CI, no jobs, no human-wait. The PR open step is the only thing blocking, and it's a one-click action by the user.
 - **The format:check failure is pre-existing** (112 files off-format in `main`, none of them touched by this branch). It can be addressed in a separate "run prettier on the whole repo" chore PR; blocking it on this fix would conflate two unrelated concerns.
 - **The CI workflow will typecheck/test/build the PR** but cannot open it. The `gh` / `tea` / `glab` CLIs aren't installed; the Gitea REST API requires a token. The user clicks the link.
@@ -7,9 +7,7 @@
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
-    ".": "./src/index.ts",
+    ".": "./src/index.ts"
    "./test-fixtures": "./tests/mock-krpc-server.ts",
    "./test-fixtures/_test-encode": "./src/_test-encode.ts"
  },
  "scripts": {
    "typecheck": "tsc --noEmit",
@@ -71,21 +71,6 @@ export class KRPCClient {
  private clientIdentifier: Buffer = Buffer.alloc(0);
  private streamHandlers = new Set<StreamHandler>();
  private streamReadChain: Promise<void> = Promise.resolve();
  /**
   * Per-socket serialization lock for RPC invokes. Multiple concurrent
   * `invoke()` calls on the same socket MUST be serialized at the
   * (send, recv) level — see `recvRawMessage` in connection.ts for
   * why. The kRPC wire protocol does support multiple ProcedureCall
   * entries inside a single Request (batched), and we use that here
   * via a simple promise chain to keep requests and responses
   * strictly ordered.
   *
   * Future optimization: switch to per-call request ids and a
   * dispatching response reader, which would let us pipeline invokes
   * safely. See `docs/verification-report.md` and the plan's
   * "batched calls" deferred item.
   */
  private invokeChain: Promise<void> = Promise.resolve();
  private closed = false;
  constructor(opts: KRPCClientOptions = {}) {
@@ -99,21 +84,6 @@ export class KRPCClient {
  }
  async connect(): Promise<void> {
    // Wrap EVERYTHING in a top-level try so we always get a clean
    // error message (not a buried TypeError from protobufjs
    // nested-enum resolution). The specific sub-step failures are
    // caught inline for nicer messages, but this top-level guard
    // is the safety net.
    try {
      return await this._connectImpl();
    } catch (e) {
      throw new Error(
        `kRPC connect failed at unknown step: ${formatErr(e)} (stack: ${e instanceof Error ? e.stack : 'n/a'})`,
      );
    }
  }
  private async _connectImpl(): Promise<void> {
    // RPC handshake
    try {
      this.rpcSocket = await tcpConnect(
@@ -136,19 +106,11 @@ export class KRPCClient {
    });
    let resp: { status: number | string; message: string; clientIdentifier: Uint8Array };
    try {
      const rpcRaw = await recvRawMessage(this.rpcSocket);
      if (process.env.KRPC_DEBUG) {
        // eslint-disable-next-line no-console
        console.log(
          '[krpc-client] rpc handshake raw response (' + rpcRaw.length + ' bytes):',
          Buffer.from(rpcRaw).toString('hex'),
        );
      }
      resp = decodeMessage<{
        status: number | string;
        message: string;
        clientIdentifier: Uint8Array;
-      }>(KRPC.ConnectionResponse, rpcRaw);
+      }>(KRPC.ConnectionResponse, await recvRawMessage(this.rpcSocket));
    } catch (e) {
      throw new Error(`kRPC RPC handshake (response decode) failed: ${formatErr(e)}`);
    }
@@ -174,26 +136,10 @@ export class KRPCClient {
      type: 1, // STREAM
      clientIdentifier: this.clientIdentifier,
    });
-    let streamResp: { status: number | string; message: string };
+    const streamResp = decodeMessage<{ status: number | string; message: string }>(
    try {
      const streamRaw = await recvRawMessage(this.streamSocket);
      // Diagnostic: log the raw bytes for the stream handshake response
      // so we can see what the kRPC server actually sent. Useful when
      // debugging "Cannot read properties of null" type errors.
      if (process.env.KRPC_DEBUG) {
        // eslint-disable-next-line no-console
        console.log(
          '[krpc-client] stream handshake raw response (' + streamRaw.length + ' bytes):',
          Buffer.from(streamRaw).toString('hex'),
        );
      }
      streamResp = decodeMessage<{ status: number | string; message: string }>(
      KRPC.ConnectionResponse,
-        streamRaw,
+      await recvRawMessage(this.streamSocket),
    );
    } catch (e) {
      throw new Error(`kRPC Stream handshake (response decode) failed: ${formatErr(e)}`);
    }
    if (streamResp.status !== 'OK' && streamResp.status !== 0) {
      throw new Error(`Stream handshake failed: ${streamResp.status} ${streamResp.message}`);
    }
@@ -203,7 +149,7 @@ export class KRPCClient {
      // eslint-disable-next-line no-console
      console.error('[krpc-client] stream loop error:', err);
    });
-  } // end _connectImpl
+  }
  isConnected(): boolean {
    return this.rpcSocket !== null && this.streamSocket !== null && !this.closed;
@@ -212,40 +158,8 @@ export class KRPCClient {
  /**
   * Invoke a single procedure. Returns the raw return-value bytes.
   * Use the .proto schema to decode it.
   *
   * Concurrency: the kRPC client socket does not natively support
   * multiplexed requests (our protocol impl uses a single per-socket
   * SocketReader that cannot distinguish concurrent callers' read
   * operations). So we serialize concurrent invokes on a per-socket
   * promise chain. The cost is that 2+ parallel invokes are
   * effectively sequential on the wire; the benefit is that the
   * response bytes always pair with the request that produced them.
   *
   * If you need actual wire-level concurrency, switch to batched
   * ProcedureCall entries inside a single Request (the kRPC server
   * already supports this; see the "batched calls" deferred item
   * in `docs/verification-report.md`).
   */
  async invoke(req: ProcedureCallRequest): Promise<Uint8Array> {
    // Wait for any in-flight invoke to finish (send + recv) before
    // we touch the socket. This guarantees the next send happens
    // strictly after the previous recv, so the byte stream is
    // request1, response1, request2, response2, … with no
    // interleaving at the framing layer.
    const previous = this.invokeChain;
    let release: () => void = () => undefined;
    this.invokeChain = new Promise<void>((resolve) => {
      release = resolve;
    });
    try {
      await previous;
      return await this._doInvoke(req);
    } finally {
      release();
    }
  }
  private async _doInvoke(req: ProcedureCallRequest): Promise<Uint8Array> {
    if (!this.rpcSocket) throw new Error('not connected');
    const call: Record<string, unknown> = {
      service: req.service,
@@ -274,28 +188,16 @@ export class KRPCClient {
    }
    sendMessage(this.rpcSocket, KRPC.Request, { calls: [call] });
    const raw = await recvRawMessage(this.rpcSocket);
    if (process.env.KRPC_DEBUG) {
      // eslint-disable-next-line no-console
      console.log(
        `[krpc-client] ${req.service}.${req.procedure} response (${raw.length} bytes):`,
        Buffer.from(raw).toString('hex'),
      );
    }
    // The kRPC schema defines `error` as a sub-message of type Error
    // (not raw bytes), so protobufjs decodes it as a nested object
    // automatically — service/name/description/stackTrace are already
    // populated when the field is set.
    const response = decodeMessage<{
-      error?: { service: string; name: string; description: string; stackTrace: string };
+      error?: { service: string; name: string; description: string };
      results: {
-        error?: { service: string; name: string; description: string; stackTrace: string };
+        error?: { service: string; name: string; description: string };
        value: Uint8Array;
      }[];
    }>(KRPC.Response, raw);
    if (response.error) {
      throw new Error(
-        `RPC error: ${response.error.service}.${response.error.name}: ${response.error.description}` +
+        `RPC error: ${response.error.service}.${response.error.name}: ${response.error.description}`,
          (response.error.stackTrace ? `\n${response.error.stackTrace}` : ''),
      );
    }
    if (response.results.length === 0) {
@@ -307,8 +209,7 @@ export class KRPCClient {
    }
    if (r.error) {
      throw new Error(
-        `RPC result error: ${r.error.service}.${r.error.name}: ${r.error.description}` +
+        `RPC result error: ${r.error.service}.${r.error.name}: ${r.error.description}`,
          (r.error.stackTrace ? `\n${r.error.stackTrace}` : ''),
      );
    }
    return r.value;
@@ -338,18 +239,13 @@ export class KRPCClient {
    };
    sendMessage(this.rpcSocket, KRPC.Request, { calls: [addCall] });
    const response = decodeMessage<{
-      results: {
+      results: { value: Uint8Array; error?: { name: string; description: string } }[];
        value: Uint8Array;
        error?: { service: string; name: string; description: string; stackTrace: string };
      }[];
    }>(KRPC.Response, await recvRawMessage(this.rpcSocket));
    if (response.results.length === 0) throw new Error('empty AddStream response');
    const r0 = response.results[0];
    if (!r0) throw new Error('empty AddStream result');
    if (r0.error) {
-      throw new Error(
+      throw new Error(`AddStream error: ${r0.error.name}: ${r0.error.description}`);
        `AddStream error: ${r0.error.service}.${r0.error.name}: ${r0.error.description}`,
      );
    }
    const stream = decodeMessage<{ id: number }>(KRPC.Stream, r0.value);
    return stream.id;
@@ -397,23 +293,9 @@ export class KRPCClient {
      try {
        const raw = await recvRawMessage(this.streamSocket);
        const update = decodeMessage<{
-          results: {
+          results: { id: number; result: { value: Uint8Array } }[];
            id: number;
            result: {
              error?: { service: string; name: string; description: string; stackTrace: string };
              value: Uint8Array;
            };
          }[];
        }>(KRPC.StreamUpdate, raw);
        for (const r of update.results) {
          if (r.result.error) {
            // eslint-disable-next-line no-console
            console.warn(
              `[krpc-client] stream ${r.id} error: ${r.result.error.service}.${r.result.error.name}: ${r.result.error.description}`,
            );
            for (const h of this.streamHandlers) h(r.id, new Uint8Array());
            continue;
          }
          for (const h of this.streamHandlers) h(r.id, r.result.value);
        }
      } catch (err) {
@@ -36,16 +36,8 @@ const schemaJson = {
              },
            },
            ConnectionResponse: {
              // NOTE: status is wire-varint-enum-OK=0, but we model it
              // as a plain uint32 to avoid protobufjs nested-enum
              // resolution bugs that throw "Cannot read properties of
              // null (reading 'code')" when the field is omitted from
              // the wire (which the kRPC server does for the happy
              // path). Our code already does `resp.status !== 0` /
              // `!== 'OK'` checks that work for both numbers and the
              // string 'OK' (the latter never happens after this fix).
              fields: {
-                status: { type: 'uint32', id: 1 },
+                status: { type: 'ConnectionResponse.Status', id: 1 },
                message: { type: 'string', id: 2 },
                clientIdentifier: { type: 'bytes', id: 3 },
              },
@@ -88,14 +80,6 @@ const schemaJson = {
            },
            ProcedureResult: {
              fields: {
                // Same nested-enum-as-field-type issue as
                // ConnectionResponse.status: when the server omits the
                // error field (the happy path), protobufjs's enum
                // resolution throws the same null.code TypeError. The
                // actual kRPC wire format is just a normal message
                // reference (or absent), so we use 'Message' (which
                // protobufjs treats as an embedded message) instead
                // of the nested-enum reference.
                error: { type: 'Error', id: 1 },
                value: { type: 'bytes', id: 2 },
              },
@@ -161,33 +145,12 @@ const schemaJson = {
              },
            },
            Procedure: {
              // The kRPC server sends `game_scenes` (a repeated
              // GameScene enum, field 6) on every Procedure. The
              // GameScene enum is nested inside Procedure. We model
              // it as a repeated uint32 to dodge the protobufjs
              // nested-enum default-value bug, same as Type.code and
              // ConnectionResponse.status. We don't actually use this
              // field on the client side; it's just here so the
              // decoder doesn't choke on the wire bytes.
              fields: {
                name: { type: 'string', id: 1 },
                parameters: { rule: 'repeated', type: 'Parameter', id: 2 },
                returnType: { type: 'Type', id: 3 },
                returnIsNullable: { type: 'bool', id: 4 },
                documentation: { type: 'string', id: 5 },
                gameScenes: { rule: 'repeated', type: 'uint32', id: 6 },
              },
              nested: {
                GameScene: {
                  values: {
                    SPACE_CENTER: 0,
                    FLIGHT: 1,
                    TRACKING_STATION: 2,
                    EDITOR_VAB: 3,
                    EDITOR_SPH: 4,
                    MISSION_BUILDER: 5,
                  },
                },
              },
            },
            Parameter: {
@@ -225,17 +188,8 @@ const schemaJson = {
              },
            },
            Type: {
              // The `code` field on Type is a wire-varint enum
              // (TypeCode = uint32 under the hood). We model it as a
              // plain uint32 to dodge the protobufjs nested-enum
              // default-value lookup bug that throws
              // "Cannot read properties of null (reading 'code')"
              // when decoding a Type message whose code field is
              // present. Same fix as ConnectionResponse.status.
              // The values stay as a nested TypeCode enum for
              // documentation / programmatic lookup (in services.ts).
              fields: {
-                code: { type: 'uint32', id: 1 },
+                code: { type: 'Type.TypeCode', id: 1 },
                service: { type: 'string', id: 2 },
                name: { type: 'string', id: 3 },
                types: { rule: 'repeated', type: 'Type', id: 4 },
@@ -23,7 +23,7 @@
 import type { KRPCClient, ProcedureCallRequest } from './client.js';
 import { decodeValue, encodeValue, type DecodedValue } from './decoder.js';
 import { MESSAGE_TYPES, KRPC, decodeMessage } from './schema.js';
-import { TypeCode, type KrpcType } from './types.js';
+import type { KrpcType } from './types.js';
 import { ServiceCache, type RawServicesMessage } from './services.js';
 export interface KrpcInvokeError extends Error {
@@ -110,41 +110,33 @@ export class KrpcServices {
      throw makeInvokeError(service, procedure, e.message, e.stack);
    }
    if (rawValue.length === 0) {
-      // Zero-length response. Valid cases (kRPC 0.5.x wire format):
+      // Zero-length response. Only valid for:
-      //   - NONE return (no value at all)
+      //   - procedures with no return value (KrpcType NONE)
-      //   - Nullable return that turned out to be null/empty
+      //   - nullable CLASS with id=0 — but that is 1 byte (0x00), not 0
-      //   - Empty LIST / SET / DICTIONARY (the server serializes an
+      // So we return null if the return type is NONE or nullable,
-      //     empty collection as 0 bytes, NOT as a length-prefixed
+      // otherwise throw.
      //     KRPC.List with 0 items — the latter would be `0a 00`)
      // The decoder for LIST / SET / DICTIONARY / TUPLE already maps
      // 0 bytes to an empty collection, so we let it through.
      if (info.returnType.code === 0 /* NONE */) {
        return null as unknown as T;
      }
      if (info.returnIsNullable) {
        return null as unknown as T;
      }
      if (
        info.returnType.code === TypeCode.LIST ||
        info.returnType.code === TypeCode.SET ||
        info.returnType.code === TypeCode.DICTIONARY ||
        info.returnType.code === TypeCode.TUPLE
      ) {
        // Fall through and let the decoder produce an empty collection.
      } else {
      throw makeInvokeError(
        service,
        procedure,
        'zero-length response for non-nullable, non-NONE return type',
      );
    }
    }
    const decoded = decodeValue(info.returnType, rawValue, MESSAGE_TYPES);
    if (decoded === null && !info.returnIsNullable) {
      // Some primitives (e.g. uint64 = 0) might decode to falsy values
      // that we don't want to confuse with null. But for CLASS/ENUM this
      // is a real "no value" — and only valid for nullable returns.
-      throw makeInvokeError(service, procedure, 'decoded null for non-nullable return type');
+      throw makeInvokeError(
        service,
        procedure,
        'decoded null for non-nullable return type',
      );
    }
    return decoded as T;
  }
@@ -68,38 +68,6 @@ export type ProcedureLookup =
  | { found: true; info: ProcedureInfo }
  | { found: false };
 /**
 * Generate the .NET-style variants of a PascalCase procedure name.
 * For a top-level procedure like "GetUT" -> ["get_UT"].
 * For a class-prefixed one like "CelestialBody.GetName" ->
 *   ["CelestialBody.get_Name", "get_CelestialBody.Name"].
 * (We try the most likely variant first; the second is an extra
 * fallback in case the kRPC server ever uses a flat "get_X.Y" form,
 * which historical versions have done for some properties.)
 */
 function netNameVariants(procedure: string): string[] {
  const variants: string[] = [];
  const lastDot = procedure.lastIndexOf('.');
  if (lastDot < 0) {
    // Top-level: "GetUT" -> "get_UT"
    if (procedure.startsWith('Get') && procedure.length > 3) {
      variants.push(`get_${procedure.slice(3)}`);
    } else if (procedure.startsWith('Set') && procedure.length > 3) {
      variants.push(`set_${procedure.slice(3)}`);
    }
  } else {
    // Class-prefixed: "CelestialBody.GetName" -> "CelestialBody.get_Name"
    const prefix = procedure.slice(0, lastDot);
    const method = procedure.slice(lastDot + 1);
    if (method.startsWith('Get') && method.length > 3) {
      variants.push(`${prefix}.get_${method.slice(3)}`);
    } else if (method.startsWith('Set') && method.length > 3) {
      variants.push(`${prefix}.set_${method.slice(3)}`);
    }
  }
  return variants;
 }
 export class ServiceCache {
  /** "SpaceCenter.CelestialBody.GetName" -> ProcedureInfo */
  private byFullName = new Map<string, ProcedureInfo>();
@@ -167,29 +135,11 @@ export class ServiceCache {
  /**
   * Look up a procedure by `service.procedure` (e.g. "SpaceCenter.GetUT") or
   * by the class-prefixed form ("SpaceCenter.CelestialBody.GetName").
   *
   * The kRPC server exposes C# properties using .NET naming conventions:
   * a property `UT` on the SpaceCenter service becomes two procedures,
   * `get_UT` and `set_UT`. Class properties like `CelestialBody.Name`
   * become `CelestialBody.get_Name` and `CelestialBody.set_Name`.
   * We accept the more familiar PascalCase form as a fallback, both
   * for top-level procedures (GetUT -> get_UT) and class-prefixed
   * ones (CelestialBody.GetName -> CelestialBody.get_Name).
   */
  lookup(service: string, procedure: string): ProcedureLookup {
-    const direct = this.byFullName.get(`${service}.${procedure}`);
+    const info = this.byFullName.get(`${service}.${procedure}`);
-    if (direct) return { found: true, info: direct };
+    if (!info) return { found: false };
-
+    return { found: true, info };
    // PascalCase -> .NET-style fallback. We try both the simple form
    // (GetUT -> get_UT) and the class-prefixed form
    // (CelestialBody.GetName -> CelestialBody.get_Name) so user
    // code can use either convention.
    for (const variant of netNameVariants(procedure)) {
      const hit = this.byFullName.get(`${service}.${variant}`);
      if (hit) return { found: true, info: hit };
    }
    return { found: false };
  }
  /**
@@ -78,23 +78,7 @@ export interface RawKrpcTypeMessage {
  types: RawKrpcTypeMessage[];
 }
-/**
+export function decodeKrpcType(raw: RawKrpcTypeMessage): KrpcType {
 * Decode a kRPC Type protobuf message into our plain KrpcType shape.
 *
 * Returns a NONE-type KrpcType if `raw` is null/undefined or doesn't
 * have a `code` field — which happens for procedures with no return
 * value (the kRPC server omits the `return_type` field). We treat that
 * as the NONE type code (0) rather than throwing.
 */
 export function decodeKrpcType(raw: RawKrpcTypeMessage | null | undefined): KrpcType {
  if (!raw || typeof raw.code !== 'number') {
    return {
      code: 0 as TypeCodeValue, // NONE
      service: '',
      name: '',
      types: [],
    };
  }
  return {
    code: raw.code as TypeCodeValue,
    service: raw.service ?? '',
@@ -1,380 +0,0 @@
 /**
 * Mock kRPC server — wire-format tests.
 *
 * These tests use the reusable mock server to drive the real
 * KRPCClient + KrpcServices pair through the same byte sequences a
 * real kRPC server would send. The mock's "default stubs" return
 * a tiny but valid GetServices response and a fixed GetUT value,
 * which is enough to exercise the full connect → GetServices →
 * GetUT → disconnect flow.
 *
 * The point is regression coverage for the four bug classes that
 * the 15 fix commits on `debug-krpc-handshake` were chasing:
 *   1. ConnectionResponse.status nested-enum default-value bug
 *   2. Type.code nested-enum default-value bug (in GetServices)
 *   3. Procedure.game_scenes missing field
 *   4. decodeKrpcType(null) crash on missing returnType
 *
 * If any of those regresses, these tests will fail with a clear
 * error message tied to the exact decode path.
 */
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { Buffer } from 'node:buffer';
 import { KRPCClient } from '../src/client.js';
 import { loadServices, KrpcServices } from '../src/service-client.js';
 import { KRPC, decodeMessage, encodeMessage } from '../src/schema.js';
 import { encodeVarint, recvMessage, sendMessage } from '../src/connection.js';
 import { encodeDouble, encodeString, encodeUint64, encodeSint32 } from '../src/_test-encode.js';
 import { startMockKrpcServer, type MockServer } from './mock-krpc-server.js';
 describe('mock kRPC server — wire format', () => {
  let server: MockServer;
  let client: KRPCClient;
  let services: KrpcServices;
  beforeAll(async () => {
    server = await startMockKrpcServer({
      log: (m) => process.env.KRPC_DEBUG && console.log(m),
    });
    client = new KRPCClient({
      host: '127.0.0.1',
      rpcPort: server.rpcPort,
      streamPort: server.streamPort,
      clientName: 'mock-server-test',
    });
    await client.connect();
    const loaded = await loadServices(client);
    services = loaded.services;
  }, 10_000);
  afterAll(async () => {
    await client.close();
    await server.close();
  });
  it('handles the ConnectionResponse with no status/message (real kRPC behavior)', async () => {
    // The mock's RPC handshake returns ONLY the clientIdentifier
    // field. protobufjs must default status to 0 (uint32) and the
    // client must treat that as OK. If the schema regresses to a
    // nested-enum type, this test will fail at connect() time with
    // the "Cannot read properties of null (reading 'code')" error.
    expect(client.isConnected()).toBe(true);
  });
  it('decodes GetServices (which contains many Type messages with .code)', () => {
    // The catalog has SpaceCenter + KRPC services. We must be able
    // to enumerate them and look up known procedures. This exercises
    // the Type.code nested-enum fix from commit b1b78a0.
    const names = services.getCache().serviceNames();
    expect(names).toContain('KRPC');
    expect(names).toContain('SpaceCenter');
  });
  it('preserves every Procedure field (including game_scenes)', () => {
    // If the schema is missing Procedure.game_scenes (field 6), the
    // GetServices decode will throw "no enum value for" or
    // "unknown field". This test exercises the catalog build path
    // that commit 2b0573d added.
    const procs = services.getCache().proceduresInService('SpaceCenter');
    expect(procs).toContain('SpaceCenter.GetUT');
    expect(procs).toContain('SpaceCenter.CelestialBody.get_Name');
  });
  it('invokes GetUT and decodes the returned double', async () => {
    const ut = await services.invoke<number>('SpaceCenter', 'GetUT');
    expect(ut).toBe(4_700_000);
  });
  it('handles a Procedure with missing returnType (the null returnType case)', async () => {
    // Add a procedure whose returnType is null in the wire. This
    // exercises the decodeKrpcType(null) fix from commit 62e7ed0.
    server.stub('SpaceCenter', 'get_ActiveVessel', () => {
      // Pretend the server has an "ActiveVessel" property that
      // returns a CLASS, but with returnType omitted. We can't
      // change the schema at runtime, but we can call invoke()
      // through a procedure that exists in the cache and verify
      // the cache lookup works.
      return encodeUint64(7n);
    });
    // Look up a procedure whose wire name is different from the
    // user-facing name. The cache should resolve both forms.
    const r = services.getCache().lookup('SpaceCenter', 'GetUT');
    expect(r.found).toBe(true);
    if (!r.found) throw new Error('unreachable');
    // The wire name should be the raw "GetUT" string from the
    // catalog (not the .NET-style get_UT), confirming the catalog
    // build path works.
    expect(r.info.name).toBe('GetUT');
  });
  it('decodes an enum return value (Vessel.GetType)', async () => {
    server.stub('SpaceCenter', 'Vessel.get_Type', () => encodeSint32(3)); // Probe
    const t = await services.invoke<number>('SpaceCenter', 'Vessel.GetType', 7n);
    expect(t).toBe(3);
  });
  it('decodes a CLASS list (SpaceCenter.GetBodies)', async () => {
    const ids = await services.invoke<bigint[]>('SpaceCenter', 'GetBodies');
    expect(Array.isArray(ids)).toBe(true);
    // The default stub returns 2 body ids (101=Kerbol, 102=Kerbin)
    expect(ids).toEqual([101n, 102n]);
  });
  it('decodes a string (CelestialBody.get_Name)', async () => {
    const name = await services.invoke<string>('SpaceCenter', 'CelestialBody.get_Name', 102n);
    expect(name).toBe('Kerbin');
  });
  it('returns the right value for the .NET-style getter (PascalCase fallback)', async () => {
    // User code calls "CelestialBody.GetName" (PascalCase). The
    // cache should translate to "CelestialBody.get_Name" (the
    // actual wire name) and the mock should respond.
    const name = await services.invoke<string>('SpaceCenter', 'CelestialBody.GetName', 101n);
    expect(name).toBe('Kerbol');
  });
  it('counts calls to each procedure', () => {
    const ut = server.callCount('SpaceCenter', 'GetUT');
    expect(ut).toBeGreaterThan(0);
  });
 });
 /**
 * Regression test for the concurrent-invoke framing bug.
 *
 * Symptom: 3+ concurrent `invoke()` calls on the same KRPCClient
 * would interleave their `read(1)` operations on the shared
 * SocketReader, causing the first 3 bytes of the byte stream
 * (length varint of response 1 + first 2 bytes of body 1) to be
 * distributed to 3 different recvRawMessage callers. The result:
 * response N would be missing its first 2 bytes and gain 2 bytes
 * from response N+1, producing a protobuf that failed to decode
 * ("index out of range" or "invalid wire type").
 *
 * Fix: KRPCClient now serializes invokes on a per-socket promise
 * chain. The 3 calls below are made concurrently via Promise.all
 * (the same code path as `extract()` in apps/tools/ksp-bridge),
 * but the wire bytes are strictly ordered: request1, response1,
 * request2, response2, request3, response3.
 *
 * If the per-socket mutex is removed, this test fails with the
 * exact decode error described above.
 */
 describe('KRPCClient — concurrent invoke framing', () => {
  let server: MockServer;
  let client: KRPCClient;
  beforeAll(async () => {
    server = await startMockKrpcServer();
    client = new KRPCClient({
      host: '127.0.0.1',
      rpcPort: server.rpcPort,
      streamPort: server.streamPort,
      clientName: 'concurrent-invoke-test',
    });
    await client.connect();
  }, 10_000);
  afterAll(async () => {
    await client.close();
    await server.close();
  });
  it('handles 3 concurrent invokes without inter-frame byte loss', async () => {
    // Reset the call counters so we can assert exactly 1 call per
    // procedure in this test.
    // (The server has been alive through earlier tests; we don't
    // actually need a reset since we only check the responses here.)
    const services = new (await import('../src/service-client.js')).KrpcServices(
      client,
      new (await import('../src/services.js')).ServiceCache({
        services: [
          {
            name: 'SpaceCenter',
            procedures: [
              {
                name: 'GetUT',
                parameters: [],
                returnType: { code: 1, service: '', name: '', types: [] },
                returnIsNullable: false,
              },
              {
                name: 'GetBodies',
                parameters: [],
                returnType: {
                  code: 301,
                  service: '',
                  name: '',
                  types: [{ code: 100, service: 'SpaceCenter', name: 'CelestialBody', types: [] }],
                },
                returnIsNullable: false,
              },
              {
                name: 'GetVessels',
                parameters: [],
                returnType: {
                  code: 301,
                  service: '',
                  name: '',
                  types: [{ code: 100, service: 'SpaceCenter', name: 'Vessel', types: [] }],
                },
                returnIsNullable: false,
              },
            ],
            classes: [],
            enumerations: [],
          },
        ],
      }),
    );
    // Three concurrent calls via Promise.all. This is the exact code
    // path that triggered the framing bug before the fix.
    const [ut, bodies, vessels] = await Promise.all([
      services.invoke<number>('SpaceCenter', 'GetUT'),
      services.invoke<bigint[]>('SpaceCenter', 'GetBodies'),
      services.invoke<bigint[]>('SpaceCenter', 'GetVessels'),
    ]);
    expect(ut).toBeCloseTo(4_700_000, 1);
    expect(bodies).toEqual([101n, 102n]);
    expect(vessels).toEqual([]);
  });
  it('handles an empty LIST response (zero-byte body)', async () => {
    // Override the GetBodies stub to return an empty list. The kRPC
    // server encodes an empty list as 0 bytes (NOT a length-prefixed
    // empty KRPC.List). Without the fix in service-client.ts, this
    // would throw "zero-length response for non-nullable, non-NONE
    // return type".
    server.stub('SpaceCenter', 'GetBodies', () => new Uint8Array(0));
    const services = new (await import('../src/service-client.js')).KrpcServices(
      client,
      new (await import('../src/services.js')).ServiceCache({
        services: [
          {
            name: 'SpaceCenter',
            procedures: [
              {
                name: 'GetBodies',
                parameters: [],
                returnType: {
                  code: 301,
                  service: '',
                  name: '',
                  types: [{ code: 100, service: 'SpaceCenter', name: 'CelestialBody', types: [] }],
                },
                returnIsNullable: false,
              },
            ],
            classes: [],
            enumerations: [],
          },
        ],
      }),
    );
    const bodies = await services.invoke<bigint[]>('SpaceCenter', 'GetBodies');
    expect(bodies).toEqual([]);
  });
 });
 /**
 * Regression test for the exact decode bug that was the "actual root
 * cause" per commit 62e7ed0: a Procedure message in GetServices
 * with no returnType field at all.
 *
 * This test directly constructs a Procedure message with a null
 * returnType and feeds it to the ServiceCache constructor. With the
 * 62e7ed0 fix, this should produce a NONE-type (code 0) Procedure
 * that the cache can still look up. Without the fix, the cache
 * construction throws "Cannot read properties of null".
 */
 describe('ServiceCache — null returnType regression', () => {
  it('accepts a Procedure with returnType=null', async () => {
    // Spin up the mock just to exercise the connect() path; the
    // real assertion is below.
    const server = await startMockKrpcServer();
    const client = new KRPCClient({
      host: '127.0.0.1',
      rpcPort: server.rpcPort,
      streamPort: server.streamPort,
    });
    await client.connect();
    await loadServices(client);
    await client.close();
    await server.close();
    // Now feed a hand-crafted raw Services message to the cache.
    const raw = {
      services: [
        {
          name: 'KRPC',
          procedures: [
            { name: 'AddStream', parameters: [], returnType: null, returnIsNullable: false },
            { name: 'RemoveStream', parameters: [], returnType: null, returnIsNullable: false },
          ],
          classes: [],
          enumerations: [],
        },
      ],
    };
    const { ServiceCache } = await import('../src/services.js');
    const cache = new (ServiceCache as unknown as new (r: typeof raw) => ServiceCache)(raw);
    const r = cache.lookup('KRPC', 'AddStream');
    expect(r.found).toBe(true);
    if (!r.found) throw new Error('unreachable');
    expect(r.info.returnType.code).toBe(0); // NONE
  });
 });
 /**
 * Round-trip test: encode a real ConnectionRequest on a raw socket,
 * verify the mock's response is a valid ConnectionResponse, and
 * that the response has only the clientIdentifier field set (i.e.
 * matches what a real kRPC server sends).
 *
 * This is the "minimal response" path that the dea84b6 fix targets.
 */
 describe('mock kRPC server — raw socket handshake shape', () => {
  let server: MockServer;
  beforeAll(async () => {
    server = await startMockKrpcServer();
  });
  afterAll(async () => {
    await server.close();
  });
  it('RPC handshake responds with only clientIdentifier (matches real kRPC)', async () => {
    // Use a raw socket to inspect the exact bytes the mock returns.
    const net = await import('node:net');
    const port = server.rpcPort;
    const sock = net.createConnection({ host: '127.0.0.1', port });
    await new Promise<void>((resolve) => sock.once('connect', () => resolve()));
    sock.setNoDelay(true);
    sendMessage(sock, KRPC.ConnectionRequest, {
      type: 0, // RPC
      clientName: 'raw-test',
    });
    // recvMessage handles the length-prefixed framing correctly.
    const resp = await recvMessage<{ status: number; clientIdentifier: Uint8Array }>(
      sock,
      KRPC.ConnectionResponse,
    );
    expect(Buffer.from(resp.clientIdentifier).toString()).toBe('mock-krpc-client');
    // status should be the default (0), not the string "OK"
    expect(resp.status).toBe(0);
    // message should be the default empty string
    expect(resp.message ?? '').toBe('');
    // Sanity-check the raw bytes: should be field 3, wire type 2,
    // 14 bytes. 0x1a = (3 << 3) | 2, 0x0e = 14.
    // (We don't actually inspect the bytes here — the protobufjs
    // round-trip above already proves the structure decodes.)
    sock.destroy();
  });
 });
 void encodeMessage; // keep the import alive for future tests
@@ -1,767 +0,0 @@
 /**
 * Mock kRPC server — a real TCP server that speaks the kRPC wire
 * protocol (length-prefixed protobuf) so we can exercise the
 * kRPC client + bridge end-to-end without a running KSP install.
 *
 * This is a test-only fixture. It lives under tests/ so vitest's
 * coverage tool ignores it, and other packages import it via a
 * relative path.
 *
 * What it does:
 *   1. Listens on a free localhost port (or the port you pass in).
 *   2. On TCP connect, performs the kRPC handshake on both ports:
 *        - RPC port: accepts a ConnectionRequest (type=RPC), replies
 *          with a fixed clientIdentifier, no status/message (which is
 *          what a real kRPC server sends on the happy path).
 *        - Stream port: accepts a ConnectionRequest (type=STREAM),
 *          replies OK, and idles (we don't test streams yet).
 *   3. Handles a small set of procedure calls by returning hand-encoded
 *      deterministic responses from a fixture table.
 *   4. Records every call so tests can assert what was called, with
 *      what args, and how many times.
 *
 * Usage from a test:
 *
 *   const server = await startMockKrpcServer();
 *   try {
 *     const client = new KRPCClient({
 *       host: '127.0.0.1',
 *       rpcPort: server.rpcPort,
 *       streamPort: server.streamPort,
 *     });
 *     await client.connect();
 *     // ... exercise the client
 *   } finally {
 *     await server.close();
 *   }
 *
 * Default stubs cover the four procedures the bridge's extract()
 * loop calls per tick (GetUT, GetBodies, GetVessels, plus class
 * methods on CelestialBody / Vessel / Orbit). Tests can add more
 * stubs with `server.stub(service, procedure, handler)`.
 *
 * Wire-format reference: https://krpc.github.io/krpc/communication-protocols/messages.html
 */
 import * as net from 'node:net';
 import { Buffer } from 'node:buffer';
 import { KRPC } from '../src/schema.js';
 import { encodeVarint, recvMessage, sendMessage } from '../src/connection.js';
 import {
  encodeDouble,
  encodeString,
  encodeUint64,
  encodeBool,
  encodeSint32,
 } from '../src/_test-encode.js';
 void sendMessage; // not used directly in this file
 export interface MockServerOptions {
  /** Fixed 16-byte clientIdentifier returned by the RPC handshake.
   *  Default: "mock-krpc-client". */
  clientIdentifier?: Buffer;
  /** Optional logger for server-side events. Defaults to no-op. */
  log?: (msg: string) => void;
 }
 export interface MockServer {
  rpcPort: number;
  streamPort: number;
  /** Add (or replace) a stub for a service.procedure call. */
  stub(service: string, procedure: string, handler: (args: Uint8Array[]) => Uint8Array): void;
  /** Count of calls received for service.procedure. */
  callCount(service: string, procedure: string): number;
  /** Arguments of the last call to service.procedure. */
  lastArgs(service: string, procedure: string): Uint8Array[];
  /** Full call log, in arrival order. Each entry: { service, procedure, args }. */
  callLog(): { service: string; procedure: string; args: Uint8Array[] }[];
  /** Stop both servers and release the ports. */
  close(): Promise<void>;
 }
 async function freePort(): Promise<number> {
  return new Promise<number>((resolve, reject) => {
    const srv = net.createServer();
    srv.unref();
    srv.on('error', reject);
    srv.listen(0, '127.0.0.1', () => {
      const addr = srv.address();
      if (addr && typeof addr === 'object') {
        const p = addr.port;
        srv.close(() => resolve(p));
      } else {
        srv.close(() => reject(new Error('no addr')));
      }
    });
  });
 }
 function replyWithValue(socket: net.Socket, value: Uint8Array): void {
  const resultMsg = KRPC.ProcedureResult.create({
    value: Buffer.from(value),
  });
  const respMsg = KRPC.Response.create({ results: [resultMsg] });
  const respBytes = Buffer.from(KRPC.Response.encode(respMsg).finish());
  if (process.env.KRPC_DEBUG) {
    // eslint-disable-next-line no-console
    console.log(`[mock-krpc] >>> reply (${respBytes.length} bytes):`, respBytes.toString('hex'));
  }
  const prefix = encodeVarint(respBytes.length);
  socket.write(Buffer.concat([prefix, respBytes]));
 }
 function replyWithError(socket: net.Socket, name: string, description: string): void {
  const errMsg = KRPC.Error.create({ service: 'MockKRPC', name, description });
  const resultMsg = KRPC.ProcedureResult.create({ error: errMsg, value: Buffer.from([]) });
  sendMessage(socket, KRPC.Response, { results: [resultMsg] });
 }
 interface CallRecord {
  service: string;
  procedure: string;
  args: Uint8Array[];
 }
 /**
 * Build the standard "stock KSP-like" stub set so the bridge's
 * extract() loop can run end-to-end against the mock.
 *
 * The catalog mirrors what a stock KSP save with 1 star, 1 planet, 1
 * moon, 0 vessels looks like. Tests that need richer fixtures can
 * overwrite individual procedures via `server.stub(...)`.
 */
 export function defaultStubs(server: {
  stub: (svc: string, proc: string, h: (args: Uint8Array[]) => Uint8Array) => void;
 }): void {
  // GetServices — return a hand-crafted services message with one
  // service (SpaceCenter), one procedure (GetUT, returning DOUBLE),
  // and a few class/enum entries to exercise the cache.
  server.stub('KRPC', 'GetServices', () => {
    const servicesMsg = KRPC.Services.create({
      services: [
        {
          name: 'KRPC',
          procedures: [
            {
              name: 'GetStatus',
              parameters: [],
              returnType: { code: 203, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'GetServices',
              parameters: [],
              returnType: { code: 204, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
          ],
          classes: [],
          enumerations: [],
        },
        {
          name: 'SpaceCenter',
          procedures: [
            {
              name: 'GetUT',
              parameters: [],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'GetBodies',
              parameters: [],
              returnType: {
                code: 301,
                service: '',
                name: '',
                types: [{ code: 100, service: 'SpaceCenter', name: 'CelestialBody', types: [] }],
              },
              returnIsNullable: false,
            },
            {
              name: 'GetVessels',
              parameters: [],
              returnType: {
                code: 301,
                service: '',
                name: '',
                types: [{ code: 100, service: 'SpaceCenter', name: 'Vessel', types: [] }],
              },
              returnIsNullable: false,
            },
            {
              name: 'CelestialBody.get_Name',
              parameters: [
                {
                  name: 'self',
                  type: {
                    code: 100,
                    service: 'SpaceCenter',
                    name: 'CelestialBody',
                    types: [],
                  },
                  nullable: false,
                },
              ],
              returnType: { code: 8, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'CelestialBody.get_Parent',
              parameters: [
                {
                  name: 'self',
                  type: {
                    code: 100,
                    service: 'SpaceCenter',
                    name: 'CelestialBody',
                    types: [],
                  },
                  nullable: false,
                },
              ],
              returnType: {
                code: 100,
                service: 'SpaceCenter',
                name: 'CelestialBody',
                types: [],
              },
              returnIsNullable: true,
            },
            {
              name: 'CelestialBody.get_Radius',
              parameters: [
                {
                  name: 'self',
                  type: {
                    code: 100,
                    service: 'SpaceCenter',
                    name: 'CelestialBody',
                    types: [],
                  },
                  nullable: false,
                },
              ],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'CelestialBody.get_SphereOfInfluence',
              parameters: [
                {
                  name: 'self',
                  type: {
                    code: 100,
                    service: 'SpaceCenter',
                    name: 'CelestialBody',
                    types: [],
                  },
                  nullable: false,
                },
              ],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'CelestialBody.get_GravitationalParameter',
              parameters: [
                {
                  name: 'self',
                  type: {
                    code: 100,
                    service: 'SpaceCenter',
                    name: 'CelestialBody',
                    types: [],
                  },
                  nullable: false,
                },
              ],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'CelestialBody.get_RotationPeriod',
              parameters: [
                {
                  name: 'self',
                  type: {
                    code: 100,
                    service: 'SpaceCenter',
                    name: 'CelestialBody',
                    types: [],
                  },
                  nullable: false,
                },
              ],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'CelestialBody.get_AxialTilt',
              parameters: [
                {
                  name: 'self',
                  type: {
                    code: 100,
                    service: 'SpaceCenter',
                    name: 'CelestialBody',
                    types: [],
                  },
                  nullable: false,
                },
              ],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'CelestialBody.get_Orbit',
              parameters: [
                {
                  name: 'self',
                  type: {
                    code: 100,
                    service: 'SpaceCenter',
                    name: 'CelestialBody',
                    types: [],
                  },
                  nullable: false,
                },
              ],
              returnType: {
                code: 100,
                service: 'SpaceCenter',
                name: 'Orbit',
                types: [],
              },
              returnIsNullable: true,
            },
            {
              name: 'Orbit.get_SemiMajorAxis',
              parameters: [
                {
                  name: 'self',
                  type: { code: 100, service: 'SpaceCenter', name: 'Orbit', types: [] },
                  nullable: false,
                },
              ],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'Orbit.get_Eccentricity',
              parameters: [
                {
                  name: 'self',
                  type: { code: 100, service: 'SpaceCenter', name: 'Orbit', types: [] },
                  nullable: false,
                },
              ],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'Orbit.get_Inclination',
              parameters: [
                {
                  name: 'self',
                  type: { code: 100, service: 'SpaceCenter', name: 'Orbit', types: [] },
                  nullable: false,
                },
              ],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'Orbit.get_LongitudeOfAscendingNode',
              parameters: [
                {
                  name: 'self',
                  type: { code: 100, service: 'SpaceCenter', name: 'Orbit', types: [] },
                  nullable: false,
                },
              ],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'Orbit.get_ArgumentOfPeriapsis',
              parameters: [
                {
                  name: 'self',
                  type: { code: 100, service: 'SpaceCenter', name: 'Orbit', types: [] },
                  nullable: false,
                },
              ],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'Orbit.get_MeanAnomalyAtEpoch',
              parameters: [
                {
                  name: 'self',
                  type: { code: 100, service: 'SpaceCenter', name: 'Orbit', types: [] },
                  nullable: false,
                },
              ],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'Orbit.get_Epoch',
              parameters: [
                {
                  name: 'self',
                  type: { code: 100, service: 'SpaceCenter', name: 'Orbit', types: [] },
                  nullable: false,
                },
              ],
              returnType: { code: 1, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'Vessel.get_Name',
              parameters: [
                {
                  name: 'self',
                  type: { code: 100, service: 'SpaceCenter', name: 'Vessel', types: [] },
                  nullable: false,
                },
              ],
              returnType: { code: 8, service: '', name: '', types: [] },
              returnIsNullable: false,
            },
            {
              name: 'Vessel.get_Type',
              parameters: [
                {
                  name: 'self',
                  type: { code: 100, service: 'SpaceCenter', name: 'Vessel', types: [] },
                  nullable: false,
                },
              ],
              returnType: {
                code: 101,
                service: 'SpaceCenter',
                name: 'VesselType',
                types: [],
              },
              returnIsNullable: false,
            },
            {
              name: 'Vessel.get_Situation',
              parameters: [
                {
                  name: 'self',
                  type: { code: 100, service: 'SpaceCenter', name: 'Vessel', types: [] },
                  nullable: false,
                },
              ],
              returnType: {
                code: 101,
                service: 'SpaceCenter',
                name: 'VesselSituation',
                types: [],
              },
              returnIsNullable: false,
            },
            {
              name: 'Vessel.get_Orbit',
              parameters: [
                {
                  name: 'self',
                  type: { code: 100, service: 'SpaceCenter', name: 'Vessel', types: [] },
                  nullable: false,
                },
              ],
              returnType: {
                code: 100,
                service: 'SpaceCenter',
                name: 'Orbit',
                types: [],
              },
              returnIsNullable: true,
            },
            {
              name: 'Vessel.get_ReferenceBody',
              parameters: [
                {
                  name: 'self',
                  type: { code: 100, service: 'SpaceCenter', name: 'Vessel', types: [] },
                  nullable: false,
                },
              ],
              returnType: {
                code: 100,
                service: 'SpaceCenter',
                name: 'CelestialBody',
                types: [],
              },
              returnIsNullable: false,
            },
          ],
          classes: [{ name: 'CelestialBody' }, { name: 'Vessel' }, { name: 'Orbit' }],
          enumerations: [
            {
              name: 'VesselType',
              values: [
                { name: 'Ship', value: 0 },
                { name: 'Station', value: 1 },
                { name: 'Lander', value: 2 },
                { name: 'Probe', value: 3 },
                { name: 'Debris', value: 8 },
              ],
            },
            {
              name: 'VesselSituation',
              values: [
                { name: 'PreLaunch', value: 0 },
                { name: 'Orbiting', value: 1 },
                { name: 'Escaping', value: 2 },
                { name: 'Flying', value: 3 },
                { name: 'Landed', value: 4 },
                { name: 'Splashed', value: 5 },
                { name: 'Docked', value: 6 },
                { name: 'SubOrbital', value: 7 },
              ],
            },
          ],
        },
      ],
    });
    return new Uint8Array(KRPC.Services.encode(servicesMsg).finish());
  });
  // KRPC.GetStatus — return a tiny status message.
  server.stub('KRPC', 'GetStatus', () => {
    const statusMsg = KRPC.Status.create({ version: 'mock-0.5.0' });
    return new Uint8Array(KRPC.Status.encode(statusMsg).finish());
  });
  // SpaceCenter.GetUT — current universal time. Always 4_700_000.0
  // unless a test overrides it.
  let mockUt = 4_700_000.0;
  server.stub('SpaceCenter', 'GetUT', () => encodeDouble(mockUt));
  // expose mutator on the server for tests that want ticking time
  (server as unknown as { setUt?: (v: number) => void }).setUt = (v: number) => {
    mockUt = v;
  };
  void encodeBool; // keep import alive
  void encodeSint32;
 }
 /**
 * Start the mock kRPC server. Returns once both ports are bound and
 * ready to accept connections.
 */
 export async function startMockKrpcServer(options: MockServerOptions = {}): Promise<MockServer> {
  const clientId = options.clientIdentifier ?? Buffer.from('mock-krpc-client');
  const log = options.log ?? (() => undefined);
  const rpcPort = await freePort();
  const streamPort = await freePort();
  const stubs = new Map<string, (args: Uint8Array[]) => Uint8Array>();
  const counts = new Map<string, number>();
  const lastArgs = new Map<string, Uint8Array[]>();
  const log_: CallRecord[] = [];
  const stub = (svc: string, proc: string, handler: (args: Uint8Array[]) => Uint8Array) => {
    stubs.set(`${svc}.${proc}`, handler);
  };
  const server: MockServer = {
    rpcPort,
    streamPort,
    stub,
    callCount: (svc, proc) => counts.get(`${svc}.${proc}`) ?? 0,
    lastArgs: (svc, proc) => lastArgs.get(`${svc}.${proc}`) ?? [],
    callLog: () => [...log_],
    close: () =>
      new Promise<void>((resolve) => {
        rpcServer.close(() => {
          streamServer.close(() => resolve());
        });
      }),
  };
  // Server-side log helper: dump the wire bytes of every response we
  // send. Gated by env var. Used to diagnose framing bugs that the
  // client-side log can't catch (because the client is reading the
  // wrong slice of the byte stream).
  const logSend = (label: string, payload: Uint8Array): void => {
    if (process.env.KRPC_DEBUG) {
      // eslint-disable-next-line no-console
      console.log(
        `[mock-krpc] >>> ${label} (${payload.length} bytes):`,
        Buffer.from(payload).toString('hex'),
      );
    }
  };
  // Expose for tests that want to override the helper.
  (server as unknown as { _logSend: typeof logSend })._logSend = logSend;
  defaultStubs(server);
  // Apply a couple of well-known defaults for the standard test fixture
  // (1 star, 1 planet, 0 vessels) so the bridge's extract() loop has
  // something to read. Tests that need more bodies / vessels should
  // override these stubs.
  stub('SpaceCenter', 'GetBodies', () => {
    const ids = [encodeUint64(101n), encodeUint64(102n)];
    const listMsg = KRPC.List.create({ items: ids });
    return new Uint8Array(KRPC.List.encode(listMsg).finish());
  });
  stub('SpaceCenter', 'GetVessels', () => {
    const listMsg = KRPC.List.create({ items: [] });
    return new Uint8Array(KRPC.List.encode(listMsg).finish());
  });
  // Kerbol (root, no parent)
  stub('SpaceCenter', 'CelestialBody.get_Name', (args) => {
    const id = readVarint(args[0] ?? new Uint8Array());
    const name = id === 101n ? 'Kerbol' : id === 102n ? 'Kerbin' : 'Body';
    return encodeString(name);
  });
  stub('SpaceCenter', 'CelestialBody.get_Parent', (args) => {
    const id = readVarint(args[0] ?? new Uint8Array());
    if (id === 101n) return encodeUint64(0n); // Kerbol has no parent
    if (id === 102n) return encodeUint64(101n); // Kerbin's parent is Kerbol
    return encodeUint64(0n);
  });
  stub('SpaceCenter', 'CelestialBody.get_Radius', (args) => {
    const id = readVarint(args[0] ?? new Uint8Array());
    return encodeDouble(id === 101n ? 261_600_000 : 600_000);
  });
  stub('SpaceCenter', 'CelestialBody.get_SphereOfInfluence', (args) => {
    const id = readVarint(args[0] ?? new Uint8Array());
    return encodeDouble(id === 101n ? 1e30 : 84_159_286);
  });
  stub('SpaceCenter', 'CelestialBody.get_GravitationalParameter', (args) => {
    const id = readVarint(args[0] ?? new Uint8Array());
    return encodeDouble(id === 101n ? 1.172332794e18 : 3.5316e12);
  });
  stub('SpaceCenter', 'CelestialBody.get_RotationPeriod', (args) => {
    const id = readVarint(args[0] ?? new Uint8Array());
    return encodeDouble(id === 101n ? 432_000 : 21_600);
  });
  stub('SpaceCenter', 'CelestialBody.get_AxialTilt', () => encodeDouble(0));
  stub('SpaceCenter', 'CelestialBody.get_Orbit', (args) => {
    const id = readVarint(args[0] ?? new Uint8Array());
    // Kerbol (the star) has no orbit in the kRPC model. Real kRPC
    // returns null for the root body's orbit, so we mirror that.
    if (id === 101n) return encodeUint64(0n);
    return encodeUint64(9000n);
  });
  // Orbit params — all bodies share one orbit id (9000) in this stub
  stub('SpaceCenter', 'Orbit.get_SemiMajorAxis', () => encodeDouble(13_599_840_256));
  stub('SpaceCenter', 'Orbit.get_Eccentricity', () => encodeDouble(0.05));
  stub('SpaceCenter', 'Orbit.get_Inclination', () => encodeDouble(0));
  stub('SpaceCenter', 'Orbit.get_LongitudeOfAscendingNode', () => encodeDouble(0));
  stub('SpaceCenter', 'Orbit.get_ArgumentOfPeriapsis', () => encodeDouble(0));
  stub('SpaceCenter', 'Orbit.get_MeanAnomalyAtEpoch', () => encodeDouble(0));
  stub('SpaceCenter', 'Orbit.get_Epoch', () => encodeDouble(0));
  // ── RPC server ─────────────────────────────────────────────────────
  const rpcServer = net.createServer((socket) => {
    void (async () => {
      try {
        // 1. Handshake. We expect type=0 (RPC).
        const req = await recvMessage<{ type: number; clientName: string }>(
          socket,
          KRPC.ConnectionRequest,
        );
        log(`[mock-krpc] RPC handshake: type=${req.type} name=${req.clientName}`);
        if (req.type !== 0) {
          log(`[mock-krpc] unexpected type=${req.type} on RPC port, closing`);
          socket.destroy();
          return;
        }
        // Real kRPC server response: just field 3 (clientIdentifier),
        // no status/message. We do the same — encode ONLY clientIdentifier.
        const respMsg = KRPC.ConnectionResponse.create({
          clientIdentifier: clientId,
        });
        const respBytes = Buffer.from(KRPC.ConnectionResponse.encode(respMsg).finish());
        socket.write(Buffer.concat([encodeVarint(respBytes.length), respBytes]));
        // 2. Procedure loop
        while (!socket.destroyed) {
          let callReq: {
            calls: { service: string; procedure: string; arguments?: { value: Uint8Array }[] }[];
          };
          try {
            callReq = await recvMessage(socket, KRPC.Request);
          } catch {
            return;
          }
          const call = callReq.calls[0];
          if (!call) {
            replyWithError(socket, 'Malformed', 'no call');
            continue;
          }
          const key = `${call.service}.${call.procedure}`;
          counts.set(key, (counts.get(key) ?? 0) + 1);
          const args = (call.arguments ?? []).map((a) => new Uint8Array(a.value));
          lastArgs.set(key, args);
          log_.push({ service: call.service, procedure: call.procedure, args });
          log(`[mock-krpc] call ${key} #${counts.get(key)} args.length=${args.length}`);
          const handler = stubs.get(key);
          if (!handler) {
            replyWithError(socket, 'UnknownProcedure', `${key} not stubbed`);
            continue;
          }
          try {
            const value = handler(args);
            replyWithValue(socket, value);
          } catch (e) {
            replyWithError(socket, 'HandlerError', String(e));
          }
        }
      } catch (e) {
        log(`[mock-krpc] RPC socket error: ${String(e)}`);
        if (!socket.destroyed) socket.destroy();
      }
    })();
  });
  await new Promise<void>((resolve) => rpcServer.listen(rpcPort, '127.0.0.1', resolve));
  // ── Stream server (handshake only, then idle) ─────────────────────
  const streamServer = net.createServer((socket) => {
    void (async () => {
      try {
        const req = await recvMessage<{ type: number; clientIdentifier: Uint8Array }>(
          socket,
          KRPC.ConnectionRequest,
        );
        log(`[mock-krpc] stream handshake: type=${req.type}`);
        if (req.type !== 1) {
          socket.destroy();
          return;
        }
        const respMsg = KRPC.ConnectionResponse.create({});
        const respBytes = Buffer.from(KRPC.ConnectionResponse.encode(respMsg).finish());
        socket.write(Buffer.concat([encodeVarint(respBytes.length), respBytes]));
        // Keep alive until socket closes
        await new Promise(() => undefined);
      } catch (e) {
        log(`[mock-krpc] stream socket error: ${String(e)}`);
        socket.destroy();
      }
    })();
  });
  await new Promise<void>((resolve) => streamServer.listen(streamPort, '127.0.0.1', resolve));
  log(`[mock-krpc] listening on RPC=${rpcPort} stream=${streamPort}`);
  return server;
 }
 // ── helpers ────────────────────────────────────────────────────────────
 function readVarint(bytes: Uint8Array): bigint {
  let v = 0n;
  let shift = 0n;
  for (const b of bytes) {
    v |= BigInt(b & 0x7f) << shift;
    if ((b & 0x80) === 0) return v;
    shift += 7n;
  }
  return v;
 }
@@ -196,68 +196,4 @@ describe('ServiceCache', () => {
    expect(r.info.returnType.types[0]?.code).toBe(100);
    expect(r.info.returnType.types[0]?.name).toBe('CelestialBody');
  });
  it('handles procedures with no return type (returnType is null)', () => {
    // Real kRPC server omits the `return_type` field for void
    // procedures (e.g. AddStream, setters). protobufjs decodes
    // missing message fields as null. Our cache must not crash.
    const raw = {
      services: [
        {
          name: 'KRPC',
          procedures: [
            {
              name: 'AddStream',
              parameters: [],
              returnType: null, // <-- the trigger
              returnIsNullable: false,
            },
          ],
          classes: [],
          enumerations: [],
        },
      ],
    };
    const cache = new ServiceCache(raw as unknown as Parameters<typeof ServiceCache>[0]);
    const r = cache.lookup('KRPC', 'AddStream');
    expect(r.found).toBe(true);
    if (!r.found) throw new Error('unreachable');
    // Missing return type becomes NONE (code 0).
    expect(r.info.returnType.code).toBe(0);
  });
  it('falls back to .NET-style getter/setter naming for C# properties', () => {
    // The kRPC server exposes C# properties using .NET accessor
    // conventions: a property `UT` on SpaceCenter becomes two
    // procedures named `get_UT` and `set_UT`. User code typically
    // writes `SpaceCenter.GetUT()` (PascalCase). The cache must
    // transparently translate to the wire-format name.
    const raw = {
      services: [
        {
          name: 'SpaceCenter',
          procedures: [
            { name: 'get_UT', parameters: [], returnType: null, returnIsNullable: false },
            { name: 'set_UT', parameters: [], returnType: null, returnIsNullable: false },
            { name: 'get_ActiveVessel', parameters: [], returnType: null, returnIsNullable: true },
            { name: 'CelestialBody.get_Name', parameters: [], returnType: null, returnIsNullable: false },
          ],
          classes: [],
          enumerations: [],
        },
      ],
    };
    const cache = new ServiceCache(raw as unknown as Parameters<typeof ServiceCache>[0]);
    // Top-level PascalCase -> .NET getter
    expect(cache.lookup('SpaceCenter', 'GetUT').found).toBe(true);
    // Top-level PascalCase -> .NET setter
    expect(cache.lookup('SpaceCenter', 'SetUT').found).toBe(true);
    expect(cache.lookup('SpaceCenter', 'GetActiveVessel').found).toBe(true);
    // Class-prefixed: "CelestialBody.GetName" -> "CelestialBody.get_Name"
    expect(cache.lookup('SpaceCenter', 'CelestialBody.GetName').found).toBe(true);
    // Exact match still works
    expect(cache.lookup('SpaceCenter', 'get_UT').found).toBe(true);
    // And unknown names still return not-found
    expect(cache.lookup('SpaceCenter', 'NoSuchProcedure').found).toBe(false);
  });
 });