From ba039487fcbc4c2a8b8d1c7100ee33ea3ab1918e Mon Sep 17 00:00:00 2001 From: He-Pin Date: Fri, 26 Jun 2026 00:44:59 +0800 Subject: [PATCH] docs: clarify threading model guidance Motivation: Prevent future AI-assisted changes from introducing unsafe assumptions about interpreter threading or shared state. Modification: Add a Threading Model section to CLAUDE.md covering allowed parallel evaluation, interpreter isolation, and explicit contracts for shared mutable state. Result: Repository guidance now supports future parallel evaluation while preserving deterministic behavior and cross-platform interpreter isolation. --- CLAUDE.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 63177b5a2..911a05fdb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -175,6 +175,12 @@ Shared and platform-specific sources are split across directories: - **Parse caching**: `ParseCache` / `DefaultParseCache` caches parsed ASTs to avoid re-parsing imports. - **Platform abstraction**: `Path` and `Importer` traits abstract filesystem access across JVM/JS/Native. +### Threading Model + +- **No internal multithreading requirement**: A single `Interpreter` does not need to evaluate a program using multiple threads. +- **Independent interpreters should not interfere**: Applications should be able to run multiple independent `Interpreter` instances concurrently on platforms that support concurrency, without one interpreter affecting another. +- **Shared mutable state is exceptional**: State should belong to an interpreter or evaluation unless it has an explicit concurrency contract and tests. + ## Dependencies Key runtime dependencies: