fix(orchestrator): prevent work directory collisions (#29)

[siphonite]

Closes #29.

This PR resolves issue #29 by introducing unique base directories for each test run, ensuring that parallel execution of tests via cargo test is safe and free from filesystem collisions.

Changes:

• Orchestrator: Generates a unique base directory (/tmp/first/first-<pid>-<uuid>) for each run.
• Orchestrator: Passes this base directory to child processes via FIRST_WORK_DIR.
• Test Runtime: Derives the leaf run_N directory from the base directory, ensuring strict ownership by the orchestrator.
• Test Isolation: Improved extract_test_name to use thread name fallback.
• Dependencies: Added uuid crate.
• Verification: Added regression test tests/repro_issue_29.rs.

---

Summary by cubic

Prevents work directory collisions during parallel test runs by generating a unique base directory per orchestrator run and deriving per-target run_N paths from it. Improves test isolation and reliability; also updates documentation and switches the project to Apache 2.0.

• Bug Fixes

  • Generate base dir as /tmp/first/first-- using UUID + PID.
  • Pass base dir to child processes via FIRST_WORK_DIR.
  • Derive run_N leaf dirs in the test runtime from the base + target.
  • Use thread name fallback in extract_test_name for better isolation.
  • Add regression test tests/repro_issue_29.rs to verify no collisions.

• Refactors

  • Add uuid crate (v4) for base dir generation; move import in orchestrator and remove stray doc comment.
  • Switch license to Apache-2.0 and streamline docs (README, ADRs, limitations, proof).

^{Written for commit 6d959d2. Summary will update on new commits.}

[cubic-dev-ai]

3 issues found across 15 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="src/orchestrator.rs">

<violation number="1" location="src/orchestrator.rs:13">
P2: This import is incorrectly placed after a doc comment that was meant for the removed `FIRST_BASE_DIR` constant. Move the import to the top of the file with other imports, and either remove the orphaned doc comment or add a new constant/comment explaining the base directory pattern (now dynamically generated in the `run` function).</violation>
</file>

<file name="docs/architecture/004_orchestrator.md">

<violation number="1" location="docs/architecture/004_orchestrator.md:10">
P3: The core-loop doc still describes the old shared `/tmp/first/run_{target}` path, but the orchestrator now creates a unique base directory per run. Update the documentation to reflect the base directory + run_N layout.</violation>
</file>

<file name="docs/architecture/002_crash_point.md">

<violation number="1" location="docs/architecture/002_crash_point.md:35">
P3: Doc example still shows `/tmp/first/run_5`, but the runtime now uses a unique base dir (`/tmp/first/first-<pid>-<uuid>/run_5`). Update the example to match the new base directory scheme so users copy the correct paths.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P3: The core-loop doc still describes the old shared /tmp/first/run_{target} path, but the orchestrator now creates a unique base directory per run. Update the documentation to reflect the base directory + run_N layout.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/architecture/004_orchestrator.md, line 10:

<comment>The core-loop doc still describes the old shared `/tmp/first/run_{target}` path, but the orchestrator now creates a unique base directory per run. Update the documentation to reflect the base directory + run_N layout.</comment>

<file context>
@@ -1,136 +1,64 @@
 loop {
-    1. Create work_dir: /tmp/first/run_{target}
-    2. Spawn EXECUTION child with target
+    1. Create /tmp/first/run_{target}
+    2. Spawn EXECUTION child
     3. Wait for exit:
</file context>

Suggested change

	1. Create /tmp/first/run_{target}
	1. Create /tmp/first/first-<pid>-<uuid>/run_{target}

[cubic-dev-ai]

P3: Doc example still shows /tmp/first/run_5, but the runtime now uses a unique base dir (/tmp/first/first-<pid>-<uuid>/run_5). Update the example to match the new base directory scheme so users copy the correct paths.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/architecture/002_crash_point.md, line 35:

<comment>Doc example still shows `/tmp/first/run_5`, but the runtime now uses a unique base dir (`/tmp/first/first-<pid>-<uuid>/run_5`). Update the example to match the new base directory scheme so users copy the correct paths.</comment>

<file context>
@@ -1,128 +1,51 @@
-**Format (JSON to stderr before kill):**
 ```json
-{"event":"crash","point_id":42,"label":"after_wal_write","seed":12345,"work_dir":"/tmp/first/run_42"}
+{"event":"crash","point_id":5,"label":"after_commit","seed":null,"work_dir":"/tmp/first/run_5"}

</file context>

</details>

```suggestion
{"event":"crash","point_id":5,"label":"after_commit","seed":null,"work_dir":"/tmp/first/first-<pid>-<uuid>/run_5"}