docs: document new resilience, observability, and call features

- Add API documentation for `call()`, load shedding, and introspection methods to `usage.md`.                                                                                  │ │
- Update `architecture.md` with a new section on the Telemetry & Observability Layer.
- Update `README.md` Core Capabilities to include the new features.
- Update `README.md` to reflect that Node.js support is on hold.

Author: SSL-ACTX

README.md

@@ -17,24 +17,26 @@
 
 ## Overview
 
-**Iris** is a hybrid distributed runtime built in Rust with first-class **Python** and **Node.js** bindings. It combines three execution styles:
+**Iris** is a hybrid distributed runtime built in Rust with first-class **Python** bindings. It combines three execution styles:
 - **Actor Mesh:** Stateful, message-driven workflows with high concurrency.
 - **Native Offload/JIT:** CPU-heavy hot paths accelerated via Cranelift. This path is experimental, currently paused, and may be dropped in future releases.
-- **Cross-Language API:** Service-oriented apps mixing Rust, Python, and Node.js.
+- **Cross-Language API:** Service-oriented apps mixing Rust and Python.
 
 Iris uses a **cooperative reduction-based scheduler** for fairness, providing built-in supervision, hot swapping, discovery, and location-transparent messaging across nodes.
 
 > [!NOTE]
-> Node.js bindings are currently in Alpha and reaching feature parity with Python.
+> Node.js bindings are currently on hold and are not actively developed or supported.
 
 ---
 
 ## Core Capabilities
 
 - **Hybrid Concurrency:** Mix "Push" green-thread actors with "Pull" OS-thread actors.
-- **Atomic Hot-Swap:** Update live application logic (Python/Node) without zero downtime.
+- **Atomic Hot-Swap:** Update live application logic (Python) with zero downtime.
 - **Global Discovery:** Register and resolve named services locally or over the network.
-- **Self-Healing:** Path-scoped supervisors and structured `EXIT` reasons for fault tolerance.
+- **Resilience:** Built-in supervision, load shedding, and network-aware exit reasons for self-healing systems.
+- **Observability:** Deep runtime introspection, system metrics, and actor health tracking.
+- **Async Request/Reply:** Built-in `call()` semantics for ergonomic, awaitable actor communication.
 - **Vortex-Transmuter (Experimental):** Instruction-bound preemption, transactional ghosting primitives, and guarded bytecode transmutation with explicit fallback telemetry (see [Vortex-Transmuter Guide](docs/vortex.md)).
 - **JIT Acceleration:** Transparently compile Python math functions to native machine code.
     - **Quantum Speculation:** Optional multi-variant JIT selection with runtime telemetry, bounded by compile budget and cooldown controls (see [JIT Internals & Configuration](docs/jit.md)).

docs/architecture.md

@@ -30,6 +30,14 @@ Iris allows updating live application logic without stopping the runtime.
 - **State Preservation:** In-flight messages remain in the mailbox; only the "behavior" pointer is swapped.
 - **Versioning:** Supports rolling back to previous behavior versions.
 
+## Telemetry & Observability Layer
+
+Iris includes a built-in `TelemetryManager` that provides real-time instrumentation of the actor mesh.
+- **Event Stream:** Captures actor life-cycles (`Spawned`, `Stopped`, `Crashed`) and message throughput.
+- **Health Tracking:** Tracks actor health status (`Starting`, `Ready`, `Busy`, `Degraded`) for cluster-wide health checks.
+- **Mailbox Depth:** Provides visibility into queue depths for identifying bottlenecks.
+- **Metrics API:** Aggregated system-wide statistics available via a high-performance concurrent registry.
+
 ## Distributed Mesh Protocol
 
 Iris nodes communicate over TCP using a length-prefixed binary protocol.

docs/usage.md

@@ -81,6 +81,7 @@ rt.spawn_with_mailbox(mailbox_worker)
 ## Sending messages
 
 - `send(pid: int, data: bytes-like) -> bool` — send user payload (`bytes`, `bytearray`, `memoryview`) to a PID.
+- `call(pid: int, data: bytes-like, timeout: Optional[float] = None) -> Awaitable[bytes]` — send a request and await a response (async).
 - `send_many(pid: int, payloads: Iterable[bytes-like]) -> int` — batch-send payloads and return accepted count.
 - `send_named(name: str, data: bytes-like) -> bool` — resolve and send by registered name.
 - `send_buffer(pid: int, buffer_id: int) -> bool` — zero-copy send via buffer ID (use `allocate_buffer`).
@@ -91,13 +92,53 @@ rt.spawn_with_mailbox(mailbox_worker)
 Example:
 
 ```python
+# Async request-reply
+response = await rt.call(pid, b"ping", timeout=2.0)
+print("response", response)
+
 timer = rt.send_after(pid, 200, b'tick')
-# cancel
-rt.cancel_timer(timer)
+```
+
+---
+
+## Observability & Introspection
+
+Iris provides deep visibility into the live runtime state via the following APIs:
+
+- `list_actors() -> list[int]` — list all active local actor PIDs.
+- `actor_info(pid: int) -> Optional[dict[str, str]]` — get metadata, health, and status for a specific actor.
+- `set_actor_health(pid: int, status: str)` — manually update actor health (e.g. `'busy'`, `'degraded'`, `'ready'`).
+- `get_metrics() -> dict[str, int]` — retrieve system-wide metrics (actor count, message throughput).
+
+Example:
+
+```python
+for pid in rt.list_actors():
+    info = rt.actor_info(pid)
+    print(f"Actor {pid}: {info['health']}")
+
+metrics = rt.get_metrics()
+print(f"Throughput: {metrics['messages_received']} msgs")
+```
+
+---
+
+## Resilience & Load Shedding
+
+To prevent cascade failures under extreme load, Iris can shed traffic by rejecting new actors and messages.
+
+- `set_system_capacity(cap: int)` — set the maximum number of concurrent actors allowed.
+- `set_load_shedding(enabled: bool)` — enable or disable the load shedding subsystem.
+- `is_load_shedding_active() -> bool` — check if the system is currently rejecting work due to capacity.
+
+Example:
+
+```python
+rt.set_system_capacity(10_000)
+rt.set_load_shedding(True)
 
-# batch send
-accepted = rt.send_many(pid, [b"a", bytearray(b"b"), memoryview(b"c")])
-print("accepted", accepted)
+if rt.is_load_shedding_active():
+    print("Warning: System at capacity, load shedding active.")
 ```
 
 ---