Fix 6 LLM-friendliness inconsistencies in Phase 4 implementation steps

- Remove FfiTransportException from 4.3 (superseded by 3.10 resolution)
- Rewrite 4.5 to use RuntimeConnection hierarchy (not rejected Transport enum)
- Fix 4.7 file path to post-restructure java/sdk/src/ location
- Add path note at 4.1 explaining src/ vs sdk/src/ relationship with 4.6a
- Expand --no-auto-update invariant in 3.9 with ABI-skew rationale
- Fix NativeSize to com.sun.jna.NativeLong in FfiOutputStream example

Author: edburns

1917-java-embed-rust-cli-runtime-remove-before-merge/1917-embed-cli-runtime-ignorance-reduction-plan.md

@@ -390,7 +390,7 @@ class FfiOutputStream extends OutputStream {
     @Override
     public void write(byte[] b, int off, int len) throws IOException {
         byte[] slice = (off == 0 && len == b.length) ? b : Arrays.copyOfRange(b, off, off + len);
-        if (!lib.copilot_runtime_connection_write(connectionId, slice, new NativeSize(len))) {
+        if (!lib.copilot_runtime_connection_write(connectionId, slice, new com.sun.jna.NativeLong(len))) {
             throw new IOException("copilot_runtime_connection_write failed");
         }
     }
@@ -631,7 +631,7 @@ Complete `env_json` key inventory (these are the **only** three keys used across
 
 **Three key invariants:**
 
-1. **`argv_json` must never be null.** It always contains at least `[entrypoint, "--embedded-host", "--no-auto-update"]`.
+1. **`argv_json` must never be null.** It always contains at least `[entrypoint, "--embedded-host", "--no-auto-update"]`. **`--no-auto-update` is mandatory** — it pins the worker to the bundled cdylib version, preventing ABI skew between the loaded library and the runtime worker. Omitting it allows the runtime to drift to a newer `~/.copilot/pkg` version whose ABI may be incompatible with the loaded cdylib.
 2. **`env_json` can be null** (with `env_json_len = 0`) when no environment overrides are needed.
 3. **All three metadata buffers (`ext_source`, `ext_name`, `conn_token`) are always null/0.** No current SDK uses them; they are reserved extension points.
 
@@ -940,7 +940,7 @@ Every implementation step in this phase **must** follow this test-driven workflo
 1. **Write tests first.** Before writing or modifying production code for a step, write the unit tests (and integration tests where specified) that define the expected behavior. Tests should initially fail (red).
 
    The test native library from `spike-3-4-jna-callback-and-threading/rust-dll/` is the test fixture for steps 4.3 and 4.4. Build it once with `cargo build --release` for the current OS and architecture and place the output at a known path before writing Java tests.
-   
+
 2. **Implement until green.** Write the minimum production code to make all tests pass.
 3. **Refactor.** Clean up the implementation while keeping tests green. Run `mvn spotless:apply` to ensure formatting compliance.
 4. **Gate before proceeding.** All tests from the current step **and all prior steps** must pass (`mvn verify`) before moving to the next step. Do not proceed with a step if any prior step's tests are broken.
@@ -956,6 +956,8 @@ Every implementation step in this phase **must** follow this test-driven workflo
 
 **What:** `PlatformDetector` class that determines `os`, `arch`, `libc` and produces the classifier string.
 
+> **Path note:** Steps 4.1–4.5 list file paths as `java/src/...`. After step 4.6a (reactor restructure), these become `java/sdk/src/...`. If 4.6a is performed first, use the `java/sdk/src/...` paths. If 4.6a is performed after, the files will be moved during 4.6a.
+
 **Files to create:**
 
 - `java/src/main/java/com/github/copilot/ffi/PlatformDetector.java`
@@ -978,11 +980,11 @@ Every implementation step in this phase **must** follow this test-driven workflo
 
 - `java/src/test/java/com/github/copilot/ffi/NativeRuntimeLoaderTest.java`
 
-**Gating criteria:** 
+**Gating criteria:**
 
 - Extracts binary to `~/.copilot/runtime-cache/<version>/<classifier>/runtime.node`. Handles concurrent extraction safely.
 
-- When *multiple* platform JARs are on the classpath (uber-jar scenario), it sorts candidates and picks the best match. The plan's `NativeRuntimeLoader` should handle this case — in the `copilot-native-all` uber-JAR, all 8 `native/<classifier>/runtime.node` resources exist on the classpath simultaneously. The loader must filter by the detected classifier, not just grab the first `runtime.node` it finds. ❌❌❌We are not doing the uber-jar approach now, but we want to do it in the future, so we must be ready for it.❌❌❌
+- When _multiple_ platform JARs are on the classpath (uber-jar scenario), it sorts candidates and picks the best match. The plan's `NativeRuntimeLoader` should handle this case — in the `copilot-native-all` uber-JAR, all 8 `native/<classifier>/runtime.node` resources exist on the classpath simultaneously. The loader must filter by the detected classifier, not just grab the first `runtime.node` it finds. ❌❌❌We are not doing the uber-jar approach now, but we want to do it in the future, so we must be ready for it.❌❌❌
 
 ### 4.3 — JNA binding interface and implementation
 
@@ -993,17 +995,16 @@ Every implementation step in this phase **must** follow this test-driven workflo
 - `java/src/main/java/com/github/copilot/ffi/NativeBinding.java`
 - `java/src/main/java/com/github/copilot/ffi/JnaNativeBinding.java`
 - `java/src/main/java/com/github/copilot/ffi/OutboundCallback.java`
-- `java/src/main/java/com/github/copilot/ffi/FfiTransportException.java`
 
 **Tests:** Unit tests using a test native library with minimal C ABI (or mock/spy on JNA calls).
 
 - `java/src/test/java/com/github/copilot/ffi/JnaNativeBindingTest.java`
 
-**Gating criteria:** 
+**Gating criteria:**
 
-- Can load a native library, call functions, receive callbacks. Error cases wrapped in `FfiTransportException`.
+- Can load a native library, call functions, receive callbacks. Error cases throw `IllegalStateException` (see 3.10 resolution — no dedicated `FfiTransportException`).
 
-- **Library-never-unloads pattern** — the loaded native handle must be held in a `static` field and never released. JNA caches by library name, but the plan should make this explicit since native worker threads outlive any `FfiRuntimeHost` instance. See Rust `OnceLock<Mutex<HashMap<PathBuf, &'static Library>>>` + `Box::leak()` Missing this risks a crash if a second `FfiRuntimeHost` is created after the first is closed. 
+- **Library-never-unloads pattern** — the loaded native handle must be held in a `static` field and never released. JNA caches by library name, but the plan should make this explicit since native worker threads outlive any `FfiRuntimeHost` instance. See Rust `OnceLock<Mutex<HashMap<PathBuf, &'static Library>>>` + `Box::leak()` Missing this risks a crash if a second `FfiRuntimeHost` is created after the first is closed.
 
 ### 4.4 — FFI runtime host and transport streams
 
@@ -1023,34 +1024,38 @@ Every implementation step in this phase **must** follow this test-driven workflo
 
 - **Callback `closing` flag early-exit** — the `on_outbound` callback must check a `closing` flag and return immediately without enqueuing data. Without this, the shutdown drain may never converge. Both .NET and Rust set this flag before `connection_close`. Failing to do this can caus a hang on shutdown.
 
-- **Operation lock for concurrent write/close safety** — `FfiOutputStream.write()` can race with `FfiRuntimeHost.close()`. See how the Rust SDK uses a `parking_lot::Mutex` (`operation_lock`). See the Rust SDK `FfiShared`. Failing to do this can cause a  data race during shutdown.
+- **Operation lock for concurrent write/close safety** — `FfiOutputStream.write()` can race with `FfiRuntimeHost.close()`. See how the Rust SDK uses a `parking_lot::Mutex` (`operation_lock`). See the Rust SDK `FfiShared`. Failing to do this can cause a data race during shutdown.
 
-- **`Connection` record needs `FfiRuntimeHost` field** — the current `CopilotClient.Connection` record has `(JsonRpcClient rpc, Process process, ServerRpc serverRpc)`. InProcess has no `Process`. Without an `ffiHost` field, `stop()` and `forceStop()` can't call `ffiHost.close()`. .NET's `Connection` record includes `FfiRuntimeHost? ffiHost`.  Failure to do this can cause a leak of native resources on shutdown.
+- **`Connection` record needs `FfiRuntimeHost` field** — the current `CopilotClient.Connection` record has `(JsonRpcClient rpc, Process process, ServerRpc serverRpc)`. InProcess has no `Process`. Without an `ffiHost` field, `stop()` and `forceStop()` can't call `ffiHost.close()`. .NET's `Connection` record includes `FfiRuntimeHost? ffiHost`. Failure to do this can cause a leak of native resources on shutdown.
 
 ### 4.5 — Transport integration with `CopilotClient`
 
-**What:** `Transport` enum, `setTransport()` on `CopilotClientOptions`, InProcess code path in `CopilotClient` that uses `FfiRuntimeHost` instead of `CliServerManager`.
+**What:** `RuntimeConnection` sealed class hierarchy (see 3.5.1 resolution), `setConnection()` on `CopilotClientOptions`, InProcess code path in `CopilotClient` that uses `FfiRuntimeHost` instead of `CliServerManager`. **Do NOT create a `Transport` enum or `setTransport()` method — that approach was explicitly rejected in the 3.5.1 resolution in favor of the `RuntimeConnection` type hierarchy.**
 
-✅✅Remember to handle **`COPILOT_SDK_DEFAULT_CONNECTION` env var resolution in `CopilotClient` constructor**. `CopilotClient` must implement `resolveDefaultConnection()` when no `connection` is set. See NET Client.cs — search for `ResolveDefaultConnection` (private static method) and its caller `_options.Connection ?? ResolveDefaultConnection(_options)`; Rust lib.rs — search for `fn resolve_default_transport` and constant `DEFAULT_CONNECTION_ENV_VAR`.
+✅✅Remember to handle **`COPILOT_SDK_DEFAULT_CONNECTION` env var resolution in `CopilotClient` constructor**. `CopilotClient` must implement `resolveDefaultConnection()` when no `connection` is set. See .NET `dotnet/src/Client.cs` — search for `ResolveDefaultConnection` (private static method) and its caller `_options.Connection ?? ResolveDefaultConnection(_options)`; Rust `rust/src/lib.rs` — search for `fn resolve_default_transport` and constant `DEFAULT_CONNECTION_ENV_VAR`.
 
-✅✅Remember: **`ValidateEnvironmentOptions` — reject incompatible options for InProcess** — `environment`, `telemetry`, `workingDirectory`, `extraArgs` must be rejected when InProcess is selected. Without this, users set options that silently do nothing in-process. See .NET Client.cs — search for `ValidateEnvironmentOptions` (private static method, called right after `ResolveDefaultConnection`); Rust lib.rs — search for `fn validate_inprocess_options`.
+✅✅Remember: **`ValidateEnvironmentOptions` — reject incompatible options for InProcess** — `environment`, `telemetry`, `workingDirectory`, `extraArgs` must be rejected when InProcess is selected. Without this, users set options that silently do nothing in-process. See .NET `dotnet/src/Client.cs` — search for `ValidateEnvironmentOptions` (private static method, called right after `ResolveDefaultConnection`); Rust `rust/src/lib.rs` — search for `fn validate_inprocess_options`.
 
 **Files to modify:**
 
-- `java/src/main/java/com/github/copilot/rpc/CopilotClientOptions.java` — add `transport` field
-- `java/src/main/java/com/github/copilot/CopilotClient.java` — InProcess connection path
+- `java/src/main/java/com/github/copilot/rpc/CopilotClientOptions.java` — add `connection` field (type `RuntimeConnection`, nullable, default `null`)
+- `java/src/main/java/com/github/copilot/CopilotClient.java` — InProcess connection path via `RuntimeConnection` dispatch
 
 **Files to create:**
 
-- `java/src/main/java/com/github/copilot/ffi/Transport.java`
+- `java/src/main/java/com/github/copilot/rpc/RuntimeConnection.java` — sealed class with factory methods (see 3.5.1 resolution)
+- `java/src/main/java/com/github/copilot/rpc/StdioRuntimeConnection.java`
+- `java/src/main/java/com/github/copilot/rpc/TcpRuntimeConnection.java`
+- `java/src/main/java/com/github/copilot/rpc/UriRuntimeConnection.java`
+- `java/src/main/java/com/github/copilot/rpc/InProcessRuntimeConnection.java`
 
 **Tests:** Unit test that InProcess transport selection uses `FfiRuntimeHost`.
 
-   ✅✅✅Test the backward-compatibility bridge (legacy fields → `RuntimeConnection` inference) and the `IllegalArgumentException` when both `connection` and legacy fields are set.✅✅✅
+✅✅✅Test the backward-compatibility bridge (legacy fields → `RuntimeConnection` inference) and the `IllegalArgumentException` when both `connection` and legacy fields are set.✅✅✅
 
 - `java/src/test/java/com/github/copilot/CopilotClientTransportTest.java`
 
-**Gating criteria:** `new CopilotClientOptions().setTransport(Transport.IN_PROCESS)` routes through FFI host. `COPILOT_SDK_DEFAULT_CONNECTION=inprocess` env var works. CLI transport unchanged.
+**Gating criteria:** `new CopilotClientOptions().setConnection(RuntimeConnection.forInProcess())` routes through FFI host. `COPILOT_SDK_DEFAULT_CONNECTION=inprocess` env var works. CLI transport unchanged.
 
 ### 4.6 — Multi-module reactor restructure and per-platform classifier JARs
 
@@ -1125,7 +1130,7 @@ version=${project.version}
 
 **Files to create:**
 
-- `java/src/test/java/com/github/copilot/e2e/InProcessTransportIT.java`
+- `java/sdk/src/test/java/com/github/copilot/e2e/InProcessTransportIT.java` _(note: `sdk/` prefix — this path is post-4.6a restructure)_
 
 **Snapshot files:** Reuse existing snapshots or create new ones as needed.