Fix review issues: package-private internals, update stale docs

Make UvRunner and PythonProbe package-private — they are internal
implementation details used by PythonEnv, not part of the public API.

Update api-contracts.md to match the actual implemented API (remove
unimplemented load/importModule/PythonSource, show real PythonEngine,
PythonEnv, HostFunction, and @ScriptInterface usage).

Update implementation-plan.md to mark Phases 1-3 as done.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: andreaTP

core/src/main/java/io/roastedroot/cpython4j/core/PythonProbe.java

@@ -7,7 +7,7 @@
 import java.nio.file.Path;
 import java.util.concurrent.TimeUnit;
 
-public final class PythonProbe {
+final class PythonProbe {
     private static final String PROBE_SCRIPT =
             "import sys, sysconfig, json; print(json.dumps({"
                     + "'version': list(sys.version_info[:3]),"
@@ -21,7 +21,7 @@ public final class PythonProbe {
 
     private PythonProbe() {}
 
-    public static Result probe(Path venvDir) {
+    static Result probe(Path venvDir) {
         var pythonBin = resolvePythonBin(venvDir);
         if (!Files.isExecutable(pythonBin)) {
             throw new RuntimeException(
@@ -99,5 +99,5 @@ private static Result parseResult(String json) {
         }
     }
 
-    public record Result(Path libPythonPath, Path purelib, Path platlib, String version) {}
+    record Result(Path libPythonPath, Path purelib, Path platlib, String version) {}
 }

core/src/main/java/io/roastedroot/cpython4j/core/UvRunner.java

@@ -6,12 +6,12 @@
 import java.util.List;
 import java.util.concurrent.TimeUnit;
 
-public final class UvRunner {
+final class UvRunner {
     private static final long TIMEOUT_SECONDS = 300;
 
     private UvRunner() {}
 
-    public static void sync(Path projectDir) {
+    static void sync(Path projectDir) {
         run(projectDir, "sync", "--python-preference", "managed");
     }
 

docs/api-contracts.md

@@ -1,27 +1,43 @@
 # Contract-first API Design
 
-## Primary Java API
+## PythonEngine API
 
 ```java
-public interface PythonEngine extends AutoCloseable {
-    static PythonEngine create(PythonEnv env) { ... }
+public final class PythonEngine implements AutoCloseable {
+    public static PythonEngine create(PythonEnv env);
+    public static Builder builder();
 
-    <T> T load(Class<T> guestContract, PythonSource source);
+    public int exec(String code);
+    public <T> T invokeFunction(String moduleName, String functionName, List<Object> args, Class<T> returnType);
 
-    <T> T importModule(Class<T> guestContract, String moduleName);
-
-    <T> void expose(String moduleName, Class<T> hostContract, T implementation);
+    public void close();
 }
 ```
 
-## PythonSource
+## PythonEngine.Builder
 
 ```java
-public sealed interface PythonSource {
-    static PythonSource file(Path path) { ... }
-    static PythonSource code(String code) { ... }
-    static PythonSource module(String moduleName) { ... }
-}
+PythonEngine.Builder builder = PythonEngine.builder()
+    .withEnv(env)
+    .withObjectMapper(mapper)
+    .expose("host", hostFunction1, hostFunction2)
+    .build();
+```
+
+## PythonEnv
+
+```java
+// Option A: uv project (syncs on first run)
+PythonEnv env = PythonEnv.uvProject(Path.of(".")).sync(true).build();
+
+// Option B: existing venv
+PythonEnv env = PythonEnv.venv(Path.of(".venv")).build();
+
+// Option C: explicit paths (container / air-gapped)
+PythonEnv env = PythonEnv.explicit()
+    .library(Path.of("/usr/lib/libpython3.13.so"))
+    .sitePackages(Path.of("/app/.venv/lib/python3.13/site-packages"))
+    .build();
 ```
 
 ## Guest contract example
@@ -32,12 +48,16 @@ Java defines the contract:
 public record Document(String text, String source) {}
 public record Analysis(String language, int wordCount) {}
 
+@ScriptInterface(module = "analyzer")
 public interface Analyzer {
     Analysis analyze(Document document);
     List<String> keywords(String text);
+    int wordCount(String text);
 }
 ```
 
+The annotation processor generates `Analyzer_Proxy` at compile time (no reflection).
+
 Python implements it:
 
 ```python
@@ -49,34 +69,39 @@ def analyze(document):
 
 def keywords(text):
     return text.lower().split()[:5]
+
+def wordCount(text):
+    return len(text.split())
 ```
 
 Java loads it:
 
 ```java
-Analyzer analyzer = engine.load(
-    Analyzer.class,
-    PythonSource.file(Path.of("analyzer.py"))
-);
+var env = PythonEnv.uvProject(Path.of(".")).sync(true).build();
+try (var engine = PythonEngine.create(env)) {
+    engine.exec("import sys; sys.path.insert(0, '.')");
+    Analyzer analyzer = new Analyzer_Proxy(engine);
+    Analysis result = analyzer.analyze(new Document("Hello", "demo"));
+}
 ```
 
 ## Host contract example
 
-Java defines a host API:
+Java exposes functions to Python:
 
 ```java
-public interface HostApi {
-    void log(String message);
-    User findUser(String id);
+try (var engine = PythonEngine.builder()
+        .withEnv(env)
+        .expose("host",
+            new HostFunction("log", List.of(String.class), Void.class,
+                args -> { System.out.println(args.get(0)); return null; }),
+            new HostFunction("findUser", List.of(String.class), User.class,
+                args -> userService.find((String) args.get(0))))
+        .build()) {
+    // ...
 }
 ```
 
-Java exposes it:
-
-```java
-engine.expose("host", HostApi.class, hostImpl);
-```
-
 Python imports it as a normal module:
 
 ```python
@@ -88,29 +113,13 @@ def run(id):
     return user
 ```
 
-## Bundled mode example
-
-```java
-try (var engine = PythonEngine.create(PythonEnv.bundled().sync(true))) {
-    Docling docling = engine.load(
-        Docling.class,
-        PythonSource.module("docling_bridge")
-    );
-    Document doc = docling.convert(Path.of("report.pdf"));
-}
-```
-
-The `bundled()` mode extracts `pyproject.toml` and `uv.lock` from JAR resources, bootstraps CPython and dependencies on first run via uv, and caches the environment locally for subsequent runs.
-
 ## Low-level escape hatch
 
-The low-level API is optional and secondary:
+The low-level API is available for tests, diagnostics, and simple scripts:
 
 ```java
-public interface PythonSession {
-    void exec(String code);
-    Object eval(String expression);
+try (var engine = PythonEngine.create(env)) {
+    engine.exec("print('hello')");
+    int count = engine.invokeFunction("my_module", "count", List.of("hello world"), int.class);
 }
 ```
-
-This is useful for tests, diagnostics, and simple scripts, but documentation should lead with Java contracts.

docs/implementation-plan.md

@@ -8,16 +8,16 @@ Many patterns transfer directly from QuickJs4J: the contract-first API (Builtins
 
 Core functionality (Phases 1–6): ~2–3 weeks.
 
-| Phase | Estimate | QuickJs4J reuse |
+| Phase | Status | QuickJs4J reuse |
 |---|---|---|
 | 0. Docs & design | done | — |
-| 1. FFM smoke test + callbacks | 2–3 days | — (new: FFM, upcalls, PyMethodDef/PyModuleDef via MemorySegment) |
-| 2. Env resolver | 2–3 days | — (new: uv/venv/libpython discovery) |
-| 3. Contract loader with callbacks | 2–3 days | high (proxy, JSON conversion, ObjectMapper, dispatcher) |
-| 4. JSON hardening | 1–2 days | high (same Jackson patterns, mostly edge-case testing) |
-| 5. Battery-included | 2–3 days | — (new: uv bootstrap, cache) |
+| 1. FFM smoke test + callbacks | done | — |
+| 2. Env resolver | done | — |
+| 3. Contract loader with callbacks | done | high (AP, JSON conversion, dispatcher) |
+| 4. JSON hardening | next | high (same Jackson patterns, edge-case testing) |
+| 5. Battery-included | pending | — (new: uv bootstrap, cache) |
 | 6. Build plugins | optional | medium (Maven plugin structure) |
-| 7. Platform hardening | 3–5 days | low (platform-specific libpython, CI matrix) |
+| 7. Platform hardening | pending | low (platform-specific libpython, CI matrix) |
 | 8. Optional layers | later | high (annotations, processors) |
 
 ## Phase 0: Documentation and design lock