GSoC/DMP 2025 Week 2: feat(program): Add Memory Module

[sa-fw-an]

This PR implements the complete Memory Module for Music Blocks 4 Program Engine as discussed in Week 2 of the GSoC project. The implementation provides a comprehensive three-scope memory management system with CRUD operations, thread isolation, and variable shadowing support.

What's Implemented

Core Memory Architecture

• Three-level scope hierarchy with Global, Thread, and Local scope management
• LayeredMap as foundational tree-based data structure with projection and shadowing
• Complete CRUD operations for variables at all scope levels
• Thread isolation with proper memory boundaries and cleanup
• Variable shadowing with deterministic resolution order: Local → Thread → Global

Memory Management Classes

• ContextManager: Global scope coordinator and thread context factory
• ContextStack: Thread-specific scope chain with push/pop operations
• ThreadManager: Thread lifecycle management and coordination
• ThreadContext: Unified API for thread-specific memory operations
• LayeredMap: Core hierarchical storage with frame-based organization

CRUD Operation Support

• Global Variables: Create, Read, Update, Delete operations accessible from any context
• Thread Scope Management: Create/Delete thread-specific memory spaces with isolation
• Local Scope Operations: Push/Pop local scopes for function calls and blocks
• Current Scope Variables: Context-aware variable operations with proper shadowing

Testing Implementation

Test Suite Structure

Located in sample/:

1. Thread Manager Tests (thread-manager.test.ts)

   • Thread creation, isolation, and lifecycle management
   • Inter-thread communication through global variables
   • Thread cleanup and resource management

2. Memory Operations Tests (memory-operations.test.ts)

   • Global variable CRUD operations from multiple contexts
   • Thread-specific variable isolation and independence
   • Local scope creation, nesting, and cleanup

3. Scope Management Tests (scope-management.test.ts)

   • Variable shadowing and resolution precedence
   • Nested function call scope handling
   • Error conditions and edge case validation

4. Performance Tests (performance.test.ts)

   • Large-scale thread and variable operations
   • Deep nesting and complex scope hierarchies
   • Memory cleanup and garbage collection validation

How to Test

Run Tests

npm test
# or for specific test files
ts-node sample/thread-manager.test.ts

Expected Output

• All test cases pass with comprehensive coverage
• Thread isolation verified across concurrent operations
• Variable shadowing works correctly with proper precedence
• Memory cleanup occurs without leaks or dangling references
• Error handling provides informative messages for invalid operations

Week 2 Objectives - COMPLETED

As discussed in Week 2:

1. ✅ Global Variable CRUD: Full Create, Read, Update, Delete operations accessible from any thread/scope
2. ✅ Thread Scope Management: Create and Delete thread-specific memory spaces with proper isolation
3. ✅ Local Scope Management: Create and Delete multiple local scopes per thread with stack behavior
4. ✅ Current Scope Variable CRUD: Operations with proper scope resolution and variable shadowing
5. ✅ Memory Module Foundation: Solid foundation prepared for future symbol table integration

Memory Module API

• ThreadManager: Factory for creating and managing thread contexts
• ThreadContext: Primary interface for all memory operations
• Scope Operations: pushScope(), popScope() for local scope management
• Variable Operations: getLocal(), setLocal(), deleteLocal() for current scope
• Global Operations: getGlobal(), setGlobal(), deleteGlobal() for program-wide variables

[sa-fw-an]

@meganindya Please have a look

[meganindya]

Wrong package. These go into modules/runtime/src. Move the sample under a src/spec folder instead.

[meganindya]

I made the move