Merge pull request #14 from robocode-dev/ch-009-m004-file-io-sandboxing

CH-009: confine robot file I/O to the data directory

Author: flemming-n-larsen

.clue/id-ledger.yaml

@@ -5,12 +5,13 @@ counters:
     ARCH: "3"
     C: "7"
     CAP: "8"
-    CH: "8"
+    CH: "9"
     CRIT: "8"
     DES: "8"
     EVT: "15"
+    FIO: "4"
     G: "2"
-    IDR: "6"
+    IDR: "7"
     OQ: "4"
     P: "1"
     PDR: "2"
@@ -243,6 +244,11 @@ entries:
       state: reserved
       prefix: CH
       component: "8"
+    - id: CH-009
+      kind: numeric
+      state: live
+      prefix: CH
+      component: "9"
     - id: CRIT-001
       kind: numeric
       state: live
@@ -398,6 +404,26 @@ entries:
       state: live
       prefix: EVT
       component: "15"
+    - id: FIO-001
+      kind: numeric
+      state: live
+      prefix: FIO
+      component: "1"
+    - id: FIO-002
+      kind: numeric
+      state: live
+      prefix: FIO
+      component: "2"
+    - id: FIO-003
+      kind: numeric
+      state: live
+      prefix: FIO
+      component: "3"
+    - id: FIO-004
+      kind: numeric
+      state: live
+      prefix: FIO
+      component: "4"
     - id: G-001
       kind: numeric
       state: live
@@ -438,6 +464,11 @@ entries:
       state: live
       prefix: IDR
       component: "6"
+    - id: IDR-007
+      kind: numeric
+      state: live
+      prefix: IDR
+      component: "7"
     - id: OQ-001
       kind: numeric
       state: live

compat-test/conformance-robots/conformance/probes/FileQuotaProbe.java

@@ -0,0 +1,48 @@
+package conformance.probes;
+
+import robocode.AdvancedRobot;
+import robocode.RobocodeFileOutputStream;
+
+import java.io.File;
+import java.io.IOException;
+
+/**
+ * Ported from classic's {@code tested.robots.FileWriteSize}: writes three 100000-byte
+ * chunks against the documented 200000-byte quota, so the third write must be refused at
+ * exactly the point classic refuses it.
+ */
+public class FileQuotaProbe extends AdvancedRobot {
+
+    @Override
+    public void run() {
+        out.println("DataQuota:" + getDataQuotaAvailable());
+
+        byte[] chunk = new byte[100_000];
+        File file = getDataFile("quota-test");
+        file.delete();
+
+        RobocodeFileOutputStream stream = null;
+        try {
+            stream = new RobocodeFileOutputStream(file);
+            for (int i = 0; i < 3; i++) {
+                stream.write(chunk);
+                out.println("WroteChunk:" + i);
+            }
+        } catch (IOException e) {
+            out.println("QuotaExceeded:" + e.getMessage());
+        } finally {
+            if (stream != null) {
+                try {
+                    stream.close();
+                } catch (IOException ignored) {
+                    // already reported above
+                }
+            }
+            file.delete();
+        }
+
+        while (true) {
+            turnLeft(1);
+        }
+    }
+}

compat-test/conformance-robots/conformance/probes/FileRedirectionProbe.java

@@ -0,0 +1,50 @@
+package conformance.probes;
+
+import robocode.AdvancedRobot;
+import robocode.RobocodeFileOutputStream;
+
+import java.io.File;
+import java.io.IOException;
+
+/**
+ * Writes through {@code getDataFile} with a plain name and with a root-relative name that
+ * looks like it escapes the data directory, then reports what was resolved and what the
+ * directory listing sees, so a conformance test can prove the two calls agree.
+ */
+public class FileRedirectionProbe extends AdvancedRobot {
+
+    @Override
+    public void run() {
+        out.println("DataDirectory:" + getDataDirectory().getAbsolutePath());
+        writeAndReport("plain-name.txt");
+        writeAndReport("/root-relative-name.txt");
+        listDirectory();
+        while (true) {
+            turnLeft(1);
+        }
+    }
+
+    private void writeAndReport(String name) {
+        try {
+            File file = getDataFile(name);
+            out.println("Resolved:" + name + ":" + file.getAbsolutePath());
+            try (RobocodeFileOutputStream stream = new RobocodeFileOutputStream(file)) {
+                stream.write(42);
+            }
+            out.println("WriteSucceeded:" + name + ":" + file.exists());
+        } catch (IOException | SecurityException e) {
+            out.println("WriteFailed:" + name + ":" + e);
+        }
+    }
+
+    private void listDirectory() {
+        File[] files = getDataDirectory().listFiles();
+        if (files == null) {
+            out.println("DirectoryListing:none");
+            return;
+        }
+        for (File file : files) {
+            out.println("DirectoryListing:" + file.getName());
+        }
+    }
+}

conformance-test/src/test/java/dev/robocode/tankroyale/bridge/conformance/FileQuotaConformanceTest.java

@@ -0,0 +1,46 @@
+package dev.robocode.tankroyale.bridge.conformance;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.nio.file.Path;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Acceptance evidence for FIO-003 — a robot's data directory is capped at the classic
+ * 200000-byte size limit, refused at the same point classic refuses it.
+ */
+class FileQuotaConformanceTest extends ConformanceTestBase {
+
+    private static final String ROBOT = "conformance.probes.FileQuotaProbe";
+    private static final Path SOURCE = ConformanceHarness.repoRoot().resolve(Path.of(
+            "compat-test", "conformance-robots", "conformance", "probes", "FileQuotaProbe.java"));
+
+    @Test
+    @DisplayName("FIO-003: a write past the quota is refused with classic's own message")
+    void testFIO003_IntegrationPositive_WritePastQuotaIsRefused() {
+        assertOnBothEngines(ROBOT, SOURCE, (outcome, engine) -> {
+            assertTrue(outcome.anyConsoleContains("DataQuota:200000"),
+                    () -> "the documented quota was not reported as 200000 on " + engine
+                            + " (" + outcome.summary() + ")");
+            assertTrue(outcome.anyConsoleContains("WroteChunk:0") && outcome.anyConsoleContains("WroteChunk:1"),
+                    () -> "the first two chunks, which fit inside the quota, did not both write on " + engine
+                            + " (" + outcome.summary() + ")");
+            assertTrue(outcome.anyConsoleContains("QuotaExceeded:")
+                            && outcome.anyConsoleContains("200000 bytes"),
+                    () -> "the third chunk was not refused with the classic quota message on " + engine
+                            + " (" + outcome.summary() + ")");
+        });
+    }
+
+    @Test
+    @DisplayName("FIO-003 negative: the write that exceeds the quota does not also succeed")
+    void testFIO003_IntegrationNegative_TheRefusedChunkDoesNotAlsoReportSuccess() {
+        assertOnBothEngines(ROBOT, SOURCE, (outcome, engine) ->
+                assertFalse(outcome.anyConsoleContains("WroteChunk:2"),
+                        () -> "the third, quota-exceeding chunk reported as written on " + engine
+                                + " (" + outcome.summary() + ")"));
+    }
+}

conformance-test/src/test/java/dev/robocode/tankroyale/bridge/conformance/FileRedirectionConformanceTest.java

@@ -0,0 +1,73 @@
+package dev.robocode.tankroyale.bridge.conformance;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.nio.file.Path;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Acceptance evidence for FIO-001 and FIO-002 — a root-relative path a robot names is
+ * redirected into its data directory, and {@code getDataFile} and {@code getDataDirectory}
+ * agree about where that directory is.
+ */
+class FileRedirectionConformanceTest extends ConformanceTestBase {
+
+    private static final String ROBOT = "conformance.probes.FileRedirectionProbe";
+    private static final Path SOURCE = ConformanceHarness.repoRoot().resolve(Path.of(
+            "compat-test", "conformance-robots", "conformance", "probes", "FileRedirectionProbe.java"));
+
+    @Test
+    @DisplayName("FIO-001: a root-relative path is redirected into the data directory")
+    void testFIO001_IntegrationPositive_RootRelativePathIsRedirectedIntoDataDirectory() {
+        assertOnBothEngines(ROBOT, SOURCE, (outcome, engine) -> {
+            assertTrue(outcome.anyConsoleContains("WriteSucceeded:/root-relative-name.txt:true"),
+                    () -> "the root-relative write did not succeed on " + engine
+                            + " (" + outcome.summary() + ")");
+            assertTrue(outcome.anyConsoleContains("DirectoryListing:root-relative-name.txt"),
+                    () -> "the redirected file did not land in the data directory on " + engine
+                            + " (" + outcome.summary() + ")");
+        });
+    }
+
+    @Test
+    @DisplayName("FIO-001 negative: the redirected name is not written where it was named")
+    void testFIO001_IntegrationNegative_NothingIsWrittenAtTheNamedPath() {
+        assertOnBothEngines(ROBOT, SOURCE, (outcome, engine) -> {
+            for (String console : outcome.consoles()) {
+                for (String line : console.split("\\R")) {
+                    if (line.startsWith("Resolved:/root-relative-name.txt:")) {
+                        String resolved = line.substring("Resolved:/root-relative-name.txt:".length());
+                        assertFalse(resolved.equals("/root-relative-name.txt")
+                                        || resolved.equals("\\root-relative-name.txt"),
+                                () -> "the name resolved to the unredirected path on " + engine + ": " + line);
+                    }
+                }
+            }
+        });
+    }
+
+    @Test
+    @DisplayName("FIO-002: getDataFile and getDataDirectory resolve against the same place")
+    void testFIO002_IntegrationPositive_DataFileAndDataDirectoryAgree() {
+        assertOnBothEngines(ROBOT, SOURCE, (outcome, engine) -> {
+            assertTrue(outcome.anyConsoleContains("WriteSucceeded:plain-name.txt:true"),
+                    () -> "the plain-name write did not succeed on " + engine
+                            + " (" + outcome.summary() + ")");
+            assertTrue(outcome.anyConsoleContains("DirectoryListing:plain-name.txt"),
+                    () -> "getDataDirectory's listing did not see what getDataFile wrote on " + engine
+                            + " (" + outcome.summary() + ")");
+        });
+    }
+
+    @Test
+    @DisplayName("FIO-002 negative: the directory listing reports no file the probe did not write")
+    void testFIO002_IntegrationNegative_DirectoryListingReportsNoUnwrittenFile() {
+        assertOnBothEngines(ROBOT, SOURCE, (outcome, engine) ->
+                assertFalse(outcome.anyConsoleContains("DirectoryListing:none"),
+                        () -> "the data directory listing came back empty on " + engine
+                                + " (" + outcome.summary() + ")"));
+    }
+}

docs/architecture/README.md

@@ -74,7 +74,7 @@ The corpus splits the goal into promises. They are not arbitrary; each sits at a
 | `CAP-008` call-routing fidelity | The same boundary, the other axis: what happens to a *call*. Every peer method proven to reach the right Bot API call, with completeness enforced. |
 | `CAP-001` event dispatch parity | The path from server to robot: which events arrive, in what order, interruptible where. |
 | `CAP-002` physics and state parity | The same path, but about the values the events and status carry. |
-| `CAP-004` file I/O sandboxing | Inside the adapter, at the file wrappers. Specified, not implemented. |
+| `CAP-004` file I/O sandboxing | Inside the adapter, at the file wrappers. Implemented for the `getDataFile`-reached surface; the raw-`java.io` case is agent-held (`IDR-007`). |
 | `CAP-006` team robot support | Inside the wrapper: the one-jar-to-one-bot-directory assumption has to give. Not implemented. |
 | `CAP-005` score parity | The whole picture, end to end. Detects; does not localise. |
 | `CAP-007` the harness | The apparatus itself, which has been wrong in ways mistaken for the bridge being wrong. |
@@ -101,7 +101,7 @@ It also has a practical consequence for anyone writing a conformance test: an ex
 
 Classic Robocode's internals. The bridge reproduces observable behaviour and the API surface, not the implementation, and is free to reach the same behaviour by other means.
 
-The rest of classic's sandbox. `CAP-004` covers file I/O because that has an observed defect; threads, reflection, and sockets are real gaps that are scoped out rather than forgotten.
+The rest of classic's sandbox. `CAP-004` covers file I/O reached through `getDataFile`/`getDataDirectory` because that had an observed defect; a raw `java.io` call that bypasses that surface, along with threads, reflection, and sockets, are real gaps that are scoped out rather than forgotten (`IDR-007`).
 
 ## The documents
 

docs/capabilities/CAP-004-robot-file-io-sandboxing/README.md

@@ -1,36 +1,30 @@
 ---
 id: CAP-004
 type: capability
-status: draft
-links: [G-001, C-005]
+status: active
+links: [G-001, C-005, IDR-007]
 goal: G-001
 title: Robot file I/O sandboxing
-provenance: inferred
+provenance: verified
 reversal-cost: high
 ---
 
 # CAP-004 — Robot file I/O sandboxing
 
-Classic Robocode confines everything a robot writes to that robot's own data directory. A robot that opens an absolute path gets a file inside its data directory instead, and never learns the difference. This capability is the promise that the bridge does the same.
-
-It currently does not. This capability is a specification for work not yet done, which is why it is the one place in this corpus where the criteria describe behaviour that does not exist.
+Classic Robocode confines everything a robot writes, through its own data-file API, to that robot's own data directory. A robot that opens a root-relative path gets a file inside its data directory instead, and never learns the difference. This capability is that redirection, implemented at the one point the bridge controls: `RobotData.getDataFile`/`getDataDirectory`.
 
 ## Why it exists as its own capability
 
-Robots depend on the redirection, and the dependency is invisible in their source. A robot that saves its learned targeting data to a root path is not misbehaving — it is a robot whose author relied on the engine to place the file, correctly, because under classic the engine always did. One such bot in the collection produces access-denied errors in the thousands over a single battle, and its behaviour under the bridge is not a degraded version of its classic behaviour but a different robot: one whose learning never persists.
-
-The safety reading points the same way. Rumble jars are downloaded code run unmodified on a maintainer's machine. Classic sandboxes them; the bridge does not.
+Robots depend on the redirection, and the dependency is invisible in their source. A robot that saves its learned targeting data to a root path is not misbehaving — it is a robot whose author relied on the engine to place the file, correctly, because under classic the engine always did. One such bot in the collection produced access-denied errors in the thousands over a single battle before this capability existed, and its behaviour under the bridge was not a degraded version of its classic behaviour but a different robot: one whose learning never persisted.
 
 ## What it covers
 
-Path confinement for the file wrappers a robot uses, the resolution rule that makes `getDataFile` and `getDataDirectory` agree with each other, and the size cap classic enforces on a robot's data directory.
+Path confinement inside `getDataFile`/`getDataDirectory` — asterisks stripped, `..` rejected in the stripped name (stricter than classic's own check order, for safety — see `design.md`), and a `java.io.File` merge used so a root-relative name is re-rooted inside the directory rather than overriding it (a true drive-letter-absolute name fails the write on both engines instead) — plus the 200000-byte quota classic enforces on a robot's data directory.
 
 ## What it does not cover
 
-The rest of classic's sandbox. Classic also restricts threads, reflection, sockets, and other ambient authority, and its own test suite has robots for each. Those are real gaps in the bridge and they are deliberately not promised here: this capability is scoped to file I/O, which is the part with an active, observed defect. Widening the scope to the whole sandbox would turn a milestone into a project.
+The rest of classic's sandbox, and, within file I/O itself, a raw `java.io` call that never goes through `getDataFile`. Classic blocks those unconditionally on path with a JVM `SecurityManager`, a mechanism JDK 24 removed and this bridge cannot reproduce; `IDR-007` records why `FIO-004` — the criterion that names this — stays `@draft` rather than closing on evidence a bridge probe cannot honestly produce. Threads, reflection, sockets, and other ambient authority are the same shape of gap and are likewise not promised here.
 
 ## Status
 
-`draft`, and honestly so. Every criterion describes behaviour the bridge lacks. `M-004` is the plan door, and `C-005` is the constraint these criteria discharge.
-
-The one thing that makes this cheaper than it looks: classic's own test suite already contains robots that assert confinement by attempting to escape it. `M-004` implements the sandbox and ports those robots in the same milestone, so the criteria gain machine evidence at the moment the behaviour appears.
+`active`. `FIO-001`–`FIO-003` are proven; `FIO-004` remains `@draft` per `IDR-007`. `M-004` is the plan door, and `C-005` is the constraint these criteria discharge — partially: the redirection and quota rules are machine-enforced, the raw-`java.io` case is not.