@simulatte/doppler 0.1.0

package/src/memory/capability.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Memory Capability Detection
+ * Agent-A | Domain: memory/
+ *
+ * Detects browser memory capabilities:
+ * - Memory64 (WASM large heap support)
+ * - Unified memory (Apple/AMD Strix)
+ * - Maximum heap sizes
+ *
+ * @module memory/capability
+ */
+
+import { UnifiedMemoryInfo } from './unified-detect.js';
+
+/**
+ * Memory strategy type
+ */
+export type MemoryStrategy = 'MEMORY64' | 'SEGMENTED';
+
+/**
+ * Segmented heap limits
+ */
+export interface SegmentedLimits {
+  maxSegmentSize: number;
+  recommendedSegments: number;
+}
+
+/**
+ * Memory capabilities result
+ */
+export interface MemoryCapabilities {
+  /** Browser supports WASM Memory64 */
+  hasMemory64: boolean;
+  /** GPU shares system RAM (Apple/Strix) */
+  isUnifiedMemory: boolean;
+  /** Details from unified-detect */
+  unifiedMemoryInfo: UnifiedMemoryInfo;
+  /** Max single heap size (Memory64 only) */
+  maxHeapSize: number | null;
+  /** Segment limits (non-Memory64) */
+  segmentedLimits: SegmentedLimits | null;
+  /** Recommended heap strategy */
+  strategy: MemoryStrategy;
+}
+
+/**
+ * Main capability detection - call this at init
+ */
+export function getMemoryCapabilities(): Promise<MemoryCapabilities>;

package/src/memory/capability.js

@@ -0,0 +1,95 @@
+
+
+import { detectUnifiedMemory } from './unified-detect.js';
+import { getRuntimeConfig } from '../config/runtime.js';
+
+// ============================================================================
+// Detection Functions
+// ============================================================================
+
+
+async function probeMemory64() {
+  // Minimal WASM module declaring memory64
+  // (module (memory i64 1))
+  const memory64Binary = new Uint8Array([
+    0x00, 0x61, 0x73, 0x6d, // WASM magic
+    0x01, 0x00, 0x00, 0x00, // Version 1
+    0x05, 0x04, 0x01, // Memory section, 1 entry
+    0x04, 0x01, 0x00, // memory64 flag (0x04), min 1 page, no max
+  ]);
+
+  try {
+    await WebAssembly.compile(memory64Binary);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+
+async function probeMaxHeapSize() {
+  const { heapTestSizes, fallbackMaxHeapBytes } = getRuntimeConfig().shared.memory.heapTesting;
+
+  for (const size of heapTestSizes) {
+    try {
+      // Try to create a WASM memory of this size
+      const pages = Math.ceil(size / 65536); // 64KB pages
+      new WebAssembly.Memory({ initial: 1, maximum: pages });
+      return size;
+    } catch {
+      continue;
+    }
+  }
+
+  return fallbackMaxHeapBytes;
+}
+
+
+function probeSegmentedLimits() {
+  const { segmentTestSizes, safeSegmentSizeBytes } = getRuntimeConfig().shared.memory.segmentTesting;
+  const { targetAddressSpaceBytes } = getRuntimeConfig().shared.memory.addressSpace;
+
+  let maxSegmentSize = safeSegmentSizeBytes; // Safe default
+
+  for (const size of segmentTestSizes) {
+    try {
+      // Actually try to allocate to see if it works
+      const testBuffer = new ArrayBuffer(size);
+      if (testBuffer.byteLength === size) {
+        maxSegmentSize = size;
+        break; // Use the largest working size
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return {
+    maxSegmentSize,
+    recommendedSegments: Math.ceil(targetAddressSpaceBytes / maxSegmentSize),
+  };
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+
+export async function getMemoryCapabilities() {
+  const hasMemory64 = await probeMemory64();
+  const unifiedMemory = await detectUnifiedMemory();
+  const maxHeapSize = hasMemory64 ? await probeMaxHeapSize() : null;
+  const segmentedLimits = !hasMemory64 ? probeSegmentedLimits() : null;
+
+  
+  const strategy = hasMemory64 ? 'MEMORY64' : 'SEGMENTED';
+
+  return {
+    hasMemory64,
+    isUnifiedMemory: unifiedMemory.isUnified,
+    unifiedMemoryInfo: unifiedMemory,
+    maxHeapSize,
+    segmentedLimits,
+    strategy,
+  };
+}

package/src/memory/heap-manager.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Heap Manager
+ * Agent-A | Domain: memory/
+ *
+ * Manages memory allocation for model weights:
+ * - Memory64 mode: Single large WASM heap
+ * - Segmented mode: Multiple 4GB ArrayBuffers with virtual addressing
+ *
+ * @module memory/heap-manager
+ */
+
+import { MemoryStrategy, SegmentedLimits } from './capability.js';
+
+/**
+ * Memory segment for segmented heap mode
+ */
+export interface MemorySegment {
+  index: number;
+  buffer: ArrayBuffer;
+  used: number;
+}
+
+/**
+ * Allocation result
+ */
+export interface AllocationResult {
+  /** Virtual address for this allocation */
+  virtualAddress: number;
+  /** Allocated size in bytes */
+  size: number;
+  /** Direct view into the buffer */
+  view: Uint8Array;
+  /** Which strategy was used */
+  strategy: MemoryStrategy;
+  /** Segment index (segmented only) */
+  segmentIndex?: number;
+  /** Offset within segment (segmented only) */
+  segmentOffset?: number;
+}
+
+/**
+ * Heap manager statistics
+ */
+export interface HeapStats {
+  strategy: MemoryStrategy | null;
+  totalAllocated: number;
+  segmentCount: number;
+  memory64HeapSize: number;
+  allocated?: number;
+  limit?: number;
+  maxSize?: number;
+}
+
+/**
+ * HeapManager - Unified interface for both memory strategies
+ */
+export declare class HeapManager {
+  /**
+   * Initialize heap manager based on detected capabilities
+   */
+  init(): Promise<void>;
+
+  /**
+   * Allocate buffer for model data
+   * @param size - Size in bytes
+   */
+  allocate(size: number): AllocationResult;
+
+  /**
+   * Read data from virtual address
+   * @param virtualAddress - Virtual address to read from
+   * @param length - Number of bytes to read
+   */
+  read(virtualAddress: number, length: number): Uint8Array;
+
+  /**
+   * Write data to virtual address
+   * @param virtualAddress - Virtual address to write to
+   * @param data - Data to write
+   */
+  write(virtualAddress: number, data: Uint8Array): void;
+
+  /**
+   * Get raw buffer for GPU upload
+   * @param virtualAddress - Virtual address
+   * @param length - Number of bytes
+   */
+  getBufferSlice(virtualAddress: number, length: number): ArrayBuffer;
+
+  /**
+   * Get memory stats
+   */
+  getStats(): HeapStats;
+
+  /**
+   * Free all memory (for model unload)
+   */
+  reset(): void;
+}
+
+/**
+ * Get the global heap manager instance
+ */
+export function getHeapManager(): HeapManager;

package/src/memory/heap-manager.js

@@ -0,0 +1,264 @@
+
+
+import { getMemoryCapabilities } from './capability.js';
+import { AddressTable } from './address-table.js';
+import { getRuntimeConfig } from '../config/runtime.js';
+import { log } from '../debug/index.js';
+import { GB, MB } from '../config/schema/index.js';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const PAGE_SIZE = 65536; // WASM page = 64KB
+
+// ============================================================================
+// Heap Manager Class
+// ============================================================================
+
+
+export class HeapManager {
+  
+  #strategy = null;
+  
+  #memory64Heap = null;
+  
+  #segments = [];
+  
+  #addressTable = null;
+  
+  #initialized = false;
+  
+  #totalAllocated = 0;
+
+  
+  async init() {
+    if (this.#initialized) return;
+
+    const caps = await getMemoryCapabilities();
+    this.#strategy = caps.strategy;
+
+    if (this.#strategy === 'MEMORY64') {
+      await this.#initMemory64( (caps.maxHeapSize));
+    } else {
+      await this.#initSegmented( (caps.segmentedLimits));
+    }
+
+    this.#initialized = true;
+    log.info('HeapManager', `Initialized with strategy: ${this.#strategy}`);
+  }
+
+  
+  async #initMemory64(maxSize) {
+    // Start with 1GB, grow as needed
+    const initialPages = Math.ceil(GB / PAGE_SIZE);
+    const maxPages = Math.ceil(maxSize / PAGE_SIZE);
+
+    try {
+      this.#memory64Heap = new WebAssembly.Memory({
+        initial: initialPages,
+        maximum: maxPages,
+        // memory64: true would go here when syntax is finalized
+      });
+      log.info(
+        'HeapManager',
+        `Memory64 heap: ${initialPages} initial pages, ${maxPages} max`
+      );
+    } catch (err) {
+      log.error(
+        'HeapManager',
+        `Memory64 init failed, falling back to segmented: ${ (err).message}`
+      );
+      this.#strategy = 'SEGMENTED';
+      const { fallbackSegmentSizeBytes } = getRuntimeConfig().shared.memory.segmentAllocation;
+      await this.#initSegmented({ maxSegmentSize: fallbackSegmentSizeBytes, recommendedSegments: 8 });
+    }
+  }
+
+  
+  async #initSegmented(limits) {
+    this.#addressTable = new AddressTable(limits.maxSegmentSize);
+    this.#segments = [];
+
+    // Pre-allocate first segment
+    this.#allocateSegment();
+
+    log.info(
+      'HeapManager',
+      `Segmented heap: ${limits.maxSegmentSize / GB}GB per segment`
+    );
+  }
+
+  
+  #allocateSegment() {
+    const segmentSize =  (this.#addressTable).segmentSize;
+
+    try {
+      
+      const segment = {
+        index: this.#segments.length,
+        buffer: new ArrayBuffer(segmentSize),
+        used: 0,
+      };
+      this.#segments.push(segment);
+      log.info(
+        'HeapManager',
+        `Allocated segment ${segment.index}: ${(segmentSize / MB).toFixed(0)}MB`
+      );
+      return segment;
+    } catch (e) {
+      // If allocation fails, try smaller sizes
+      const { segmentFallbackSizes } = getRuntimeConfig().shared.memory.segmentAllocation;
+
+      for (const size of segmentFallbackSizes) {
+        if (size >= segmentSize) continue; // Already tried this size
+        try {
+          
+          const segment = {
+            index: this.#segments.length,
+            buffer: new ArrayBuffer(size),
+            used: 0,
+          };
+          this.#segments.push(segment);
+          // Update address table's segment size for consistency
+           (this.#addressTable).segmentSize = size;
+          log.warn('HeapManager', `Allocation fallback to ${size / MB}MB segment`);
+          return segment;
+        } catch {
+          continue;
+        }
+      }
+
+      throw new Error(
+        `Failed to allocate segment: ${ (e).message}. Try closing other tabs.`
+      );
+    }
+  }
+
+  
+  allocate(size) {
+    if (!this.#initialized) {
+      throw new Error('HeapManager not initialized. Call init() first.');
+    }
+
+    if (this.#strategy === 'MEMORY64') {
+      return this.#allocateMemory64(size);
+    } else {
+      return this.#allocateSegmented(size);
+    }
+  }
+
+  
+  #allocateMemory64(size) {
+    const buffer =  (this.#memory64Heap).buffer;
+    const offset = this.#totalAllocated;
+
+    // Grow if needed
+    if (offset + size > buffer.byteLength) {
+      const neededPages = Math.ceil((offset + size - buffer.byteLength) / PAGE_SIZE);
+       (this.#memory64Heap).grow(neededPages);
+    }
+
+    this.#totalAllocated += size;
+
+    return {
+      virtualAddress: offset,
+      size,
+      view: new Uint8Array( (this.#memory64Heap).buffer, offset, size),
+      strategy: 'MEMORY64',
+    };
+  }
+
+  
+  #allocateSegmented(size) {
+    // Find segment with enough space, or allocate new one
+    let segment = this.#segments.find((s) => s.buffer.byteLength - s.used >= size);
+
+    if (!segment) {
+      segment = this.#allocateSegment();
+    }
+
+    const offset = segment.used;
+    segment.used += size;
+    this.#totalAllocated += size;
+
+    const virtualAddress =  (this.#addressTable).encode(segment.index, offset);
+
+    return {
+      virtualAddress,
+      size,
+      view: new Uint8Array(segment.buffer, offset, size),
+      segmentIndex: segment.index,
+      segmentOffset: offset,
+      strategy: 'SEGMENTED',
+    };
+  }
+
+  
+  read(virtualAddress, length) {
+    if (this.#strategy === 'MEMORY64') {
+      return new Uint8Array( (this.#memory64Heap).buffer, virtualAddress, length);
+    } else {
+      const { segmentIndex, offset } =  (this.#addressTable).decode(virtualAddress);
+      const segment = this.#segments[segmentIndex];
+      return new Uint8Array(segment.buffer, offset, length);
+    }
+  }
+
+  
+  write(virtualAddress, data) {
+    const view = this.read(virtualAddress, data.length);
+    view.set(data);
+  }
+
+  
+  getBufferSlice(virtualAddress, length) {
+    if (this.#strategy === 'MEMORY64') {
+      // Return a copy for GPU upload (can't share WASM memory directly)
+      const slice = new ArrayBuffer(length);
+      new Uint8Array(slice).set(
+        new Uint8Array( (this.#memory64Heap).buffer, virtualAddress, length)
+      );
+      return slice;
+    } else {
+      const { segmentIndex, offset } =  (this.#addressTable).decode(virtualAddress);
+      const segment = this.#segments[segmentIndex];
+      return segment.buffer.slice(offset, offset + length);
+    }
+  }
+
+  
+  getStats() {
+    return {
+      strategy: this.#strategy,
+      totalAllocated: this.#totalAllocated,
+      segmentCount: this.#segments.length,
+      memory64HeapSize: this.#memory64Heap?.buffer.byteLength || 0,
+    };
+  }
+
+  
+  reset() {
+    if (this.#strategy === 'SEGMENTED') {
+      this.#segments = [];
+      this.#allocateSegment();
+    }
+    // Memory64 heap can't be shrunk, but we can reset allocation pointer
+    this.#totalAllocated = 0;
+  }
+}
+
+// ============================================================================
+// Singleton
+// ============================================================================
+
+
+let heapManagerInstance = null;
+
+
+export function getHeapManager() {
+  if (!heapManagerInstance) {
+    heapManagerInstance = new HeapManager();
+  }
+  return heapManagerInstance;
+}

package/src/memory/unified-detect.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Unified Memory Detection
+ * Agent-A | Domain: memory/
+ *
+ * Detects if system has unified memory (CPU/GPU share RAM):
+ * - Apple Silicon (M1/M2/M3/M4/M5)
+ * - AMD Strix Halo (Ryzen AI Max)
+ * - Other APUs with large shared memory
+ *
+ * @module memory/unified-detect
+ */
+
+/**
+ * Apple Silicon detection result
+ */
+export interface AppleSiliconInfo {
+  isApple: boolean;
+  mSeriesGen?: number | null;
+  vendor?: string;
+  device?: string;
+  description?: string;
+}
+
+/**
+ * AMD unified memory detection result
+ */
+export interface AMDUnifiedInfo {
+  isAMDUnified: boolean;
+  isStrix?: boolean;
+  vendor?: string;
+  device?: string;
+  description?: string;
+}
+
+/**
+ * WebGPU buffer limit indicators
+ */
+export interface LimitIndicators {
+  largeBuffers: boolean;
+  maxBufferSize?: number;
+  maxStorageBufferBindingSize?: number;
+}
+
+/**
+ * Unified memory detection result
+ */
+export interface UnifiedMemoryInfo {
+  isUnified: boolean;
+  apple?: AppleSiliconInfo;
+  amd?: AMDUnifiedInfo;
+  limits?: LimitIndicators;
+  estimatedMemoryGB?: number | null;
+  reason: string;
+}
+
+/**
+ * Main unified memory detection
+ */
+export function detectUnifiedMemory(): Promise<UnifiedMemoryInfo>;