specmem-hardwicksoftware 3.5.99

package/dist/watcher/tsCompiler.js

@@ -0,0 +1,212 @@
+/**
+ * tsCompiler.ts - TypeScript Compilation Watcher for Hot Reload
+ *
+ * watches for TS changes and triggers compilation
+ * part of the hot reload system - compiles then signals for reload
+ *
+ * Features:
+ * - Debounced compilation (prevents rapid recompiles)
+ * - Event emission for compile success/error
+ * - Queue system for pending compiles
+ * - Non-blocking async compilation
+ */
+import { spawn } from 'child_process';
+import { logger } from '../utils/logger.js';
+import { EventEmitter } from 'events';
+import { getSpawnEnv } from '../utils/index.js';
+/**
+ * TypeScriptCompiler - handles TypeScript compilation for hot reload
+ *
+ * fr fr this is the compiler that makes hot reload work
+ * emits events when compile succeeds or fails
+ */
+export class TypeScriptCompiler extends EventEmitter {
+    isCompiling = false;
+    pendingCompile = false;
+    debounceTimer = null;
+    debounceMs;
+    cwd;
+    tscArgs;
+    verbose;
+    // stats tracking
+    stats = {
+        totalCompiles: 0,
+        successfulCompiles: 0,
+        failedCompiles: 0,
+        lastCompileTime: null,
+        lastCompileDuration: 0,
+        lastError: null
+    };
+    constructor(config = {}) {
+        super();
+        this.debounceMs = config.debounceMs ?? 500;
+        this.cwd = config.cwd ?? '/specmem';
+        this.tscArgs = config.tscArgs ?? ['--noEmit', 'false'];
+        this.verbose = config.verbose ?? false;
+    }
+    /**
+     * queueCompile - Queue a compilation with debouncing
+     *
+     * yooo queuing compile with debounce so we dont spam tsc
+     */
+    queueCompile() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        if (this.verbose) {
+            logger.debug('[TSCompiler] Compile queued, debouncing...');
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            this.compile();
+        }, this.debounceMs);
+    }
+    /**
+     * compile - Run TypeScript compilation
+     *
+     * fr fr running tsc and emitting events
+     */
+    async compile() {
+        if (this.isCompiling) {
+            this.pendingCompile = true;
+            logger.debug('[TSCompiler] Compile already in progress, queuing another');
+            return false;
+        }
+        this.isCompiling = true;
+        this.stats.totalCompiles++;
+        logger.info('[TSCompiler] Starting TypeScript compilation...');
+        return new Promise((resolve) => {
+            const startTime = Date.now();
+            // spawn tsc process
+            // bruh ALWAYS use getSpawnEnv for project isolation
+            const tsc = spawn('npx', ['tsc', ...this.tscArgs], {
+                cwd: this.cwd,
+                shell: true,
+                env: getSpawnEnv()
+            });
+            let stdout = '';
+            let stderr = '';
+            tsc.stdout?.on('data', (data) => {
+                stdout += data.toString();
+                if (this.verbose) {
+                    logger.debug({ data: data.toString() }, '[TSCompiler] stdout');
+                }
+            });
+            tsc.stderr?.on('data', (data) => {
+                stderr += data.toString();
+                if (this.verbose) {
+                    logger.debug({ data: data.toString() }, '[TSCompiler] stderr');
+                }
+            });
+            tsc.on('error', (error) => {
+                const duration = Date.now() - startTime;
+                this.isCompiling = false;
+                this.stats.failedCompiles++;
+                this.stats.lastCompileTime = new Date();
+                this.stats.lastCompileDuration = duration;
+                this.stats.lastError = error.message;
+                logger.error({ error }, '[TSCompiler] Failed to spawn tsc process');
+                const result = {
+                    success: false,
+                    duration,
+                    stderr: error.message
+                };
+                this.emit('compile:error', result);
+                resolve(false);
+                this.handlePendingCompile();
+            });
+            tsc.on('close', (code) => {
+                const duration = Date.now() - startTime;
+                this.isCompiling = false;
+                this.stats.lastCompileTime = new Date();
+                this.stats.lastCompileDuration = duration;
+                const result = {
+                    success: code === 0,
+                    duration,
+                    code: code ?? undefined,
+                    stdout: stdout || undefined,
+                    stderr: stderr || undefined
+                };
+                if (code === 0) {
+                    this.stats.successfulCompiles++;
+                    this.stats.lastError = null;
+                    logger.info({ duration }, '[TSCompiler] Compilation successful');
+                    this.emit('compile:success', result);
+                    resolve(true);
+                }
+                else {
+                    this.stats.failedCompiles++;
+                    this.stats.lastError = stderr || `Exit code: ${code}`;
+                    logger.error({ code, stderr }, '[TSCompiler] Compilation failed');
+                    this.emit('compile:error', result);
+                    resolve(false);
+                }
+                this.handlePendingCompile();
+            });
+        });
+    }
+    /**
+     * handlePendingCompile - Process any queued compile requests
+     */
+    handlePendingCompile() {
+        if (this.pendingCompile) {
+            this.pendingCompile = false;
+            logger.debug('[TSCompiler] Processing pending compile...');
+            // slight delay to prevent rapid succession
+            setTimeout(() => this.compile(), 100);
+        }
+    }
+    /**
+     * cancelPending - Cancel any pending compilation
+     */
+    cancelPending() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        this.pendingCompile = false;
+        logger.debug('[TSCompiler] Pending compile cancelled');
+    }
+    /**
+     * isCurrentlyCompiling - Check if compilation is in progress
+     */
+    isCurrentlyCompiling() {
+        return this.isCompiling;
+    }
+    /**
+     * hasPendingCompile - Check if there's a pending compile
+     */
+    hasPendingCompile() {
+        return this.pendingCompile || this.debounceTimer !== null;
+    }
+    /**
+     * getStats - Returns compiler statistics
+     */
+    getStats() {
+        return {
+            ...this.stats,
+            isCompiling: this.isCompiling,
+            hasPending: this.hasPendingCompile()
+        };
+    }
+    /**
+     * setDebounceMs - Update debounce delay
+     */
+    setDebounceMs(ms) {
+        this.debounceMs = ms;
+        logger.debug({ debounceMs: ms }, '[TSCompiler] Debounce delay updated');
+    }
+    /**
+     * setCwd - Update working directory
+     */
+    setCwd(cwd) {
+        this.cwd = cwd;
+        logger.debug({ cwd }, '[TSCompiler] Working directory updated');
+    }
+}
+// LOW-12 FIX: Make default singleton cwd configurable via env var
+// This allows per-project TypeScript compilation instead of hardcoded /specmem
+export const tsCompiler = new TypeScriptCompiler({
+    cwd: process.env.SPECMEM_PROJECT_PATH || process.cwd() || '/specmem'
+});
+//# sourceMappingURL=tsCompiler.js.map

package/dist/watcher/tsCompiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsCompiler.js","sourceRoot":"","sources":["../../src/watcher/tsCompiler.ts"],"names":[],"mappings":"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"}

package/embedding-sandbox/Dockerfile

@@ -0,0 +1,77 @@
+# ============================================
+# SPECMEM SANDBOXED EMBEDDING SERVICE
+# ============================================
+#
+# SECURITY ARCHITECTURE:
+#   - NO NETWORK ACCESS (run with --network none)
+#   - Read-only root filesystem
+#   - No capabilities (--cap-drop ALL)
+#   - Runs as non-root user
+#   - Only Unix socket communication
+#   - Model weights pre-downloaded (no runtime network)
+#
+# Build:
+#   docker build -t specmem-embedding .
+#
+# Run (AIR-GAPPED):
+#   docker run --rm \
+#     --network none \
+#     --read-only \
+#     --cap-drop ALL \
+#     --security-opt no-new-privileges \
+#     -v /tmp/specmem-sockets:/sockets \
+#     -e SOCKET_PATH=/sockets/embeddings.sock \
+#     specmem-embedding
+#
+# ============================================
+
+FROM node:20-slim
+
+# Create non-root user with minimal permissions
+RUN useradd --create-home --shell /bin/false embed && \
+    mkdir -p /home/embed/.cache/huggingface && \
+    chown -R embed:embed /home/embed
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package.json ./
+
+# Install dependencies (network needed during build only)
+RUN npm install --production && \
+    npm cache clean --force && \
+    rm -rf /root/.npm
+
+# Copy application code
+COPY server.mjs download-model.mjs ./
+
+# Set environment for model download
+ENV HF_HOME=/home/embed/.cache/huggingface
+ENV XDG_CACHE_HOME=/home/embed/.cache
+
+# Download model during build (this is the key step!)
+# Model will be baked into the image
+RUN node download-model.mjs && \
+    echo "Model downloaded and baked into image"
+
+# Change ownership
+RUN chown -R embed:embed /app /home/embed/.cache
+
+# Switch to non-root user
+USER embed
+
+# Environment
+ENV NODE_ENV=production
+ENV SOCKET_PATH=/sockets/embeddings.sock
+ENV HF_HOME=/home/embed/.cache/huggingface
+ENV XDG_CACHE_HOME=/home/embed/.cache
+
+# Health check via socket existence (uses SOCKET_PATH env var set at runtime)
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
+  CMD test -S "${SOCKET_PATH:-/sockets/embeddings.sock}" || exit 1
+
+# No network, no capabilities, read-only - these are enforced at runtime
+# via docker run flags, not in the Dockerfile
+
+CMD ["node", "server.mjs"]

package/embedding-sandbox/Dockerfile.frankenstein

@@ -0,0 +1,91 @@
+# ============================================
+# FRANKENSTEIN EMBEDDINGS - QQMS v2 EDITION
+# ============================================
+#
+# FEATURES:
+#   - QQMS v2 queue management (FIFO + ACK)
+#   - Priority aging (prevents starvation)
+#   - Dead Letter Queue (DLQ) for failed items
+#   - PostgreSQL-backed overflow queue
+#   - CPU-throttled (20% cap via --cpus=0.2)
+#   - Auto-pause when idle
+#
+# Build:
+#   docker build -f Dockerfile.frankenstein -t frankenstein-qqmsv2 .
+#
+# Run (THROTTLED with PostgreSQL):
+#   docker run -d \
+#     --name frankenstein-qqmsv2 \
+#     --cpus=0.2 \
+#     --memory=2g \
+#     -v /tmp/specmem-sockets:/sockets \
+#     -e SOCKET_PATH=/sockets/embeddings.sock \
+#     -e SPECMEM_DB_HOST=host.docker.internal \
+#     -e SPECMEM_DB_NAME=specmem \
+#     -e SPECMEM_DB_USER=specmem \
+#     -e SPECMEM_DB_PASSWORD=specmem \
+#     --add-host=host.docker.internal:host-gateway \
+#     frankenstein-qqmsv2
+#
+# ============================================
+
+FROM python:3.12-slim
+
+# Install system dependencies (including libpq for PostgreSQL)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    g++ \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user
+RUN useradd --create-home --shell /bin/false embed && \
+    mkdir -p /home/embed/.cache && \
+    mkdir -p /overflow && \
+    chown -R embed:embed /home/embed /overflow
+
+WORKDIR /app
+
+# Install Python dependencies
+COPY requirements-frankenstein.txt ./
+RUN pip install --no-cache-dir -r requirements-frankenstein.txt
+
+# Copy application code (including QQMS v2 queue system)
+COPY frankenstein-embeddings.py overflow_queue.py qqms_v2.py ./
+
+# Pre-download model during build
+ENV TRANSFORMERS_CACHE=/home/embed/.cache/huggingface
+RUN python3 -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')" && \
+    chown -R embed:embed /home/embed/.cache
+
+# Change ownership
+RUN chown -R embed:embed /app
+
+# Switch to non-root user
+USER embed
+
+# Environment - Socket and throttling
+ENV SOCKET_PATH=/sockets/embeddings.sock
+ENV MAX_RPS=3
+ENV BASE_DELAY=200
+ENV CPU_THRESHOLD=15
+
+# QQMS v2 settings (PostgreSQL-backed overflow)
+ENV QQMS_V2_ENABLED=1
+ENV SPECMEM_DB_HOST=localhost
+ENV SPECMEM_DB_PORT=5432
+ENV SPECMEM_DB_NAME=specmem
+ENV SPECMEM_DB_USER=specmem
+ENV SPECMEM_DB_PASSWORD=specmem
+
+# HuggingFace cache settings (model baked in)
+ENV HF_HOME=/home/embed/.cache/huggingface
+ENV TRANSFORMERS_CACHE=/home/embed/.cache/huggingface
+ENV SENTENCE_TRANSFORMERS_HOME=/home/embed/.cache/huggingface
+
+# Healthcheck - uses SOCKET_PATH env var
+HEALTHCHECK --interval=30s --timeout=5s --start-period=60s \
+  CMD test -S "${SOCKET_PATH}" || exit 1
+
+# Default CMD enables QQMS v2 with service mode (no idle shutdown)
+CMD ["python3", "frankenstein-embeddings.py", "--service", "--max-rps", "3", "--base-delay", "200", "--cpu-threshold", "15"]

package/embedding-sandbox/README.md

@@ -0,0 +1,193 @@
+# SpecMem Embedding Sandbox
+
+Air-gapped embedding service for SpecMem. Provides real ML embeddings using the `all-MiniLM-L6-v2` model with **zero network access**.
+
+## Why Air-Gapped?
+
+**Security First.** The embedding model runs in a Docker container with:
+
+- **`--network none`**: Absolutely no network access. Cannot phone home.
+- **`--read-only`**: Read-only root filesystem. Cannot write to disk.
+- **`--cap-drop ALL`**: No Linux capabilities. Minimal privileges.
+- **`--security-opt no-new-privileges`**: Cannot escalate privileges.
+- **Non-root user**: Runs as unprivileged `embed` user.
+- **Unix socket only**: No TCP ports. Communication via local socket only.
+
+This means the embedding service:
+- Cannot send your data anywhere
+- Cannot download anything at runtime
+- Cannot modify its own code
+- Cannot access your filesystem
+- Can ONLY receive text and return embeddings
+
+## Architecture
+
+```
++------------------+        Unix Socket         +------------------+
+|                  |  ${SPECMEM_SOCKET_DIR}/    |                  |
+|  SpecMem Server  | ----------------------->   |  Sandbox         |
+|  (Node.js)       |   embeddings.sock          |  Container       |
+|                  | <-----------------------   |  (Docker)        |
+|                  |    384-dim vectors         |                  |
++------------------+                            +------------------+
+                                                       |
+                                                       | --network none
+                                                       | --read-only
+                                                       | --cap-drop ALL
+                                                       v
+                                                   [NO NETWORK]
+```
+
+## Quick Start
+
+### 1. Start the Sandbox
+
+```bash
+./start-sandbox.sh
+```
+
+This will:
+1. Build the Docker image
+2. Download the model (~23MB) to a Docker volume
+3. Start the container with all security restrictions
+4. Create the Unix socket at `${SPECMEM_HOME}/run/embeddings.sock`
+
+### 2. Stop the Sandbox
+
+```bash
+./stop-sandbox.sh
+```
+
+Or manually:
+```bash
+docker stop specmem-embedding
+```
+
+### 3. View Logs
+
+```bash
+docker logs specmem-embedding
+docker logs -f specmem-embedding  # Follow mode
+```
+
+## Pre-downloading the Model
+
+The model is automatically downloaded on first run. To pre-download manually:
+
+```bash
+# Create the volume
+docker volume create specmem-model-cache
+
+# Build the image
+docker build -t specmem-embedding .
+
+# Download the model (requires network)
+docker run --rm \
+  -v specmem-model-cache:/home/embed/.cache \
+  specmem-embedding \
+  node download-model.mjs
+```
+
+After this, the container can run fully air-gapped.
+
+## Model Details
+
+- **Model**: `Xenova/all-MiniLM-L6-v2` (ONNX version)
+- **Dimensions**: 384
+- **Size**: ~23MB
+- **Library**: `@huggingface/transformers` (browser/Node.js inference)
+
+This is the same architecture as sentence-transformers but runs locally without Python.
+
+## Integration with SpecMem
+
+The client in `client.ts` handles:
+
+1. Checking if the sandbox socket exists
+2. Sending text to the sandbox for embedding
+3. Falling back to hash-based embeddings if sandbox unavailable
+
+```typescript
+import { getSandboxedEmbeddingClient } from './embedding-sandbox/client.js';
+
+const client = getSandboxedEmbeddingClient();
+
+// Automatically uses sandbox if available, hash fallback otherwise
+const embedding = await client.generateEmbedding("Hello world");
+```
+
+## Socket Protocol
+
+The sandbox uses newline-delimited JSON over Unix socket:
+
+**Request:**
+```json
+{"type": "embed", "text": "Your text here"}\n
+```
+
+**Response:**
+```json
+{"embedding": [0.123, -0.456, ...], "dimension": 384, "model": "Xenova/all-MiniLM-L6-v2"}\n
+```
+
+**Error:**
+```json
+{"error": "Error message"}\n
+```
+
+## Troubleshooting
+
+### Socket not found
+
+```bash
+# Check if container is running
+docker ps | grep specmem-embedding
+
+# Check socket directory
+ls -la /tmp/specmem-sockets/
+
+# Restart the sandbox
+./stop-sandbox.sh && ./start-sandbox.sh
+```
+
+### Model not loading
+
+```bash
+# Check container logs
+docker logs specmem-embedding
+
+# Re-download model
+docker volume rm specmem-model-cache
+./start-sandbox.sh
+```
+
+### Permission denied on socket
+
+```bash
+# Fix socket directory permissions
+sudo chmod 755 /tmp/specmem-sockets
+```
+
+## Security Verification
+
+Verify the container has no network:
+
+```bash
+# Try to ping from inside container (should fail)
+docker exec specmem-embedding ping -c 1 google.com
+# Expected: ping: bad address 'google.com'
+
+# Check network settings
+docker inspect specmem-embedding | grep -A 10 "NetworkSettings"
+# Should show "NetworkMode": "none"
+```
+
+## Files
+
+- `Dockerfile` - Container configuration
+- `server.mjs` - Embedding server (runs inside container)
+- `download-model.mjs` - Model pre-download script
+- `client.ts` - TypeScript client for SpecMem
+- `start-sandbox.sh` - Start the sandbox
+- `stop-sandbox.sh` - Stop the sandbox
+- `package.json` - Dependencies