@amg555/frameforge-mcp 0.0.0-stage → 2.3.1

package/src/pipeline/retry-policy.js

@@ -0,0 +1,134 @@
+/**
+ * Retry / Timeout / Error Policy
+ *
+ * Classifies errors as RETRYABLE, NON_RETRYABLE, or FATAL.
+ * Applies exponential backoff with jitter for RETRYABLE errors.
+ * Dead-letters jobs that exceed max attempts.
+ * Stage timeouts enforced via Promise.race.
+ *
+ * Usage:
+ *   const policy = new RetryPolicy();
+ *   const result = await policy.executeStage('Research', async () => {
+ *     return await doResearch();
+ *   });
+ */
+
+'use strict';
+
+// Stage timeouts in milliseconds
+const STAGE_TIMEOUTS_MS = {
+  Research:         5  * 60 * 1000,
+  // Script with 32k max-token LLM calls can exceed 3 min on slower providers —
+  // raised to 5 min to match Research.
+  Script:           5  * 60 * 1000,
+  Asset_Generation: 10 * 60 * 1000,
+  Video_Rendering:  30 * 60 * 1000,
+  Shorts_Extraction:10 * 60 * 1000,
+  Quality_Check:    2  * 60 * 1000,
+  Packaging:        1  * 60 * 1000,
+  Publishing:       5  * 60 * 1000,
+  // per-request timeouts
+  HTTP_REQUEST:     30 * 1000,
+  TTS:              2  * 60 * 1000,
+  IMAGE_GENERATION: 3  * 60 * 1000,
+  FFMPEG:           30 * 60 * 1000,
+};
+
+// Error classification patterns
+const RETRYABLE_PATTERNS    = [/ECONNREFUSED/, /ETIMEDOUT/, /ECONNRESET/, /socket hang up/, /429/, /503/, /worker unavailable/, /rate limit/i, /timeout/i];
+const NON_RETRYABLE_PATTERNS = [/JSON parse/i, /schema validation/i, /quality gate/i, /parse failed/i, /Too few scenes/i, /Too few claims/i];
+const FATAL_PATTERNS         = [/401/, /403/, /Invalid credential/i, /Missing credential/i];
+
+class RetryPolicy {
+  constructor({ maxAttempts = 3, baseDelayMs = 10000 } = {}) {
+    this.maxAttempts  = maxAttempts;
+    this.baseDelayMs  = baseDelayMs;
+  }
+
+  classifyError(error) {
+    const msg = String(error?.message || error);
+    const code = String(error?.code || '');
+    const combined = msg + ' ' + code;
+    if (FATAL_PATTERNS.some(p => p.test(combined)))         return 'FATAL';
+    if (NON_RETRYABLE_PATTERNS.some(p => p.test(combined))) return 'NON_RETRYABLE';
+    if (RETRYABLE_PATTERNS.some(p => p.test(combined)))     return 'RETRYABLE';
+    const status = error?.status || error?.statusCode;
+    if (status === 401 || status === 403) return 'FATAL';
+    if (status === 429 || status >= 500)  return 'RETRYABLE';
+    if (status >= 400)                    return 'NON_RETRYABLE';
+    return 'NON_RETRYABLE'; // conservative default
+  }
+
+  /**
+   * Execute a stage function with timeout and retry.
+   * @param {string} stageName
+   * @param {() => Promise<any>} fn
+   * @returns {Promise<any>}
+   */
+  async executeStage(stageName, fn) {
+    const timeoutMs = STAGE_TIMEOUTS_MS[stageName] || (30 * 60 * 1000);
+    let lastError;
+
+    for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+      try {
+        return await this._withTimeout(fn(), timeoutMs, stageName);
+      } catch (err) {
+        lastError = err;
+        const errorClass = this.classifyError(err);
+
+        if (errorClass === 'FATAL') {
+          throw Object.assign(err, { errorClass: 'FATAL', stageName, attempt });
+        }
+
+        if (errorClass === 'NON_RETRYABLE') {
+          throw Object.assign(err, { errorClass: 'NON_RETRYABLE', stageName, attempt });
+        }
+
+        // RETRYABLE
+        if (attempt < this.maxAttempts) {
+          const delay = this._backoffDelay(attempt);
+          console.warn(`[RetryPolicy] ${stageName} attempt ${attempt}/${this.maxAttempts} failed (RETRYABLE): ${err.message} — retry in ${delay}ms`);
+          await this._sleep(delay);
+        }
+      }
+    }
+
+    const deadLetterErr = Object.assign(lastError, {
+      errorClass: 'DEAD_LETTER',
+      stageName,
+      attempt: this.maxAttempts,
+    });
+    console.error(`[RetryPolicy] ${stageName} dead-lettered after ${this.maxAttempts} attempts: ${lastError.message}`);
+    throw deadLetterErr;
+  }
+
+  /**
+   * Execute a single operation (not a stage) with timeout only.
+   * No retry — callers handle that via executeStage.
+   */
+  async withTimeout(fn, timeoutMs, label = 'operation') {
+    return this._withTimeout(fn, timeoutMs, label);
+  }
+
+  _withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(Object.assign(new Error(`${label} timed out after ${ms}ms`), { code: 'ETIMEDOUT' }));
+      }, ms);
+      Promise.resolve(promise).then(
+        v  => { clearTimeout(timer); resolve(v); },
+        e  => { clearTimeout(timer); reject(e); }
+      );
+    });
+  }
+
+  _backoffDelay(attempt) {
+    // Exponential with full jitter: random(0, baseDelay * 2^attempt)
+    const cap = this.baseDelayMs * Math.pow(2, attempt);
+    return Math.floor(Math.random() * cap);
+  }
+
+  _sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+}
+
+module.exports = { RetryPolicy, STAGE_TIMEOUTS_MS };

package/src/pipeline/state-machine.js

@@ -0,0 +1,297 @@
+/**
+ * PostgreSQL-backed production state machine.
+ *
+ * Productions: QUEUED → RUNNING → SUCCEEDED / FAILED / WAITING_REVIEW / CANCELLED
+ * Stages:      PENDING → RUNNING → SUCCEEDED / FAILED / SKIPPED / WAITING_REVIEW
+ *
+ * Never infer state from n8n execution history — always read from this table.
+ *
+ * Usage (filesystem mode — no PG required for single-worker):
+ *   const sm = new StateMachine({ mode: 'file', stateDir: '/home/node/.n8n-files/state' });
+ *   await sm.init();
+ *   const id = await sm.createProduction({ topic, pipelineVersion: '1.0.0' });
+ *   await sm.startStage(id, 'Research');
+ *   await sm.completeStage(id, 'Research', { outputHash: '...' });
+ */
+
+'use strict';
+
+const fs   = require('fs').promises;
+const path = require('path');
+const crypto = require('crypto');
+
+const PRODUCTION_STATUSES = ['QUEUED','RUNNING','SUCCEEDED','FAILED','WAITING_REVIEW','CANCELLED'];
+const STAGE_STATUSES      = ['PENDING','RUNNING','SUCCEEDED','FAILED','SKIPPED','WAITING_REVIEW'];
+
+const ALLOWED_TRANSITIONS = {
+  QUEUED:         ['RUNNING','CANCELLED'],
+  RUNNING:        ['SUCCEEDED','FAILED','WAITING_REVIEW','CANCELLED'],
+  WAITING_REVIEW: ['RUNNING','SUCCEEDED','FAILED','CANCELLED'],
+  SUCCEEDED:      [],
+  FAILED:         ['QUEUED'], // allow retry
+  CANCELLED:      [],
+};
+
+class StateMachine {
+  /**
+   * @param {{ mode: 'file'|'pg', stateDir?: string, pg?: object }} config
+   */
+  constructor(config = {}) {
+    this.mode     = config.mode || 'file';
+    const _os = require('os'); const _path = require('path');
+    this.stateDir = config.stateDir || _path.join(process.env.N8N_FILES_DIR || _path.join(_os.homedir(), '.frameforge-files'), 'state');
+    this.pg       = config.pg || null; // pg.Pool instance when mode === 'pg'
+    // Per-productionId write mutex — prevents concurrent file writes from
+    // parallel asset generation (assets.js runs up to 4 scenes at once).
+    // Each entry is a Promise chain; new writes append to the tail.
+    this._writeLocks = new Map();
+  }
+
+  async init() {
+    if (this.mode === 'file') {
+      await fs.mkdir(this.stateDir, { recursive: true });
+    } else {
+      await this._pgInit();
+    }
+  }
+
+  // ── Production lifecycle ──────────────────────────────────────────────────
+
+  async createProduction({ topic, pipelineVersion = '1.0.0', schemaVersion = '1.0.0', metadata = {} }) {
+    const productionId = `vid_${Date.now()}_${crypto.randomBytes(3).toString('hex')}`;
+    const record = {
+      productionId,
+      status: 'QUEUED',
+      pipelineVersion,
+      schemaVersion,
+      topic,
+      createdAt: new Date().toISOString(),
+      startedAt:   null,
+      completedAt: null,
+      configHash: this._hash(JSON.stringify({ topic, pipelineVersion })),
+      stages: {},
+      metadata,
+    };
+    await this._saveProduction(productionId, record);
+    return productionId;
+  }
+
+  async transitionProduction(productionId, newStatus) {
+    const record = await this._loadProduction(productionId);
+    if (!PRODUCTION_STATUSES.includes(newStatus)) throw new Error(`Invalid status: ${newStatus}`);
+    const allowed = ALLOWED_TRANSITIONS[record.status] || [];
+    if (!allowed.includes(newStatus)) {
+      throw new Error(`Illegal transition ${record.status} → ${newStatus} for ${productionId}`);
+    }
+    record.status = newStatus;
+    if (newStatus === 'RUNNING')   record.startedAt   = new Date().toISOString();
+    if (['SUCCEEDED','FAILED','CANCELLED'].includes(newStatus)) record.completedAt = new Date().toISOString();
+    await this._saveProduction(productionId, record);
+  }
+
+  async getProduction(productionId) {
+    return this._loadProduction(productionId);
+  }
+
+  async listProductions(statusFilter = null) {
+    if (this.mode === 'file') {
+      const files = await fs.readdir(this.stateDir).catch(() => []);
+      const prods = await Promise.all(
+        files.filter(f => f.endsWith('.json')).map(f => this._loadProduction(f.replace('.json', '')))
+      );
+      return statusFilter ? prods.filter(p => p.status === statusFilter) : prods;
+    }
+    return this._pgListProductions(statusFilter);
+  }
+
+  // ── Stage lifecycle ───────────────────────────────────────────────────────
+
+  async startStage(productionId, stageName) {
+    let record;
+    try {
+      record = await this._loadProduction(productionId);
+    } catch (err) {
+      // Production not yet registered (agent-first path skips createProduction).
+      // Auto-create a minimal QUEUED record so the stage can proceed.
+      const now = new Date().toISOString();
+      record = {
+        productionId,
+        status: 'QUEUED',
+        pipelineVersion: '1.0.0',
+        schemaVersion: '1.0.0',
+        topic: productionId,
+        createdAt: now,
+        startedAt: null,
+        completedAt: null,
+        configHash: this._hash(productionId),
+        stages: {},
+        metadata: {},
+      };
+      await this._saveProduction(productionId, record);
+    }
+    record.stages[stageName] = {
+      status:    'RUNNING',
+      startedAt: new Date().toISOString(),
+      completedAt: null,
+      inputHash: null,
+      outputHash: null,
+      retryCount: 0,
+      errorMessage: null,
+    };
+    if (record.status === 'QUEUED') {
+      record.status    = 'RUNNING';
+      record.startedAt = new Date().toISOString();
+    }
+    await this._saveProduction(productionId, record);
+  }
+
+  async completeStage(productionId, stageName, { outputHash = null, metrics = {} } = {}) {
+    const record = await this._loadProduction(productionId);
+    const stage  = record.stages[stageName] || {};
+    stage.status      = 'SUCCEEDED';
+    stage.completedAt = new Date().toISOString();
+    stage.outputHash  = outputHash;
+    stage.metrics     = metrics;
+    record.stages[stageName] = stage;
+    await this._saveProduction(productionId, record);
+  }
+
+  async failStage(productionId, stageName, errorMessage, { retryable = false } = {}) {
+    const record = await this._loadProduction(productionId);
+    const stage  = record.stages[stageName] || {};
+    stage.status       = 'FAILED';
+    stage.completedAt  = new Date().toISOString();
+    stage.errorMessage = errorMessage;
+    stage.retryCount   = (stage.retryCount || 0) + 1;
+    stage.retryable    = retryable;
+    record.stages[stageName] = stage;
+    await this._saveProduction(productionId, record);
+  }
+
+  async skipStage(productionId, stageName, reason = '') {
+    const record = await this._loadProduction(productionId);
+    record.stages[stageName] = { status: 'SKIPPED', reason, skippedAt: new Date().toISOString() };
+    await this._saveProduction(productionId, record);
+  }
+
+  async getStage(productionId, stageName) {
+    const record = await this._loadProduction(productionId);
+    return record.stages[stageName] || { status: 'PENDING' };
+  }
+
+  // ── Idempotency check ─────────────────────────────────────────────────────
+
+  /**
+   * Returns true if the stage can be skipped because its output is still valid.
+   * Components: inputHash of current inputs + outputHash of cached output + quality flag.
+   */
+  async canReuseStage(productionId, stageName, currentInputHash) {
+    const stage = await this.getStage(productionId, stageName);
+    return (
+      stage.status === 'SUCCEEDED' &&
+      stage.inputHash === currentInputHash &&
+      stage.outputHash &&
+      stage.qualityPassed !== false
+    );
+  }
+
+  async recordInputHash(productionId, stageName, inputHash) {
+    const record = await this._loadProduction(productionId);
+    record.stages[stageName] = record.stages[stageName] || {};
+    record.stages[stageName].inputHash = inputHash;
+    await this._saveProduction(productionId, record);
+  }
+
+  // ── Internal helpers ──────────────────────────────────────────────────────
+
+  _hash(data) {
+    return crypto.createHash('sha256').update(data).digest('hex').slice(0, 16);
+  }
+
+  async _saveProduction(productionId, record) {
+    if (this.mode === 'file') {
+      // Serialize writes for the same productionId to prevent data loss from
+      // concurrent stage updates (e.g. parallel TTS/image generation).
+      const prev = this._writeLocks.get(productionId) || Promise.resolve();
+      const next = prev.then(async () => {
+        const filePath = path.join(this.stateDir, `${productionId}.json`);
+        await fs.writeFile(filePath, JSON.stringify(record, null, 2), 'utf8');
+      });
+      // Store the tail; remove once resolved so the Map doesn't grow unbounded
+      this._writeLocks.set(productionId, next.catch(() => {}).then(() => {
+        if (this._writeLocks.get(productionId) === next) {
+          this._writeLocks.delete(productionId);
+        }
+      }));
+      await next;
+    } else {
+      await this._pgUpsertProduction(record);
+    }
+  }
+
+  async _loadProduction(productionId) {
+    if (this.mode === 'file') {
+      const filePath = path.join(this.stateDir, `${productionId}.json`);
+      try {
+        return JSON.parse(await fs.readFile(filePath, 'utf8'));
+      } catch (err) {
+        throw new Error(`Production not found: ${productionId}`);
+      }
+    }
+    return this._pgLoadProduction(productionId);
+  }
+
+  // ── PostgreSQL stubs (wire up a pg.Pool to activate) ─────────────────────
+
+  async _pgInit() {
+    if (!this.pg) throw new Error('pg.Pool required for mode=pg');
+    await this.pg.query(`
+      CREATE TABLE IF NOT EXISTS productions (
+        production_id VARCHAR(64) PRIMARY KEY,
+        status VARCHAR(20) NOT NULL DEFAULT 'QUEUED',
+        pipeline_version VARCHAR(20),
+        schema_version VARCHAR(20),
+        topic TEXT,
+        created_at TIMESTAMP DEFAULT NOW(),
+        started_at TIMESTAMP,
+        completed_at TIMESTAMP,
+        config_hash VARCHAR(32),
+        stages JSONB DEFAULT '{}',
+        metadata JSONB DEFAULT '{}'
+      );
+    `);
+  }
+
+  async _pgUpsertProduction(record) {
+    await this.pg.query(`
+      INSERT INTO productions (production_id, status, pipeline_version, schema_version, topic,
+        created_at, started_at, completed_at, config_hash, stages, metadata)
+      VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10::jsonb,$11::jsonb)
+      ON CONFLICT (production_id) DO UPDATE SET
+        status=EXCLUDED.status, started_at=EXCLUDED.started_at,
+        completed_at=EXCLUDED.completed_at, stages=EXCLUDED.stages
+    `, [record.productionId, record.status, record.pipelineVersion, record.schemaVersion,
+        record.topic, record.createdAt, record.startedAt, record.completedAt,
+        record.configHash, JSON.stringify(record.stages), JSON.stringify(record.metadata)]);
+  }
+
+  async _pgLoadProduction(productionId) {
+    const { rows } = await this.pg.query('SELECT * FROM productions WHERE production_id=$1', [productionId]);
+    if (!rows.length) throw new Error(`Production not found: ${productionId}`);
+    const r = rows[0];
+    return { productionId: r.production_id, status: r.status, pipelineVersion: r.pipeline_version,
+             schemaVersion: r.schema_version, topic: r.topic, createdAt: r.created_at,
+             startedAt: r.started_at, completedAt: r.completed_at, configHash: r.config_hash,
+             stages: r.stages || {}, metadata: r.metadata || {} };
+  }
+
+  async _pgListProductions(statusFilter) {
+    const q = statusFilter
+      ? 'SELECT * FROM productions WHERE status=$1 ORDER BY created_at DESC'
+      : 'SELECT * FROM productions ORDER BY created_at DESC';
+    const { rows } = await this.pg.query(q, statusFilter ? [statusFilter] : []);
+    return Promise.all(rows.map(r => this._pgLoadProduction(r.production_id)));
+  }
+}
+
+module.exports = { StateMachine };

package/src/pipeline/telemetry.js

@@ -0,0 +1,162 @@
+/**
+ * Observability + Cost Tracking
+ *
+ * Writes usage_events to PostgreSQL (when configured) or a local NDJSON log.
+ * Every LLM call, image gen, TTS render, and video encode logs a usage event.
+ *
+ * Usage:
+ *   const telemetry = new Telemetry({ mode: 'file', logPath: '/home/node/.n8n-files/usage.ndjson' });
+ *   await telemetry.track({ productionId, stage: 'Script', provider: 'groq', operation: 'script_generation', units: 14500 });
+ *   const report = await telemetry.costReport(productionId);
+ */
+
+'use strict';
+
+const fs   = require('fs').promises;
+const path = require('path');
+
+// Approximate pricing (USD per unit)
+const COST_TABLE = {
+  groq:        { tokens:     0.00000059 },  // $0.59/1M tokens (llama-3.3-70b-versatile)
+  cerebras:    { tokens:     0.00000060 },  // $0.60/1M tokens (llama3.3-70b)
+  openrouter:  { tokens:     0.00000300 },  // varies by model — rough estimate
+  anthropic:   { tokens:     0.00000300 },  // $3/1M tokens (claude-sonnet-4-5)
+  gemini:      { tokens:     0.00000010 },  // $0.10/1M tokens (gemini-2.0-flash)
+  mistral:     { tokens:     0.00000200 },  // $2/1M tokens (mistral-large-latest)
+  together:    { tokens:     0.00000090 },  // $0.90/1M tokens (Llama-3.3-70B-Turbo)
+  openai:      { tokens:     0.00000250 },  // $2.50/1M input tokens (gpt-4o)
+  ollama:      { tokens:     0           },  // local
+  pollinations:{ images:     0           },  // free tier
+  falai:       { images:     0.003       },  // ~$0.003/image
+  replicate:   { images:     0.003       },
+  dalle:       { images:     0.04        },  // DALL-E 3 1024x1024
+  elevenlabs:  { characters: 0.00003     },  // $30/1M chars
+  azure:       { characters: 0.000016    },
+  'edge-tts':  { characters: 0           },  // free
+  openai_tts:  { characters: 0.000015    },
+  ffmpeg:      { seconds:    0           },  // local
+};
+
+function estimateCost(provider, operation, units) {
+  const prov = COST_TABLE[provider] || {};
+  if (operation.includes('token') || operation.includes('script') || operation.includes('research')) return units * (prov.tokens || 0);
+  if (operation.includes('image') || operation.includes('doodle') || operation.includes('thumbnail')) return units * (prov.images || 0);
+  if (operation.includes('tts') || operation.includes('voice')) return units * (prov.characters || 0);
+  if (operation.includes('render') || operation.includes('video') || operation.includes('audio')) return units * (prov.seconds || 0);
+  return 0;
+}
+
+class Telemetry {
+  constructor({ mode = 'file', logPath = require('path').join(process.env.N8N_FILES_DIR || require('path').join(require('os').homedir(), '.frameforge-files'), 'usage.ndjson'), pg = null } = {}) {
+    this.mode    = mode;
+    this.logPath = logPath;
+    this.pg      = pg;
+  }
+
+  async init() {
+    if (this.mode === 'file') {
+      await fs.mkdir(path.dirname(this.logPath), { recursive: true });
+    } else {
+      await this._pgInit();
+    }
+  }
+
+  /**
+   * Track a usage event.
+   * @param {{ productionId: string, stage: string, provider: string, operation: string, units: number, metadata?: object }} event
+   */
+  async track({ productionId, stage, provider, operation, units = 0, metadata = {} }) {
+    const event = {
+      id:            `${Date.now()}_${Math.random().toString(36).slice(2, 7)}`,
+      productionId,
+      stage,
+      provider,
+      operation,
+      units,
+      estimatedCostUsd: estimateCost(provider, operation, units),
+      timestamp:     new Date().toISOString(),
+      schemaVersion: '1.0.0',
+      metadata,
+    };
+
+    if (this.mode === 'file') {
+      await fs.appendFile(this.logPath, JSON.stringify(event) + '\n');
+    } else {
+      await this._pgInsert(event);
+    }
+
+    return event;
+  }
+
+  /**
+   * Aggregate cost report for a production.
+   * @returns {{ totalCostUsd: number, byProvider: object, byStage: object, events: number }}
+   */
+  async costReport(productionId) {
+    const events = await this._loadEvents(productionId);
+    const byProvider = {};
+    const byStage    = {};
+    let totalCostUsd = 0;
+
+    for (const e of events) {
+      byProvider[e.provider] = (byProvider[e.provider] || 0) + e.estimatedCostUsd;
+      byStage[e.stage]       = (byStage[e.stage]       || 0) + e.estimatedCostUsd;
+      totalCostUsd           += e.estimatedCostUsd;
+    }
+
+    return {
+      productionId,
+      totalCostUsd:  Math.round(totalCostUsd * 1e6) / 1e6,
+      byProvider:    Object.fromEntries(Object.entries(byProvider).map(([k,v]) => [k, Math.round(v * 1e6) / 1e6])),
+      byStage:       Object.fromEntries(Object.entries(byStage).map(([k,v]) => [k, Math.round(v * 1e6) / 1e6])),
+      events:        events.length,
+    };
+  }
+
+  async _loadEvents(productionId) {
+    if (this.mode === 'file') {
+      try {
+        const raw  = await fs.readFile(this.logPath, 'utf8');
+        return raw.trim().split('\n').filter(Boolean).map(l => JSON.parse(l)).filter(e => e.productionId === productionId);
+      } catch { return []; }
+    }
+    return this._pgLoadEvents(productionId);
+  }
+
+  async _pgInit() {
+    if (!this.pg) throw new Error('pg.Pool required for mode=pg');
+    await this.pg.query(`
+      CREATE TABLE IF NOT EXISTS usage_events (
+        id VARCHAR(32) PRIMARY KEY,
+        production_id VARCHAR(64) NOT NULL,
+        stage VARCHAR(50),
+        provider VARCHAR(50),
+        operation VARCHAR(100),
+        units DECIMAL,
+        estimated_cost_usd DECIMAL(10,6),
+        timestamp TIMESTAMP DEFAULT NOW(),
+        schema_version VARCHAR(20) DEFAULT '1.0.0',
+        metadata JSONB DEFAULT '{}'
+      );
+      CREATE INDEX IF NOT EXISTS idx_usage_production ON usage_events(production_id);
+      CREATE INDEX IF NOT EXISTS idx_usage_provider ON usage_events(provider);
+      CREATE INDEX IF NOT EXISTS idx_usage_timestamp ON usage_events(timestamp);
+    `);
+  }
+
+  async _pgInsert(event) {
+    await this.pg.query(`
+      INSERT INTO usage_events (id, production_id, stage, provider, operation, units, estimated_cost_usd, timestamp, schema_version, metadata)
+      VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10::jsonb)
+    `, [event.id, event.productionId, event.stage, event.provider, event.operation,
+        event.units, event.estimatedCostUsd, event.timestamp, event.schemaVersion,
+        JSON.stringify(event.metadata)]);
+  }
+
+  async _pgLoadEvents(productionId) {
+    const { rows } = await this.pg.query('SELECT * FROM usage_events WHERE production_id=$1 ORDER BY timestamp', [productionId]);
+    return rows.map(r => ({ ...r, productionId: r.production_id, estimatedCostUsd: parseFloat(r.estimated_cost_usd) }));
+  }
+}
+
+module.exports = { Telemetry, estimateCost };