From 1dfff05bf409b32bd58436dac7fd321e590cc4b6 Mon Sep 17 00:00:00 2001
From: Aman Kumar <amansinha327@gmail.com>
Date: Fri, 6 Feb 2026 20:28:35 +0530
Subject: [PATCH] docs: document re-entrancy and integration constraints

Add Integration Constraints section to limitations.md:
- One first::test() per #[test]
- Async tests not supported
- Not thread-safe
- No nested workspaces

Add limitations summary to lib.rs crate docs.

Closes #18
---
 docs/limitations.md | 40 ++++++++++++++++++++++++++++++++++++++++
 src/lib.rs          |  9 +++++++++
 2 files changed, 49 insertions(+)

diff --git a/docs/limitations.md b/docs/limitations.md
index 56c979e..4b2c1da 100644
--- a/docs/limitations.md
+++ b/docs/limitations.md
@@ -145,3 +145,43 @@ Crash points are serialized. Concurrent operations are not explored for race con
 ### Linux Only (v0.1)
 
 The current implementation uses Linux-specific APIs (`SIGKILL`, `/proc`). macOS and Windows support is not yet available.
+
+---
+
+## Integration Constraints (v0.1)
+
+### One `first::test()` Per `#[test]`
+
+| Pattern | Status |
+|---------|--------|
+| One `first::test()` per `#[test]` | ✅ Supported |
+| Multiple `first::test()` in one `#[test]` | ❌ Undefined |
+
+**Rationale**: The orchestrator manages process lifecycle. Nested or sequential calls conflict.
+
+### Async Tests Not Supported
+
+| Pattern | Status |
+|---------|--------|
+| `#[test]` (sync) | ✅ Supported |
+| `#[tokio::test]` | ❌ Not supported |
+| `#[async_std::test]` | ❌ Not supported |
+
+**Rationale**: FIRST uses `fork()` + `SIGKILL` — async runtimes don't survive this.
+
+### Not Thread-Safe
+
+| Pattern | Status |
+|---------|--------|
+| Single-threaded `.run()` closure | ✅ Supported |
+| `crash_point()` from spawned threads | ❌ Undefined |
+
+**Rationale**: Crash point counter uses atomic state but determinism requires single-threaded execution.
+
+### No Nested Workspaces
+
+| Pattern | Status |
+|---------|--------|
+| User-managed dirs inside `env.path()` | ✅ Supported |
+| Expecting FIRST to manage nested isolation | ❌ Not supported |
+
diff --git a/src/lib.rs b/src/lib.rs
index f7df3b7..33c5198 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -24,6 +24,15 @@
 //!         });
 //! }
 //! ```
+//!
+//! # Limitations (v0.1)
+//!
+//! - One `first::test()` per `#[test]` function
+//! - Async tests (`#[tokio::test]`) not supported
+//! - Not thread-safe (`crash_point()` from spawned threads is undefined)
+//! - No nested workspaces
+//!
+//! See `docs/limitations.md` for full details.
 
 mod env;
 mod orchestrator;