1 files changed, 283 insertions, 0 deletions
diff --git a/js/scripting-lang/c/REQ.md b/js/scripting-lang/c/REQ.md
new file mode 100644
index 0000000..78c03b5
--- /dev/null
+++ b/js/scripting-lang/c/REQ.md
@@ -0,0 +1,283 @@
+# Baba Yaga JS Team Response to C Implementation Questions
+
+## Executive Summary
+
+Our JavaScript implementation successfully handles all the test cases, including `integration_02_pattern_matching.txt`. The key insight is that **function call arguments are evaluated immediately when the assignment is processed**, not lazily. This is critical for avoiding the argument corruption issue you're experiencing.
+
+## Critical Issue Analysis
+
+### Root Cause of Your Segfault
+
+The issue you're experiencing with `factorial` receiving `n = -3549` instead of `5` is likely due to **argument evaluation timing and memory management**. Here's what's happening:
+
+1. **Immediate Evaluation**: In `fact5 : factorial 5;`, the argument `5` must be evaluated immediately when the assignment is processed
+2. **Memory Safety**: The argument value must be properly allocated and preserved until the function is called
+3. **Scope Management**: Function arguments need to be bound to the correct scope when the function is executed
+
+## Detailed Answers to Your Questions
+
+### 1. Function Call Argument Evaluation
+
+**Answer**: Arguments are evaluated **immediately** when parsing the assignment.
+
+```javascript
+// In our implementation:
+case 'Assignment':
+    const assignmentValue = evalNode(node.value);  // This evaluates factorial 5 immediately
+    globalScope[node.identifier] = assignmentValue;
+    return;
+```
+
+**Key Points**:
+- `factorial 5` is evaluated to a function call result (120) before assignment
+- No lazy evaluation or delayed argument processing
+- Arguments are fully resolved before the assignment completes
+
+### 2. Memory Management for Function Arguments
+
+**Answer**: We use JavaScript's built-in memory management, but the critical insight is **argument evaluation order**:
+
+```javascript
+case 'FunctionCall':
+    let args = node.args.map(evalNode);  // Evaluate all arguments immediately
+    return funcToCall(...args);
+```
+
+**Key Points**:
+- Arguments are evaluated in order: `[evalNode(arg1), evalNode(arg2), ...]`
+- Each argument is fully resolved before function execution
+- No special cleanup needed due to JavaScript's garbage collection
+- For recursive calls, each call gets fresh argument arrays
+
+### 3. File Reading vs Piped Input
+
+**Answer**: Our implementation handles both identically, but we use different input methods:
+
+```javascript
+// File reading
+async function readFile(filePath) {
+    const fs = createFileSystem();
+    return new Promise((resolve, reject) => {
+        fs.readFile(filePath, 'utf8', (err, data) => {
+            if (err) reject(err);
+            else resolve(data);
+        });
+    });
+}
+
+// Piped input (stdin)
+const rl = createReadline();
+```
+
+**Key Points**:
+- No differences in parsing between file and stdin
+- Same lexer/parser for both input sources
+- No preprocessing or encoding differences
+
+### 4. Top-Level Assignment Semantics
+
+**Answer**: Top-level assignments evaluate their right-hand side **immediately**:
+
+```javascript
+// This evaluates factorial 5 immediately, not lazily
+fact5 : factorial 5;
+
+// This is equivalent to:
+fact5 : (factorial 5);
+```
+
+**Key Points**:
+- No lazy evaluation in Baba Yaga
+- Parentheses don't change evaluation timing
+- All expressions are evaluated when encountered
+
+### 5. Function Call Argument Array Initialization
+
+**Answer**: Arguments are evaluated and stored in a fresh array for each call:
+
+```javascript
+case 'FunctionCall':
+    let args = node.args.map(evalNode);  // Fresh array each time
+    return funcToCall(...args);
+```
+
+**Key Points**:
+- Array is created fresh for each function call
+- Arguments are evaluated in order
+- No pre-allocation or reuse of argument arrays
+
+## Language Semantics Answers
+
+### 6. Pattern Matching in Multi-Parameter Contexts
+
+**Answer**: Expressions are evaluated **once** per pattern match:
+
+```javascript
+case 'WhenExpression':
+    const whenValues = Array.isArray(node.value) 
+        ? node.value.map(evalNode)  // Evaluate once
+        : [evalNode(node.value)];
+```
+
+**Key Points**:
+- `(x % 2)` and `(y % 2)` are evaluated once when the when expression is processed
+- Results are cached and reused for pattern matching
+- No re-evaluation during pattern comparison
+
+### 7. Recursive Function Scope
+
+**Answer**: Each recursive call gets a fresh local scope:
+
+```javascript
+let localScope = Object.create(globalScope);  // Fresh scope each call
+for (let i = 0; i < node.params.length; i++) {
+    localScope[node.params[i]] = args[i];  // Bind parameters
+}
+```
+
+**Key Points**:
+- Prototypal inheritance from global scope
+- Fresh parameter bindings for each call
+- No scope pollution between recursive calls
+
+### 8. Partial Application Semantics
+
+**Answer**: Partial application occurs when fewer arguments are provided:
+
+```javascript
+if (args.length < node.params.length) {
+    return function(...moreArgs) {  // Return curried function
+        const allArgs = [...args, ...moreArgs];
+        // ... handle remaining arguments
+    };
+}
+```
+
+**Key Points**:
+- Automatic currying when arguments < parameters
+- No errors for partial application
+- Works with user-defined and standard library functions
+
+## Implementation Answers
+
+### 9. Parser State Management
+
+**Answer**: Parser state is maintained throughout file processing:
+
+```javascript
+function interpreter(ast, environment = null, initialState = {}) {
+    let globalScope = { ...initialState };
+    // ... parser maintains state in globalScope
+}
+```
+
+**Key Points**:
+- No state reset between statements
+- Global scope persists throughout execution
+- Context switching handled by scope inheritance
+
+### 10. Error Handling
+
+**Answer**: Errors cause immediate termination with descriptive messages:
+
+```javascript
+if (identifierValue === undefined) {
+    throw new Error(`Variable ${node.value} is not defined`);
+}
+```
+
+**Key Points**:
+- No error recovery or continuation
+- Descriptive error messages
+- Immediate termination on critical errors
+
+### 11. Memory and Performance
+
+**Answer**: Leverage JavaScript's garbage collection:
+
+**Key Points**:
+- No manual memory management
+- Automatic cleanup of temporary values
+- No identified performance bottlenecks
+
+## Test-Specific Answers
+
+### 12. Integration Test 02 Expected Behavior
+
+**Answer**: The test should complete successfully with these outputs:
+
+```
+=== Integration Test: Pattern Matching ===
+Pattern matching integration test completed
+```
+
+**Expected Values**:
+- `fact5 = 120` (factorial of 5)
+- `fact3 = 6` (factorial of 3)
+- All assertions should pass
+- No errors or segfaults
+
+### 13. File Reading Behavior
+
+**Answer**: Our JS implementation handles the test file correctly:
+
+```bash
+$ bun lang.js tests/integration_02_pattern_matching.txt
+=== Integration Test: Pattern Matching ===
+Pattern matching integration test completed
+```
+
+**Key Points**:
+- No differences between file reading and piped input
+- All assertions pass
+- No known issues with this test file
+
+## Debugging Recommendations
+
+### 14. Debugging Strategies
+
+**Recommendations**:
+1. **Add argument validation**: Log argument values before function execution
+2. **Check evaluation order**: Ensure arguments are evaluated before assignment
+3. **Memory debugging**: Use tools like AddressSanitizer/LeakSanitizer (or Valgrind on Linux) to detect memory corruption
+4. **Scope inspection**: Verify parameter binding in recursive calls
+
+### 15. Testing Approach
+
+**Our Testing Strategy**:
+- Comprehensive test suite with edge cases
+- Function argument validation
+- Recursive function testing
+- Pattern matching validation
+
+## Implementation Recommendations
+
+### 16. Code Review Suggestions
+
+**Critical Areas to Check**:
+1. **Argument evaluation timing**: Ensure `factorial 5` is evaluated immediately
+2. **Memory allocation**: Verify argument arrays are properly allocated
+3. **Scope management**: Check parameter binding in recursive calls
+4. **File I/O**: Ensure no buffer corruption during file reading
+
+### 17. Test Validation
+
+**Our Results**:
+- All 27 tests pass in our implementation
+- No segfaults or memory issues
+- Consistent behavior across file and stdin input
+
+## Specific Fix Recommendations
+
+Based on your symptoms, focus on these areas:
+
+1. **Immediate Argument Evaluation**: Ensure `factorial 5` evaluates to `120` before assignment
+2. **Memory Safety**: Check for buffer overflows or uninitialized memory
+3. **Scope Isolation**: Verify recursive calls don't corrupt argument values
+4. **File Reading**: Ensure no differences between file and stdin processing
+
+## Contact Information
+
+We're available for further discussion and can provide additional code examples or debugging assistance. The key insight is that Baba Yaga uses **eager evaluation** - all expressions are evaluated immediately when encountered, not lazily.
+
+Good luck with resolving the final issue! Your 96% completion rate is impressive, and this should be the final piece needed for 100%.