groove-dev 0.27.77 → 0.27.78

package/moe-training/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@groove-dev/moe-training",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MoE TrajectoryCapture client — captures agent session data into structured Trajectory Envelopes",
+  "license": "FSL-1.1-Apache-2.0",
+  "exports": {
+    ".": "./client/index.js",
+    "./shared/*": "./shared/*.js"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "start:server": "node server/index.js"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "uuid": "^9.0.0",
+    "express": "^4.18.0"
+  }
+}

package/moe-training/server/enrichment.js

@@ -0,0 +1,24 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+// TODO: LLM-as-a-Judge — classify each step's cognitive target
+//   (syntactic/semantic/strategic/corrective/coordinative)
+//   using a small model call after stitching
+
+// TODO: Model fingerprint verification — confirm the claimed model_engine
+//   matches the output style using an LLM classifier
+
+// TODO: Quality assessment — score trajectory coherence, tool usage
+//   efficiency, and error recovery patterns
+
+export class EnrichmentPipeline {
+  async enrich(stitchedTrajectory) {
+    return {
+      ...stitchedTrajectory,
+      enrichment: {
+        cognitive_target: 'pending',
+        model_verified: 'pending',
+        quality_assessment: 'pending',
+      },
+    };
+  }
+}

package/moe-training/server/index.js

@@ -0,0 +1,119 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import express from 'express';
+import { SessionRegistry } from './session-registry.js';
+import { EnvelopeVerifier } from './verifier.js';
+import { EnvelopeStorage } from './storage.js';
+import { TrajectoryStitcher } from './stitcher.js';
+import { TrajectoryScorer } from './scoring.js';
+import { ContributorLedger } from './ledger.js';
+import { EnrichmentPipeline } from './enrichment.js';
+import { CentralStats } from './stats.js';
+import { createSessionRoutes } from './routes/sessions.js';
+import { createIngestRoutes } from './routes/ingest.js';
+import { createStatsRoutes } from './routes/stats.js';
+import { MODEL_TIERS, QUALITY_MULTIPLIERS } from '../shared/constants.js';
+
+const PORT = parseInt(process.env.GROOVE_CENTRAL_PORT, 10) || 8443;
+
+const sessionRegistry = new SessionRegistry();
+const storage = new EnvelopeStorage();
+const ledger = new ContributorLedger();
+const verifier = new EnvelopeVerifier(sessionRegistry);
+const stitcher = new TrajectoryStitcher(storage);
+const scorer = new TrajectoryScorer({ MODEL_TIERS, QUALITY_MULTIPLIERS });
+const enrichment = new EnrichmentPipeline();
+const centralStats = new CentralStats(storage, ledger, sessionRegistry);
+
+const app = express();
+
+app.use((_req, res, next) => {
+  res.header('Access-Control-Allow-Origin', '*');
+  res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.header('Access-Control-Allow-Headers', 'Content-Type');
+  if (_req.method === 'OPTIONS') return res.sendStatus(204);
+  next();
+});
+
+app.use(express.json({ limit: '5mb' }));
+
+// Per-IP rate limiting
+const ipWindows = new Map();
+const RATE_LIMIT_PER_MINUTE = 100;
+const RATE_LIMIT_PER_HOUR = 1000;
+
+setInterval(() => {
+  const now = Date.now();
+  for (const [ip, entry] of ipWindows) {
+    if (now - entry.minuteStart > 120_000 && now - entry.hourStart > 7200_000) {
+      ipWindows.delete(ip);
+    }
+  }
+}, 300_000);
+
+app.use((req, res, next) => {
+  const ip = req.headers['x-forwarded-for']?.split(',')[0]?.trim() || req.ip;
+  const now = Date.now();
+
+  let entry = ipWindows.get(ip);
+  if (!entry) {
+    entry = { minuteCount: 0, minuteStart: now, hourCount: 0, hourStart: now };
+    ipWindows.set(ip, entry);
+  }
+
+  if (now - entry.minuteStart > 60_000) {
+    entry.minuteCount = 0;
+    entry.minuteStart = now;
+  }
+  if (now - entry.hourStart > 3600_000) {
+    entry.hourCount = 0;
+    entry.hourStart = now;
+  }
+
+  entry.minuteCount++;
+  entry.hourCount++;
+
+  if (entry.minuteCount > RATE_LIMIT_PER_MINUTE) {
+    return res.status(429).json({ error: 'Too Many Requests', retryAfter: Math.ceil((entry.minuteStart + 60_000 - now) / 1000) });
+  }
+  if (entry.hourCount > RATE_LIMIT_PER_HOUR) {
+    return res.status(429).json({ error: 'Too Many Requests', retryAfter: Math.ceil((entry.hourStart + 3600_000 - now) / 1000) });
+  }
+
+  next();
+});
+
+app.use((req, res, next) => {
+  const start = Date.now();
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    console.log(`[${new Date().toISOString()}] ${req.method} ${req.path} ${res.statusCode} ${duration}ms`);
+  });
+  next();
+});
+
+app.get('/health', (_req, res) => res.json({ status: 'ok', uptime: process.uptime() }));
+
+app.use(createSessionRoutes(sessionRegistry));
+app.use(createIngestRoutes(verifier, storage, stitcher, scorer, enrichment, ledger, sessionRegistry));
+app.use(createStatsRoutes(centralStats));
+
+const server = app.listen(PORT, () => {
+  console.log(`[central-command] listening on port ${PORT}`);
+});
+
+function shutdown() {
+  console.log('[central-command] shutting down...');
+  server.close(() => {
+    sessionRegistry.close();
+    ledger.close();
+    console.log('[central-command] shut down complete');
+    process.exit(0);
+  });
+  setTimeout(() => process.exit(1), 5000);
+}
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+
+export { app, server };

package/moe-training/server/ledger.js

@@ -0,0 +1,110 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import Database from 'better-sqlite3';
+import { mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export class ContributorLedger {
+  constructor(dbPath = './data/ledger.db') {
+    const dir = join(dbPath, '..');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+    this.db = new Database(dbPath);
+    this.db.pragma('journal_mode = WAL');
+    this._createTables();
+  }
+
+  _createTables() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS credits (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        contributor_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        points REAL NOT NULL,
+        base_points INTEGER NOT NULL,
+        multiplier_breakdown TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      )
+    `);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS balances (
+        contributor_id TEXT PRIMARY KEY,
+        total_points REAL NOT NULL DEFAULT 0,
+        total_sessions INTEGER NOT NULL DEFAULT 0,
+        last_credit_at TEXT,
+        trust_score REAL NOT NULL DEFAULT 1.0
+      )
+    `);
+  }
+
+  credit(contributorId, sessionId, scoreResult) {
+    const now = new Date().toISOString();
+    const breakdown = JSON.stringify({
+      modelMultiplier: scoreResult.modelMultiplier,
+      correctionBonus: scoreResult.correctionBonus,
+      coordinationBonus: scoreResult.coordinationBonus,
+      errorRecoveryBonus: scoreResult.errorRecoveryBonus,
+      complexityBonus: scoreResult.complexityBonus,
+      qualityBonus: scoreResult.qualityBonus,
+    });
+
+    const txn = this.db.transaction(() => {
+      this.db.prepare(`
+        INSERT INTO credits (contributor_id, session_id, points, base_points, multiplier_breakdown, created_at)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(contributorId, sessionId, scoreResult.totalPoints, scoreResult.basePoints, breakdown, now);
+
+      const existing = this.db.prepare('SELECT * FROM balances WHERE contributor_id = ?').get(contributorId);
+      if (existing) {
+        this.db.prepare(`
+          UPDATE balances SET total_points = total_points + ?, total_sessions = total_sessions + 1, last_credit_at = ?
+          WHERE contributor_id = ?
+        `).run(scoreResult.totalPoints, now, contributorId);
+      } else {
+        this.db.prepare(`
+          INSERT INTO balances (contributor_id, total_points, total_sessions, last_credit_at, trust_score)
+          VALUES (?, ?, 1, ?, 1.0)
+        `).run(contributorId, scoreResult.totalPoints, now);
+      }
+    });
+    txn();
+  }
+
+  getBalance(contributorId) {
+    return this.db.prepare('SELECT * FROM balances WHERE contributor_id = ?').get(contributorId) || null;
+  }
+
+  getLeaderboard(limit = 50) {
+    return this.db.prepare('SELECT * FROM balances ORDER BY total_points DESC LIMIT ?').all(limit);
+  }
+
+  getCreditsForContributor(contributorId, limit = 100) {
+    return this.db.prepare(
+      'SELECT * FROM credits WHERE contributor_id = ? ORDER BY created_at DESC LIMIT ?'
+    ).all(contributorId, limit);
+  }
+
+  getDailyCredits(days = 7) {
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - days);
+
+    return this.db.prepare(`
+      SELECT DATE(created_at) as date, SUM(points) as totalPoints, COUNT(*) as totalSessions
+      FROM credits WHERE created_at > ? GROUP BY DATE(created_at) ORDER BY date
+    `).all(cutoff.toISOString());
+  }
+
+  adjustTrustScore(contributorId, delta) {
+    this.db.prepare(`
+      UPDATE balances SET trust_score = MAX(0, MIN(10, trust_score + ?)) WHERE contributor_id = ?
+    `).run(delta, contributorId);
+  }
+
+  getTotalPointsAwarded() {
+    const row = this.db.prepare('SELECT COALESCE(SUM(total_points), 0) as total FROM balances').get();
+    return row.total;
+  }
+
+  close() {
+    this.db.close();
+  }
+}

package/moe-training/server/routes/ingest.js

@@ -0,0 +1,96 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import { Router } from 'express';
+import { v4 as uuidv4 } from 'uuid';
+
+const MAX_ENVELOPES_PER_SESSION = 200;
+
+export function createIngestRoutes(verifier, storage, stitcher, scorer, enrichment, ledger, sessionRegistry) {
+  const router = Router();
+
+  router.post('/v1/training/ingest', async (req, res) => {
+    const envelope = req.body;
+
+    if (!envelope || !envelope.session_id) {
+      return res.status(400).json({ accepted: false, reason: 'malformed request: missing envelope or session_id' });
+    }
+
+    if (envelope.type === 'SESSION_CLOSE') {
+      const closeResult = verifier.verifyClose(envelope);
+      if (!closeResult.valid) {
+        return res.json({ accepted: false, reason: closeResult.reason });
+      }
+
+      // Server-generated envelope_id
+      const envelopeId = `env_${uuidv4()}`;
+      envelope.envelope_id = envelopeId;
+
+      // Dedup check
+      if (sessionRegistry.isEnvelopeProcessed(envelopeId)) {
+        return res.json({ accepted: false, reason: 'duplicate envelope' });
+      }
+
+      try {
+        storage.store(envelope);
+      } catch (err) {
+        if (err.message === 'STORAGE_QUOTA_EXCEEDED') {
+          return res.status(507).json({ accepted: false, reason: 'storage quota exceeded' });
+        }
+        throw err;
+      }
+
+      sessionRegistry.recordProcessedEnvelope(envelopeId, envelope.session_id);
+
+      try {
+        const stitched = stitcher.stitch(envelope.session_id);
+        if (stitched) {
+          const enriched = await enrichment.enrich(stitched);
+          const scoreResult = scorer.score(enriched);
+          const contributorId = stitched.contributor_id;
+          if (contributorId) {
+            ledger.credit(contributorId, envelope.session_id, scoreResult);
+          }
+        }
+      } catch (err) {
+        console.error(`[ingest] stitching/scoring error for session ${envelope.session_id}:`, err.message);
+      }
+
+      return res.json({ accepted: true, envelope_id: envelopeId });
+    }
+
+    // Per-session envelope limit
+    if (!sessionRegistry.checkEnvelopeCount(envelope.session_id, MAX_ENVELOPES_PER_SESSION)) {
+      return res.status(429).json({ accepted: false, reason: `session envelope limit exceeded (max ${MAX_ENVELOPES_PER_SESSION})` });
+    }
+
+    const result = verifier.verify(envelope);
+    if (!result.valid) {
+      return res.json({ accepted: false, reason: result.reason });
+    }
+
+    // Server-generated envelope_id
+    const envelopeId = `env_${uuidv4()}`;
+    envelope.envelope_id = envelopeId;
+
+    // Dedup check
+    if (sessionRegistry.isEnvelopeProcessed(envelopeId)) {
+      return res.json({ accepted: false, reason: 'duplicate envelope' });
+    }
+
+    try {
+      storage.store(envelope);
+    } catch (err) {
+      if (err.message === 'STORAGE_QUOTA_EXCEEDED') {
+        return res.status(507).json({ accepted: false, reason: 'storage quota exceeded' });
+      }
+      throw err;
+    }
+
+    sessionRegistry.recordProcessedEnvelope(envelopeId, envelope.session_id);
+    sessionRegistry.incrementEnvelopeCount(envelope.session_id);
+
+    res.json({ accepted: true, envelope_id: envelopeId });
+  });
+
+  return router;
+}

package/moe-training/server/routes/sessions.js

@@ -0,0 +1,43 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import { Router } from 'express';
+
+export function createSessionRoutes(sessionRegistry) {
+  const router = Router();
+
+  router.post('/v1/sessions/open', (req, res) => {
+    const { session_id, public_key, provider, model, machine_fingerprint, app_version_hash, groove_version } = req.body;
+
+    if (!session_id || !public_key || !provider || !model || !machine_fingerprint || !app_version_hash || !groove_version) {
+      return res.status(400).json({ error: 'missing required fields', required: ['session_id', 'public_key', 'provider', 'model', 'machine_fingerprint', 'app_version_hash', 'groove_version'] });
+    }
+
+    const result = sessionRegistry.openSession(session_id, public_key, provider, model, machine_fingerprint, app_version_hash, groove_version);
+
+    if (result.rateLimited) {
+      return res.status(429).json({ error: 'rate limited: too many sessions from this machine' });
+    }
+
+    res.json({ server_public_key: result.serverPublicKey });
+  });
+
+  router.post('/v1/sessions/close', (req, res) => {
+    const { session_id } = req.body;
+    if (!session_id) {
+      return res.status(400).json({ error: 'missing session_id' });
+    }
+
+    const session = sessionRegistry.getSession(session_id);
+    if (!session) {
+      return res.status(404).json({ error: 'unknown session_id' });
+    }
+    if (session.status === 'closed') {
+      return res.json({ closed: true, already_closed: true });
+    }
+
+    sessionRegistry.closeSession(session_id);
+    res.json({ closed: true });
+  });
+
+  return router;
+}

package/moe-training/server/routes/stats.js

@@ -0,0 +1,31 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import { Router } from 'express';
+
+export function createStatsRoutes(centralStats) {
+  const router = Router();
+
+  router.get('/v1/stats/summary', (_req, res) => {
+    res.json(centralStats.summary());
+  });
+
+  router.get('/v1/stats/daily', (req, res) => {
+    const days = parseInt(req.query.days, 10) || 7;
+    res.json(centralStats.dailyGrowth(days));
+  });
+
+  router.get('/v1/stats/models', (_req, res) => {
+    res.json(centralStats.modelBreakdown());
+  });
+
+  router.get('/v1/stats/providers', (_req, res) => {
+    res.json(centralStats.providerBreakdown());
+  });
+
+  router.get('/v1/stats/leaderboard', (req, res) => {
+    const limit = parseInt(req.query.limit, 10) || 10;
+    res.json(centralStats.topContributors(limit));
+  });
+
+  return router;
+}

package/moe-training/server/scoring.js

@@ -0,0 +1,63 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+export class TrajectoryScorer {
+  constructor(constants) {
+    this.modelTiers = constants.MODEL_TIERS || {};
+    this.multipliers = constants.QUALITY_MULTIPLIERS || {};
+  }
+
+  score(stitchedTrajectory) {
+    const steps = stitchedTrajectory.trajectory_log || [];
+    const metadata = stitchedTrajectory.metadata || {};
+
+    // DERIVE from actual steps — never trust client-reported outcome
+    const correctionSteps = steps.filter(s => s.type === 'correction').length;
+    const coordinationSteps = steps.filter(s => s.type === 'coordination').length;
+    const errorSteps = steps.filter(s => s.type === 'error').length;
+    const resolutionSteps = steps.filter(s => s.type === 'resolution').length;
+    const errorsRecovered = Math.min(errorSteps, resolutionSteps);
+
+    const basePoints = Math.min(steps.length, 5000);
+
+    const modelEngine = metadata.model_engine || '';
+    const modelMultiplier = this.modelTiers[modelEngine] || 1;
+
+    // Correction bonus: 10x on ACTUAL correction steps, capped at 30% of trajectory
+    const maxCorrectionSteps = Math.floor(steps.length * 0.3);
+    const cappedCorrectionSteps = Math.min(correctionSteps, maxCorrectionSteps);
+    const correctionBonus = cappedCorrectionSteps * (this.multipliers.correction || 10);
+
+    // Coordination bonus: 5x on ACTUAL coordination steps, capped at 20% of trajectory
+    const maxCoordSteps = Math.floor(steps.length * 0.2);
+    const cappedCoordSteps = Math.min(coordinationSteps, maxCoordSteps);
+    const coordinationBonus = cappedCoordSteps * (this.multipliers.coordination || 5);
+
+    // Error recovery: 3x if errors AND resolutions exist in the trajectory
+    const errorRecoveryBonus = errorsRecovered > 0 ? Math.min(errorsRecovered, errorSteps) * (this.multipliers.errorRecovery || 3) : 0;
+
+    // Complexity bonus: only if validated value
+    const validComplexity = ['light', 'medium', 'heavy'];
+    const complexityBonus = validComplexity.includes(metadata.task_complexity) && metadata.task_complexity === 'heavy'
+      ? basePoints * 1
+      : 0;
+
+    // Quality bonus: server-derived from trajectory completeness
+    const hasResolution = resolutionSteps > 0;
+    const reasonableLength = steps.length >= 5 && steps.length <= 5000;
+    const subtotal = (basePoints * modelMultiplier) + correctionBonus + coordinationBonus + errorRecoveryBonus + complexityBonus;
+    const qualityBonus = (hasResolution && reasonableLength) ? Math.floor(subtotal * 0.1) : 0;
+
+    const totalPoints = subtotal + qualityBonus;
+
+    return {
+      basePoints,
+      modelMultiplier,
+      correctionBonus,
+      coordinationBonus,
+      errorRecoveryBonus,
+      complexityBonus,
+      qualityBonus,
+      totalPoints,
+    };
+  }
+}

package/moe-training/server/session-registry.js

@@ -0,0 +1,156 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import Database from 'better-sqlite3';
+import { mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { generateECDHKeypair, deriveSharedSecret } from '../shared/crypto.js';
+
+export class SessionRegistry {
+  constructor(dbPath = './data/sessions.db') {
+    const dir = join(dbPath, '..');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+    this.db = new Database(dbPath);
+    this.db.pragma('journal_mode = WAL');
+    this.db.pragma('foreign_keys = ON');
+    this._createTables();
+  }
+
+  _createTables() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sessions (
+        session_id TEXT PRIMARY KEY,
+        server_private_key TEXT NOT NULL,
+        server_public_key TEXT NOT NULL,
+        shared_secret TEXT NOT NULL,
+        client_public_key TEXT NOT NULL,
+        provider TEXT NOT NULL,
+        model TEXT NOT NULL,
+        machine_fingerprint TEXT NOT NULL,
+        app_version_hash TEXT NOT NULL,
+        groove_version TEXT NOT NULL,
+        expected_sequence INTEGER DEFAULT 0,
+        envelope_count INTEGER DEFAULT 0,
+        status TEXT DEFAULT 'active',
+        created_at TEXT NOT NULL,
+        closed_at TEXT
+      )
+    `);
+
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS processed_envelopes (
+        envelope_id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        processed_at TEXT NOT NULL
+      )
+    `);
+
+    // Migration: add envelope_count if table exists but column doesn't
+    try {
+      this.db.prepare('SELECT envelope_count FROM sessions LIMIT 1').get();
+    } catch {
+      try { this.db.exec('ALTER TABLE sessions ADD COLUMN envelope_count INTEGER DEFAULT 0'); } catch { /* already exists */ }
+    }
+  }
+
+  openSession(sessionId, clientPublicKey, provider, model, machineFingerprint, appVersionHash, grooveVersion) {
+    if (this.rateLimitCheck(machineFingerprint)) {
+      return { rateLimited: true };
+    }
+
+    const keypair = generateECDHKeypair();
+    const sharedSecret = deriveSharedSecret(keypair.privateKey, clientPublicKey);
+
+    this.db.prepare(`
+      INSERT INTO sessions (session_id, server_private_key, server_public_key, shared_secret,
+        client_public_key, provider, model, machine_fingerprint, app_version_hash,
+        groove_version, expected_sequence, envelope_count, status, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 0, 'active', ?)
+    `).run(
+      sessionId, keypair.privateKey, keypair.publicKey, sharedSecret,
+      clientPublicKey, provider, model, machineFingerprint, appVersionHash,
+      grooveVersion, new Date().toISOString()
+    );
+
+    return { serverPublicKey: keypair.publicKey };
+  }
+
+  getSession(sessionId) {
+    return this.db.prepare('SELECT * FROM sessions WHERE session_id = ?').get(sessionId) || null;
+  }
+
+  checkAndIncrementSequence(sessionId, expectedSequence) {
+    const txn = this.db.transaction(() => {
+      const row = this.db.prepare(
+        "SELECT expected_sequence FROM sessions WHERE session_id = ? AND status = 'active'"
+      ).get(sessionId);
+
+      if (!row) {
+        return { valid: false, reason: 'session not found or not active' };
+      }
+
+      if (row.expected_sequence !== expectedSequence) {
+        return { valid: false, reason: `sequence mismatch: expected ${row.expected_sequence}, got ${expectedSequence}` };
+      }
+
+      this.db.prepare(
+        'UPDATE sessions SET expected_sequence = expected_sequence + 1 WHERE session_id = ?'
+      ).run(sessionId);
+
+      return { valid: true };
+    });
+
+    return txn.immediate();
+  }
+
+  incrementSequence(sessionId) {
+    const result = this.db.prepare(`
+      UPDATE sessions SET expected_sequence = expected_sequence + 1
+      WHERE session_id = ? RETURNING expected_sequence
+    `).get(sessionId);
+    return result ? result.expected_sequence : null;
+  }
+
+  checkEnvelopeCount(sessionId, max = 200) {
+    const row = this.db.prepare('SELECT envelope_count FROM sessions WHERE session_id = ?').get(sessionId);
+    if (!row) return false;
+    return row.envelope_count < max;
+  }
+
+  incrementEnvelopeCount(sessionId) {
+    this.db.prepare('UPDATE sessions SET envelope_count = envelope_count + 1 WHERE session_id = ?').run(sessionId);
+  }
+
+  isEnvelopeProcessed(envelopeId) {
+    const row = this.db.prepare('SELECT 1 FROM processed_envelopes WHERE envelope_id = ?').get(envelopeId);
+    return !!row;
+  }
+
+  recordProcessedEnvelope(envelopeId, sessionId) {
+    this.db.prepare(
+      'INSERT OR IGNORE INTO processed_envelopes (envelope_id, session_id, processed_at) VALUES (?, ?, ?)'
+    ).run(envelopeId, sessionId, new Date().toISOString());
+  }
+
+  closeSession(sessionId) {
+    this.db.prepare(`
+      UPDATE sessions SET status = 'closed', closed_at = ? WHERE session_id = ?
+    `).run(new Date().toISOString(), sessionId);
+  }
+
+  getActiveSessions() {
+    return this.db.prepare("SELECT * FROM sessions WHERE status = 'active'").all();
+  }
+
+  rateLimitCheck(machineFingerprint) {
+    const oneHourAgo = new Date(Date.now() - 3600_000).toISOString();
+    const row = this.db.prepare(`
+      SELECT COUNT(*) as cnt FROM sessions
+      WHERE machine_fingerprint = ? AND created_at > ?
+    `).get(machineFingerprint, oneHourAgo);
+    return row.cnt >= 20;
+  }
+
+  close() {
+    this.db.close();
+  }
+}