@agenticmail/enterprise 0.3.2 → 0.4.0

package/src/engine/community-routes.ts

@@ -0,0 +1,233 @@
+/**
+ * Community Skill Registry Routes
+ * Mounted at /community/* on the engine sub-app.
+ *
+ * Endpoints:
+ *   Browse:   GET  /skills, /skills/search, /skills/featured, /skills/popular,
+ *                   /skills/categories, /skills/stats, /skills/:id, /skills/:id/reviews
+ *   Install:  GET  /installed, POST /skills/:id/install, DELETE /skills/:id/uninstall,
+ *             PUT  /skills/:id/enable, PUT /skills/:id/disable, PUT /skills/:id/config,
+ *             POST /skills/:id/upgrade
+ *   Admin:    POST /skills/publish, DELETE /skills/:id/unpublish,
+ *             POST /skills/import-github, POST /skills/validate,
+ *             POST /skills/:id/verify, POST /skills/:id/feature,
+ *             POST /skills/:id/reviews
+ */
+
+import { Hono } from 'hono';
+import type { CommunitySkillRegistry } from './community-registry.js';
+
+export function createCommunityRoutes(registry: CommunitySkillRegistry) {
+  const router = new Hono();
+
+  // ─── Browse ──────────────────────────────────────────
+
+  router.get('/skills', async (c) => {
+    const result = await registry.search({
+      query: c.req.query('q') || undefined,
+      category: c.req.query('category') || undefined,
+      risk: c.req.query('risk') || undefined,
+      tag: c.req.query('tag') || undefined,
+      verified: c.req.query('verified') === 'true' ? true : c.req.query('verified') === 'false' ? false : undefined,
+      featured: c.req.query('featured') === 'true' ? true : c.req.query('featured') === 'false' ? false : undefined,
+      sortBy: c.req.query('sort') || undefined,
+      order: c.req.query('order') || undefined,
+      limit: parseInt(c.req.query('limit') || '50'),
+      offset: parseInt(c.req.query('offset') || '0'),
+    });
+    return c.json(result);
+  });
+
+  router.get('/skills/search', async (c) => {
+    const q = c.req.query('q') || '';
+    const result = await registry.search({
+      query: q,
+      limit: parseInt(c.req.query('limit') || '20'),
+    });
+    return c.json(result);
+  });
+
+  router.get('/skills/featured', async (c) => {
+    const skills = await registry.getFeatured();
+    return c.json({ skills });
+  });
+
+  router.get('/skills/popular', async (c) => {
+    const limit = parseInt(c.req.query('limit') || '10');
+    const skills = await registry.getPopular(limit);
+    return c.json({ skills });
+  });
+
+  router.get('/skills/categories', (c) => {
+    return c.json({ categories: registry.getCategories() });
+  });
+
+  router.get('/skills/stats', (c) => {
+    return c.json(registry.getStats());
+  });
+
+  router.get('/skills/:id', (c) => {
+    const skill = registry.getSkill(c.req.param('id'));
+    if (!skill) return c.json({ error: 'Skill not found' }, 404);
+    return c.json({ skill });
+  });
+
+  router.get('/skills/:id/reviews', async (c) => {
+    const limit = parseInt(c.req.query('limit') || '50');
+    const reviews = await registry.getReviews(c.req.param('id'), limit);
+    return c.json({ reviews });
+  });
+
+  // ─── Install / Manage ────────────────────────────────
+
+  router.get('/installed', async (c) => {
+    const orgId = c.req.query('orgId') || 'default';
+    const installed = await registry.getInstalledWithDetails(orgId);
+    return c.json({ installed });
+  });
+
+  router.post('/skills/:id/install', async (c) => {
+    const { orgId, config } = await c.req.json().catch(() => ({ orgId: 'default', config: {} }));
+    const userId = c.req.header('X-User-Id') || 'admin';
+    const installed = await registry.install(orgId || 'default', c.req.param('id'), userId, config);
+    return c.json({ installed }, 201);
+  });
+
+  router.delete('/skills/:id/uninstall', async (c) => {
+    const orgId = c.req.query('orgId') || 'default';
+    await registry.uninstall(orgId, c.req.param('id'));
+    return c.json({ ok: true });
+  });
+
+  router.put('/skills/:id/enable', async (c) => {
+    const { orgId } = await c.req.json().catch(() => ({ orgId: 'default' }));
+    await registry.enable(orgId || 'default', c.req.param('id'));
+    return c.json({ ok: true });
+  });
+
+  router.put('/skills/:id/disable', async (c) => {
+    const { orgId } = await c.req.json().catch(() => ({ orgId: 'default' }));
+    await registry.disable(orgId || 'default', c.req.param('id'));
+    return c.json({ ok: true });
+  });
+
+  router.put('/skills/:id/config', async (c) => {
+    const { orgId, config } = await c.req.json();
+    if (!config) return c.json({ error: 'config required' }, 400);
+    await registry.updateConfig(orgId || 'default', c.req.param('id'), config);
+    return c.json({ ok: true });
+  });
+
+  router.post('/skills/:id/upgrade', async (c) => {
+    const { orgId } = await c.req.json().catch(() => ({ orgId: 'default' }));
+    const installed = await registry.upgrade(orgId || 'default', c.req.param('id'));
+    return c.json({ installed });
+  });
+
+  // ─── Admin / Publishing ──────────────────────────────
+
+  router.post('/skills/publish', async (c) => {
+    const manifest = await c.req.json();
+    const skill = await registry.publish(manifest);
+    return c.json({ skill }, 201);
+  });
+
+  router.delete('/skills/:id/unpublish', async (c) => {
+    await registry.unpublish(c.req.param('id'));
+    return c.json({ ok: true });
+  });
+
+  router.post('/skills/import-github', async (c) => {
+    const { repoUrl } = await c.req.json();
+    if (!repoUrl) return c.json({ error: 'repoUrl required' }, 400);
+    const skill = await registry.importFromGitHub(repoUrl);
+    return c.json({ skill }, 201);
+  });
+
+  router.post('/skills/validate', async (c) => {
+    const manifest = await c.req.json();
+    const result = registry.validateManifest(manifest);
+    return c.json(result);
+  });
+
+  router.post('/skills/:id/verify', async (c) => {
+    const { verified } = await c.req.json().catch(() => ({ verified: true }));
+    await registry.setVerified(c.req.param('id'), verified !== false);
+    return c.json({ ok: true });
+  });
+
+  router.post('/skills/:id/feature', async (c) => {
+    const { featured } = await c.req.json().catch(() => ({ featured: true }));
+    await registry.setFeatured(c.req.param('id'), featured !== false);
+    return c.json({ ok: true });
+  });
+
+  router.post('/skills/:id/reviews', async (c) => {
+    const body = await c.req.json();
+    const userId = c.req.header('X-User-Id') || body.userId || 'anonymous';
+    const review = await registry.submitReview({
+      skillId: c.req.param('id'),
+      userId,
+      userName: body.userName || body.displayName || undefined,
+      rating: body.rating,
+      reviewText: body.reviewText || body.text || undefined,
+    });
+    return c.json({ review }, 201);
+  });
+
+  // ─── Sync / Auto-Publish ─────────────────────────
+
+  // Reload all skills from the community-skills/ directory.
+  // Called by the post-merge CI workflow or manually to pick up new skills
+  // without restarting the server.
+  router.post('/sync', async (c) => {
+    const path = await import('path');
+    const communityDir = c.req.query('dir')
+      || path.resolve(import.meta.dirname || '.', '../../community-skills');
+    const result = await registry.loadFromDirectory(communityDir);
+    return c.json({
+      ok: true,
+      loaded: result.loaded,
+      errors: result.errors,
+      message: `Synced ${result.loaded} skills from directory`,
+    });
+  });
+
+  // Publish a single skill by reading its manifest from the directory.
+  // Used by CI after a specific skill is merged.
+  router.post('/sync/:skillId', async (c) => {
+    const skillId = c.req.param('skillId');
+    const path = await import('path');
+    const fs = await import('fs/promises');
+    const communityDir = c.req.query('dir')
+      || path.resolve(import.meta.dirname || '.', '../../community-skills');
+    const manifestPath = path.join(communityDir, skillId, 'agenticmail-skill.json');
+
+    try {
+      const raw = await fs.readFile(manifestPath, 'utf-8');
+      const manifest = JSON.parse(raw);
+      const skill = await registry.publish(manifest);
+      return c.json({ ok: true, skill }, 201);
+    } catch (err: any) {
+      return c.json({ error: `Failed to sync ${skillId}: ${err.message}` }, 400);
+    }
+  });
+
+  // Trigger a remote sync from the central GitHub repo (agenticmail/enterprise).
+  // This fetches community-skills/index.json from the repo and pulls any
+  // new/updated skills. Called by the dashboard "Sync Now" button or by cron.
+  router.post('/sync-remote', async (c) => {
+    const result = await registry.syncFromRemote();
+    return c.json({
+      ok: true,
+      synced: result.synced,
+      errors: result.errors,
+      lastSyncAt: registry.getLastSyncAt(),
+      message: result.synced > 0
+        ? `Synced ${result.synced} new skills from remote registry`
+        : 'Already up to date',
+    });
+  });
+
+  return router;
+}

package/src/engine/compliance-routes.ts

@@ -0,0 +1,93 @@
+/**
+ * Compliance Reporting Routes
+ * Mounted at /compliance/* on the engine sub-app.
+ */
+
+import { Hono } from 'hono';
+import type { ComplianceReporter } from './compliance.js';
+
+export function createComplianceRoutes(compliance: ComplianceReporter) {
+  const router = new Hono();
+
+  router.post('/reports/soc2', async (c) => {
+    try {
+      const { orgId, dateRange } = await c.req.json();
+      if (!orgId || !dateRange?.from || !dateRange?.to) return c.json({ error: 'orgId and dateRange.from/to required' }, 400);
+      const generatedBy = c.req.header('X-User-Id') || 'admin';
+      const report = await compliance.generateSOC2(orgId, dateRange, generatedBy);
+      return c.json({ report }, 201);
+    } catch (err: any) {
+      return c.json({ error: err.message }, 500);
+    }
+  });
+
+  router.post('/reports/gdpr', async (c) => {
+    try {
+      const { orgId, agentId } = await c.req.json();
+      if (!orgId || !agentId) return c.json({ error: 'orgId and agentId required' }, 400);
+      const generatedBy = c.req.header('X-User-Id') || 'admin';
+      const report = await compliance.generateGDPR(orgId, agentId, generatedBy);
+      return c.json({ report }, 201);
+    } catch (err: any) {
+      return c.json({ error: err.message }, 500);
+    }
+  });
+
+  router.post('/reports/audit', async (c) => {
+    try {
+      const { orgId, dateRange, agentIds } = await c.req.json();
+      if (!orgId || !dateRange?.from || !dateRange?.to) return c.json({ error: 'orgId and dateRange.from/to required' }, 400);
+      const generatedBy = c.req.header('X-User-Id') || 'admin';
+      const report = await compliance.generateAudit(orgId, dateRange, generatedBy, agentIds);
+      return c.json({ report }, 201);
+    } catch (err: any) {
+      return c.json({ error: err.message }, 500);
+    }
+  });
+
+  router.get('/reports', (c) => {
+    try {
+      const reports = compliance.getReports({
+        orgId: c.req.query('orgId') || undefined,
+        type: c.req.query('type') || undefined,
+        limit: parseInt(c.req.query('limit') || '50'),
+      });
+      return c.json({ reports, total: reports.length });
+    } catch (err: any) {
+      return c.json({ error: err.message }, 500);
+    }
+  });
+
+  router.get('/reports/:id', (c) => {
+    try {
+      const report = compliance.getReport(c.req.param('id'));
+      if (!report) return c.json({ error: 'Report not found' }, 404);
+      return c.json({ report });
+    } catch (err: any) {
+      return c.json({ error: err.message }, 500);
+    }
+  });
+
+  router.get('/reports/:id/download', (c) => {
+    try {
+      const report = compliance.getReport(c.req.param('id'));
+      if (!report) return c.json({ error: 'Report not found' }, 404);
+
+      const format = c.req.query('format') || report.format;
+      if (format === 'csv') {
+        const csv = compliance.toCSV(report);
+        c.header('Content-Type', 'text/csv');
+        c.header('Content-Disposition', `attachment; filename="${report.type}-${report.id}.csv"`);
+        return c.body(csv);
+      }
+
+      c.header('Content-Type', 'application/json');
+      c.header('Content-Disposition', `attachment; filename="${report.type}-${report.id}.json"`);
+      return c.body(JSON.stringify(report.data, null, 2));
+    } catch (err: any) {
+      return c.json({ error: err.message }, 500);
+    }
+  });
+
+  return router;
+}

package/src/engine/compliance.ts

@@ -0,0 +1,325 @@
+/**
+ * Compliance Reporting Engine
+ *
+ * Generates compliance reports by aggregating data from all engine modules:
+ * - SOC2 Summary: risk analysis, approval rates, DLP incidents, interventions
+ * - GDPR Export: all data associated with an agent (right to access)
+ * - Audit Summary: timeline of events across all tables
+ *
+ * Reports are stored in DB for later retrieval/download.
+ */
+
+import type { EngineDatabase } from './db-adapter.js';
+
+// ─── Types ──────────────────────────────────────────────
+
+export interface ComplianceReport {
+  id: string;
+  orgId: string;
+  type: 'soc2' | 'gdpr' | 'audit';
+  title: string;
+  parameters: Record<string, any>;
+  status: 'generating' | 'completed' | 'failed';
+  data?: Record<string, any>;
+  format: 'json' | 'csv';
+  generatedBy: string;
+  error?: string;
+  createdAt: string;
+  completedAt?: string;
+}
+
+// ─── Compliance Reporter ────────────────────────────────
+
+export class ComplianceReporter {
+  private reports: ComplianceReport[] = [];
+  private engineDb?: EngineDatabase;
+
+  async setDb(db: EngineDatabase): Promise<void> {
+    this.engineDb = db;
+    await this.loadFromDb();
+  }
+
+  private async loadFromDb(): Promise<void> {
+    if (!this.engineDb) return;
+    try {
+      const rows = await this.engineDb.query<any>(
+        'SELECT * FROM compliance_reports ORDER BY created_at DESC LIMIT 100'
+      );
+      this.reports = rows.map((r: any) => ({
+        id: r.id, orgId: r.org_id, type: r.type, title: r.title,
+        parameters: r.parameters ? JSON.parse(r.parameters) : {},
+        status: r.status, data: r.data ? JSON.parse(r.data) : undefined,
+        format: r.format || 'json', generatedBy: r.generated_by,
+        error: r.error, createdAt: r.created_at, completedAt: r.completed_at,
+      }));
+    } catch { /* table may not exist yet */ }
+  }
+
+  // ─── Report Generation ────────────────────────────
+
+  async generateSOC2(orgId: string, dateRange: { from: string; to: string }, generatedBy: string): Promise<ComplianceReport> {
+    const report = this.createReport(orgId, 'soc2', `SOC2 Summary ${dateRange.from} to ${dateRange.to}`, { dateRange }, generatedBy);
+
+    try {
+      const data: Record<string, any> = {};
+
+      if (this.engineDb) {
+        // Tool call volume & risk breakdown
+        const toolCalls = await this.engineDb.query<any>(
+          'SELECT COUNT(*) as cnt FROM tool_calls WHERE org_id = ? AND created_at BETWEEN ? AND ?',
+          [orgId, dateRange.from, dateRange.to]
+        ).catch(() => [{ cnt: 0 }]);
+        data.toolCalls = { total: toolCalls[0]?.cnt || 0 };
+
+        // Approval stats
+        const approvals = await this.engineDb.query<any>(
+          'SELECT status, COUNT(*) as cnt FROM approval_requests WHERE org_id = ? AND created_at BETWEEN ? AND ? GROUP BY status',
+          [orgId, dateRange.from, dateRange.to]
+        ).catch(() => []);
+        data.approvals = {};
+        for (const r of approvals) { data.approvals[r.status] = r.cnt; }
+
+        // DLP violations
+        const dlpViolations = await this.engineDb.query<any>(
+          'SELECT action_taken, COUNT(*) as cnt FROM dlp_violations WHERE org_id = ? AND created_at BETWEEN ? AND ? GROUP BY action_taken',
+          [orgId, dateRange.from, dateRange.to]
+        ).catch(() => []);
+        data.dlpViolations = {};
+        for (const r of dlpViolations) { data.dlpViolations[r.action_taken] = r.cnt; }
+
+        // Interventions
+        const interventions = await this.engineDb.query<any>(
+          'SELECT type, COUNT(*) as cnt FROM interventions WHERE org_id = ? AND created_at BETWEEN ? AND ? GROUP BY type',
+          [orgId, dateRange.from, dateRange.to]
+        ).catch(() => []);
+        data.interventions = {};
+        for (const r of interventions) { data.interventions[r.type] = r.cnt; }
+
+        // Budget compliance
+        const budgetAlerts = await this.engineDb.query<any>(
+          'SELECT alert_type, COUNT(*) as cnt FROM budget_alerts WHERE org_id = ? AND created_at BETWEEN ? AND ? GROUP BY alert_type',
+          [orgId, dateRange.from, dateRange.to]
+        ).catch(() => []);
+        data.budgetAlerts = {};
+        for (const r of budgetAlerts) { data.budgetAlerts[r.alert_type] = r.cnt; }
+
+        // Journal actions
+        const journalActions = await this.engineDb.query<any>(
+          'SELECT action_type, COUNT(*) as cnt, SUM(reversed) as reversed_cnt FROM action_journal WHERE org_id = ? AND created_at BETWEEN ? AND ? GROUP BY action_type',
+          [orgId, dateRange.from, dateRange.to]
+        ).catch(() => []);
+        data.journalActions = {};
+        for (const r of journalActions) { data.journalActions[r.action_type] = { total: r.cnt, reversed: r.reversed_cnt || 0 }; }
+      }
+
+      report.data = data;
+      report.status = 'completed';
+      report.completedAt = new Date().toISOString();
+    } catch (err: any) {
+      report.status = 'failed';
+      report.error = err.message;
+    }
+
+    this.persistReport(report);
+    return report;
+  }
+
+  async generateGDPR(orgId: string, agentId: string, generatedBy: string): Promise<ComplianceReport> {
+    const report = this.createReport(orgId, 'gdpr', `GDPR Export — Agent ${agentId}`, { agentId }, generatedBy);
+
+    try {
+      const data: Record<string, any> = { agentId };
+
+      if (this.engineDb) {
+        // All tool calls
+        data.toolCalls = await this.engineDb.query<any>(
+          'SELECT * FROM tool_calls WHERE org_id = ? AND agent_id = ? ORDER BY created_at DESC',
+          [orgId, agentId]
+        ).catch(() => []);
+
+        // Activity events
+        data.activityEvents = await this.engineDb.query<any>(
+          'SELECT * FROM activity_events WHERE org_id = ? AND agent_id = ? ORDER BY created_at DESC',
+          [orgId, agentId]
+        ).catch(() => []);
+
+        // Conversations
+        data.conversations = await this.engineDb.query<any>(
+          'SELECT * FROM conversations WHERE org_id = ? AND agent_id = ? ORDER BY created_at DESC',
+          [orgId, agentId]
+        ).catch(() => []);
+
+        // Messages
+        data.messages = await this.engineDb.query<any>(
+          'SELECT * FROM agent_messages WHERE org_id = ? AND (from_agent_id = ? OR to_agent_id = ?) ORDER BY created_at DESC',
+          [orgId, agentId, agentId]
+        ).catch(() => []);
+
+        // Journal entries
+        data.journalEntries = await this.engineDb.query<any>(
+          'SELECT * FROM action_journal WHERE org_id = ? AND agent_id = ? ORDER BY created_at DESC',
+          [orgId, agentId]
+        ).catch(() => []);
+
+        // Interventions
+        data.interventions = await this.engineDb.query<any>(
+          'SELECT * FROM interventions WHERE org_id = ? AND agent_id = ? ORDER BY created_at DESC',
+          [orgId, agentId]
+        ).catch(() => []);
+
+        // Approval requests
+        data.approvalRequests = await this.engineDb.query<any>(
+          'SELECT * FROM approval_requests WHERE org_id = ? AND agent_id = ? ORDER BY created_at DESC',
+          [orgId, agentId]
+        ).catch(() => []);
+      }
+
+      report.data = data;
+      report.status = 'completed';
+      report.completedAt = new Date().toISOString();
+    } catch (err: any) {
+      report.status = 'failed';
+      report.error = err.message;
+    }
+
+    this.persistReport(report);
+    return report;
+  }
+
+  async generateAudit(orgId: string, dateRange: { from: string; to: string }, generatedBy: string, agentIds?: string[]): Promise<ComplianceReport> {
+    const report = this.createReport(orgId, 'audit', `Audit Summary ${dateRange.from} to ${dateRange.to}`, { dateRange, agentIds }, generatedBy);
+
+    try {
+      const data: Record<string, any> = {};
+      const agentFilter = agentIds && agentIds.length > 0;
+
+      if (this.engineDb) {
+        // Unified timeline from multiple tables
+        const timeline: { timestamp: string; source: string; type: string; agentId: string; detail: string }[] = [];
+
+        // Tool calls
+        const tools = await this.engineDb.query<any>(
+          'SELECT * FROM tool_calls WHERE org_id = ? AND created_at BETWEEN ? AND ? ORDER BY created_at',
+          [orgId, dateRange.from, dateRange.to]
+        ).catch(() => []);
+        for (const t of tools) {
+          if (agentFilter && !agentIds!.includes(t.agent_id)) continue;
+          timeline.push({ timestamp: t.created_at, source: 'tool_call', type: t.tool_id, agentId: t.agent_id, detail: `Tool: ${t.tool_name || t.tool_id}` });
+        }
+
+        // Interventions
+        const ints = await this.engineDb.query<any>(
+          'SELECT * FROM interventions WHERE org_id = ? AND created_at BETWEEN ? AND ? ORDER BY created_at',
+          [orgId, dateRange.from, dateRange.to]
+        ).catch(() => []);
+        for (const i of ints) {
+          if (agentFilter && !agentIds!.includes(i.agent_id)) continue;
+          timeline.push({ timestamp: i.created_at, source: 'intervention', type: i.type, agentId: i.agent_id, detail: i.reason });
+        }
+
+        // DLP violations
+        const dlps = await this.engineDb.query<any>(
+          'SELECT * FROM dlp_violations WHERE org_id = ? AND created_at BETWEEN ? AND ? ORDER BY created_at',
+          [orgId, dateRange.from, dateRange.to]
+        ).catch(() => []);
+        for (const d of dlps) {
+          if (agentFilter && !agentIds!.includes(d.agent_id)) continue;
+          timeline.push({ timestamp: d.created_at, source: 'dlp_violation', type: d.action_taken, agentId: d.agent_id, detail: `Rule ${d.rule_id}: ${d.action_taken}` });
+        }
+
+        // Sort timeline chronologically
+        timeline.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+        data.timeline = timeline;
+        data.summary = {
+          totalEvents: timeline.length,
+          bySource: {} as Record<string, number>,
+          byAgent: {} as Record<string, number>,
+        };
+        for (const e of timeline) {
+          data.summary.bySource[e.source] = (data.summary.bySource[e.source] || 0) + 1;
+          data.summary.byAgent[e.agentId] = (data.summary.byAgent[e.agentId] || 0) + 1;
+        }
+      }
+
+      report.data = data;
+      report.status = 'completed';
+      report.completedAt = new Date().toISOString();
+    } catch (err: any) {
+      report.status = 'failed';
+      report.error = err.message;
+    }
+
+    this.persistReport(report);
+    return report;
+  }
+
+  // ─── Query ────────────────────────────────────────
+
+  getReports(opts?: { orgId?: string; type?: string; limit?: number }): ComplianceReport[] {
+    let list = [...this.reports];
+    if (opts?.orgId) list = list.filter(r => r.orgId === opts.orgId);
+    if (opts?.type) list = list.filter(r => r.type === opts.type);
+    return list.slice(0, opts?.limit || 50);
+  }
+
+  getReport(id: string): ComplianceReport | undefined {
+    return this.reports.find(r => r.id === id);
+  }
+
+  // ─── CSV Export ───────────────────────────────────
+
+  toCSV(report: ComplianceReport): string {
+    if (!report.data) return '';
+
+    if (report.type === 'audit' && report.data.timeline) {
+      const rows = report.data.timeline as any[];
+      if (rows.length === 0) return 'timestamp,source,type,agentId,detail\n';
+      return 'timestamp,source,type,agentId,detail\n' +
+        rows.map((r: any) => `${r.timestamp},${r.source},${r.type},${r.agentId},"${(r.detail || '').replace(/"/g, '""')}"`).join('\n');
+    }
+
+    // Generic flat JSON-to-CSV
+    const flat = this.flattenObject(report.data);
+    return 'key,value\n' + Object.entries(flat).map(([k, v]) => `${k},"${String(v).replace(/"/g, '""')}"`).join('\n');
+  }
+
+  // ─── Private ──────────────────────────────────────
+
+  private createReport(orgId: string, type: ComplianceReport['type'], title: string, parameters: Record<string, any>, generatedBy: string): ComplianceReport {
+    const report: ComplianceReport = {
+      id: crypto.randomUUID(),
+      orgId, type, title, parameters,
+      status: 'generating',
+      format: 'json',
+      generatedBy,
+      createdAt: new Date().toISOString(),
+    };
+    this.reports.unshift(report);
+    if (this.reports.length > 200) this.reports = this.reports.slice(0, 200);
+    return report;
+  }
+
+  private persistReport(report: ComplianceReport): void {
+    this.engineDb?.execute(
+      `INSERT INTO compliance_reports (id, org_id, type, title, parameters, status, data, format, generated_by, error, created_at, completed_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET status=excluded.status, data=excluded.data, error=excluded.error, completed_at=excluded.completed_at`,
+      [report.id, report.orgId, report.type, report.title, JSON.stringify(report.parameters),
+       report.status, report.data ? JSON.stringify(report.data) : null, report.format,
+       report.generatedBy, report.error || null, report.createdAt, report.completedAt || null]
+    ).catch((err) => { console.error('[compliance] Failed to persist report:', err); });
+  }
+
+  private flattenObject(obj: Record<string, any>, prefix = ''): Record<string, string> {
+    const result: Record<string, string> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        Object.assign(result, this.flattenObject(value, path));
+      } else {
+        result[path] = Array.isArray(value) ? `[${value.length} items]` : String(value);
+      }
+    }
+    return result;
+  }
+}