1 files changed, 214 insertions, 0 deletions
diff --git a/js/scripting-lang/baba-yaga-c/REQ.md b/js/scripting-lang/baba-yaga-c/REQ.md
new file mode 100644
index 0000000..81a8c90
--- /dev/null
+++ b/js/scripting-lang/baba-yaga-c/REQ.md
@@ -0,0 +1,214 @@
+# Requirements and Implementation Guidance for Baba Yaga C Implementation
+
+## Response to C Implementation Team Questions
+
+### Scope Chain Semantics
+
+**Q: When evaluating a sequence of statements, are all variable declarations and lookups expected to occur in the same (global) scope?**
+
+**A:** **CORRECTION**: The JavaScript implementation uses a **hybrid scope model** with both global and local scopes.
+
+**Key Points:**
+- **Global Scope**: All top-level variable declarations and function definitions are stored in a single global environment object
+- **Local Scopes**: Function calls create new local scopes using prototypal inheritance (`Object.create(globalScope)`)
+- **Variable Lookup**: Local scopes inherit from global scope, allowing access to global variables
+- **Function Parameters**: Create local variables in the function's scope
+
+**Q: Are there any cases where a new scope is created implicitly?**
+
+**A:** **CORRECTION**: Yes, the JavaScript implementation creates local scopes for function calls.
+
+**Scope Creation:**
+- **Function Calls**: Create new local scopes using `Object.create(globalScope)`
+- **Function Parameters**: Become local variables in the function scope
+- **`when` expressions**: No new scope created
+- **Table literals**: No new scope created
+- **Other constructs**: No new scope created
+
+### Variable Lookup and Shadowing
+
+**Q: If a variable is declared in a sequence, is it immediately available for lookup in subsequent statements?**
+
+**A:** **CORRECTION**: Yes, for global variables. However, local variables in function scopes are only available within that function.
+
+**Global Scope Behavior:**
+```
+x : 5;
+y : 3;
+sum : x + y;  // x and y are immediately available in global scope
+```
+
+**Local Scope Behavior:**
+```
+func : (param) -> {
+    local : param + 1;  // local is only available within this function
+    return local;
+};
+// local is NOT available here in global scope
+```
+
+**Q: How does the JS implementation handle variable shadowing or redeclaration?**
+
+**A:** **CORRECTION**: The JavaScript implementation uses **prototypal inheritance shadowing** for local scopes and **overwrites** for global redeclaration.
+
+**Behavior:**
+- **Global Scope**: Variable redeclaration overwrites the previous value (no error)
+- **Local Scopes**: Function parameters and local variables shadow global variables
+- **Lookup Order**: Local scope first, then global scope (prototypal inheritance)
+- **No Block Scoping**: No nested block-level scopes exist
+
+**Global Redeclaration Example:**
+```
+x : 5;
+x : 10;  // x is now 10, previous value 5 is lost
+result : x;  // result = 10
+```
+
+**IMPORTANT CORRECTION**: The above redeclaration behavior appears to be incorrect based on functional programming principles and test evidence. See the "Variable Redeclaration" section below for the corrected implementation.
+
+**Local Shadowing Example:**
+```
+global_var : 5;
+func : (global_var) -> {
+    // global_var parameter shadows the global variable
+    return global_var + 1;  // uses parameter, not global
+};
+result : func(10);  // result = 11, global_var still = 5
+```
+
+### Table Pattern Matching
+
+**Q: When matching a table pattern in a when expression, is the pattern table compared by key and value only?**
+
+**A:** Yes, table pattern matching is a **simple key-value comparison**. The JavaScript implementation performs a shallow comparison of table properties.
+
+**Matching Rules:**
+- Keys must match exactly (string comparison)
+- Values must be equal (using `===` semantics)
+- No prototype chain traversal
+- No hidden property checking
+- No deep object comparison
+
+**Example:**
+```
+table : {a: 1, b: 2};
+result : when table
+  {a: 1, b: 2} -> "exact match"
+  {a: 1} -> "partial match"
+  _ -> "no match"
+```
+
+**Q: Are there edge cases in table pattern matching?**
+
+**A:** The JavaScript implementation treats table patterns as simple object comparisons. No special edge cases beyond standard JavaScript object equality semantics.
+
+### Function Call Semantics
+
+**Q: What are the exact rules for when an identifier is treated as a function vs. a value?**
+
+**A:** The JavaScript implementation uses **parse-time function detection** based on syntax, not runtime type checking.
+
+**Function Call Rules:**
+1. **Parse-time detection**: If an identifier is followed by parentheses `()` or expressions that could be arguments, it's treated as a function call
+2. **Scope creation**: Function calls create new local scopes using prototypal inheritance
+3. **No runtime type checking**: The system doesn't verify if the identifier actually contains a function
+4. **Runtime errors**: If you call a non-function value, it will attempt to execute it as a function (causes runtime error)
+
+**Examples:**
+```
+x : 5;
+func : (a, b) -> a + b;
+
+result1 : func(1, 2);     // Function call - works
+result2 : x(1, 2);        // Non-function call - runtime error
+```
+
+**Important:** The distinction is made at parse time based on syntax, not at runtime based on the actual value type.
+
+### Test 05 IO Operations
+
+**Q: Are there any known quirks regarding order of evaluation or scope for IO operations?**
+
+**A:** IO operations follow the same global scope rules as all other operations.
+
+**IO Behavior:**
+- IO operations use the current scope (global or local)
+- No special scoping for IO functions
+- Order of evaluation follows normal left-to-right sequence evaluation
+- IO operations can reference any variables in the current scope
+
+**Example:**
+```
+x : 5;
+print(x);        // Prints 5
+y : 10;
+print(y);        // Prints 10
+print(x + y);    // Prints 15
+```
+
+### Implementation Recommendations
+
+**For C Implementation:**
+
+1. **Hybrid Scope Model**: Implement both global scope and local function scopes
+2. **Prototypal Inheritance**: Local scopes should inherit from global scope
+3. **Variable Lookup Order**: Local scope first, then global scope
+4. **Function Parameter Scoping**: Function parameters create local variables
+5. **Simple Table Comparison**: Use shallow key-value comparison for table pattern matching
+6. **Parse-time Function Detection**: Determine function calls at parse time, not runtime
+7. **Allow Global Redeclaration**: Permit variable redeclaration in global scope without errors
+
+**Key Implementation Pattern:**
+```c
+// Global environment
+typedef struct {
+    char* name;
+    Value value;
+} Variable;
+
+Variable* global_env[MAX_VARS];
+int global_env_size = 0;
+
+// Local scope (for function calls)
+typedef struct {
+    Variable* local_vars[MAX_VARS];
+    int local_size;
+    Variable** parent_scope;  // Reference to global scope
+} LocalScope;
+
+// Variable lookup: check local scope first, then global scope
+```
+
+## Variable Redeclaration
+
+**Q: Is variable redeclaration allowed?**
+**A:** **NO** - Variable redeclaration is NOT allowed in Baba Yaga. This is a functional programming language where all values are immutable once declared.
+
+**Evidence:**
+- None of the test files contain variable redeclarations
+- Functional programming principles require immutability
+- Current C implementation correctly prevents redeclaration (returns false if variable exists)
+
+**Implementation:** When defining a variable, if it already exists in the current scope, return an error rather than overwriting the value.
+
+**Note:** The JS team's previous response about allowing redeclaration appears to be incorrect or outdated. The language design clearly favors functional programming principles.
+
+### Testing Strategy
+
+**Focus Areas for C Implementation:**
+1. Verify hybrid scope model (global + local function scopes)
+2. Test variable shadowing in function parameters
+3. Confirm table pattern matching uses simple key-value comparison
+4. Validate parse-time function call detection
+5. Ensure IO operations use current scope (global or local)
+
+**Critical Test Cases:**
+- Variable redeclaration in global scope (should overwrite, not error)
+- Function parameter shadowing of global variables
+- Cross-statement variable access in global scope
+- Local variable isolation within functions
+- Table pattern matching with exact and partial matches
+- Function calls vs. value references
+- IO operations with variables from current scope
+
+This should resolve the scope-related test failures and ensure the C implementation matches the JavaScript reference semantics exactly.