@ossdeveloper/github-compliance 1.0.0

package/compliance.ts

@@ -0,0 +1,159 @@
+/**
+ * Compliance validation logic for GitHub write tools
+ * 
+ * Handles tool identification, content hashing, and result parsing.
+ */
+
+import { createHash } from "crypto";
+import { SCHEMA, RECORD_STATUS } from "./schema";
+
+/**
+ * List of GitHub write tools that require compliance validation
+ * Read-only tools are not included
+ */
+const GITHUB_WRITE_TOOLS_UNPREFIXED = [
+  "issue_write",
+  "issue_update",
+  "pull_request_write",
+  "pull_request_update",
+  "add_issue_comment",
+  "add_pull_request_comment",
+  "pull_request_review",
+  "pull_request_review_comment",
+  "create_pull_request",
+  "update_issue",
+  "update_pull_request",
+  "push_files",
+  "create_branch",
+  "create_or_update_file",
+  "delete_file",
+  "create_repository",
+  "create_pull_request_with_copilot",
+  "update_pull_request_branch",
+  "reply_to_pull_request_comment",
+  "add_reply_to_pull_request_comment"
+] as const;
+
+const GITHUB_WRITE_TOOLS_PREFIXED = GITHUB_WRITE_TOOLS_UNPREFIXED.map(t => `github_${t}`);
+
+export const GITHUB_WRITE_TOOLS = [...GITHUB_WRITE_TOOLS_UNPREFIXED, ...GITHUB_WRITE_TOOLS_PREFIXED] as const;
+
+export type GitHubWriteTool = typeof GITHUB_WRITE_TOOLS[number];
+
+/**
+ * Extracted information from a tool call for compliance lookup
+ */
+export interface ToolInfo {
+  toolName: string;
+  owner: string;
+  repo: string;
+  title: string | null;
+  body: string | null;
+  contentHash: string;
+}
+
+/**
+ * Check if a tool name is a GitHub write tool requiring compliance
+ * 
+ * @param toolName - Name of the tool to check
+ * @returns True if the tool requires compliance validation
+ */
+export function isGitHubWriteTool(toolName: string): boolean {
+  return GITHUB_WRITE_TOOLS.includes(toolName as GitHubWriteTool);
+}
+
+/**
+ * Extract compliance-relevant information from a tool call
+ * 
+ * Different GitHub tools have different arguments, but they all share
+ * owner/repo and typically have title/body for content.
+ * 
+ * @param toolName - Name of the tool being called
+ * @param args - Arguments passed to the tool
+ * @returns Extracted ToolInfo with content hash
+ */
+export function extractToolInfo(toolName: string, args: Record<string, unknown>): ToolInfo {
+  const owner = (args.owner as string) || "";
+  const repo = (args.repo as string) || "";
+  const title = (args.title as string) || null;
+  const body = (args.body as string) || null;
+  
+  return {
+    toolName,
+    owner,
+    repo,
+    title,
+    body,
+    contentHash: computeContentHash(title, body)
+  };
+}
+
+/**
+ * Compute a SHA256 hash of the content for integrity verification
+ * 
+ * The hash is computed over a normalized JSON string containing
+ * the content-determining fields. This ensures:
+ * - Same content = same hash
+ * - Different content = different hash
+ * 
+ * @param title - Issue/PR title (or null)
+ * @param body - Issue/PR body (or null)
+ * @returns Hash string in format "sha256:..."
+ */
+export function computeContentHash(title: string | null, body: string | null): string {
+  const content = JSON.stringify({
+    title: title || "",
+    body: body || ""
+  });
+  return "sha256:" + createHash("sha256").update(content).digest("hex");
+}
+
+/**
+ * Extract GitHub issue/PR ID from a tool execution result
+ * 
+ * GitHub MCP tools return results with 'number' or 'id' fields.
+ * This helper extracts the numeric/string ID for audit logging.
+ * 
+ * @param result - Raw tool execution result
+ * @returns GitHub ID if found, null otherwise
+ */
+export function extractGitHubId(result: unknown): string | null {
+  if (!result || typeof result !== "object") return null;
+  
+  const r = result as Record<string, unknown>;
+  
+  if (typeof r.number === "number") {
+    return String(r.number);
+  }
+  
+  if (typeof r.id === "string" || typeof r.id === "number") {
+    return String(r.id);
+  }
+  
+  return null;
+}
+
+/**
+ * Extract GitHub URL from a tool execution result
+ * 
+ * GitHub MCP tools return results with 'html_url' or 'url' fields.
+ * This helper extracts the URL for audit logging.
+ * 
+ * @param result - Raw tool execution result
+ * @returns GitHub URL if found, null otherwise
+ */
+export function extractGitHubUrl(result: unknown): string | null {
+  if (!result || typeof result !== "object") return null;
+  
+  const r = result as Record<string, unknown>;
+  
+  if (typeof r.html_url === "string") {
+    return r.html_url;
+  }
+  
+  if (typeof r.url === "string") {
+    return r.url;
+  }
+  
+  return null;
+}

package/database.ts

@@ -0,0 +1,563 @@
+/**
+ * Database operations for GitHub Compliance Plugin
+ * 
+ * Manages SQLite database for compliance records, audit logs, and failed attempts.
+ * Uses centralized schema from schema.ts for all table/column names.
+ */
+
+import Database from "bun:sqlite";
+import { createHash } from "crypto";
+import { mkdir } from "fs";
+import { homedir } from "os";
+import { 
+  SCHEMA, 
+  RECORD_STATUS, 
+  RECORD_TTL_MS, 
+  RECORD_CLEANUP_AGE_MS,
+  CONTENT_PREVIEW_MAX_LENGTH 
+} from "./schema";
+
+const DB_DIR = `${homedir()}/.opencode`;
+const DB_PATH = `${DB_DIR}/github-compliance.db`;
+
+let db: Database | null = null;
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Compliance record stored in SQLite
+ * Represents approval for a specific GitHub write operation
+ */
+export interface ComplianceRecord {
+  id: string;
+  tool_name: string;
+  owner: string;
+  repo: string;
+  title: string | null;
+  content_hash: string;
+  github_username: string;
+  approved_at: string;
+  expires_at: string;
+  status: typeof RECORD_STATUS[keyof typeof RECORD_STATUS];
+  created_at: string;
+  client_name: string;
+  policy_version: string;
+}
+
+/**
+ * Individual compliance check performed
+ * e.g., CONTRIBUTING.md read, duplicate search, etc.
+ */
+export interface ComplianceCheck {
+  id: string;
+  compliance_record_id: string;
+  check_type: string;
+  check_passed: number;
+  details: string | null;
+}
+
+/**
+ * Audit log entry for successful operations
+ */
+export interface AuditEntry {
+  compliance_record_id: string | null;
+  tool_name: string;
+  owner: string;
+  repo: string;
+  github_username: string;
+  status: string;
+  error_message: string | null;
+  github_url: string | null;
+  github_id: string | null;
+  executed_at: string;
+  content_preview: string | null;
+}
+
+/**
+ * Failed attempt record for rejected operations
+ */
+export interface FailedAttemptEntry {
+  tool_name: string;
+  owner: string;
+  repo: string;
+  reason: string;
+  content_hash: string | null;
+  provided_record_id: string | null;
+  error_details: string | null;
+}
+
+/**
+ * Input for creating a new compliance record
+ */
+export interface CreateRecordInput {
+  tool_name: string;
+  owner: string;
+  repo: string;
+  title: string | null;
+  body: string;
+  github_username: string;
+  approved_at: string;
+  checks: Array<{
+    check_type: string;
+    passed: boolean;
+    details: Record<string, unknown>;
+  }>;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function uuid(): string {
+  return crypto.randomUUID();
+}
+
+function computeContentHash(title: string | null, body: string): string {
+  const content = JSON.stringify({
+    title: title || "",
+    body: body || ""
+  });
+  return "sha256:" + createHash("sha256").update(content).digest("hex");
+}
+
+// ============================================================================
+// Database Initialization
+// ============================================================================
+
+/**
+ * Initialize the SQLite database
+ * 
+ * Creates the database file and tables if they don't exist.
+ * Tables: compliance_records, compliance_checks, audit_log, failed_attempts
+ */
+export async function initDatabase(): Promise<void> {
+  if (db) return;
+
+  try {
+    await mkdir(DB_DIR, { recursive: true });
+  } catch {
+    // Directory may already exist
+  }
+
+  db = new Database(DB_PATH);
+  db.run("PRAGMA foreign_keys = ON");
+
+  // Main compliance records table
+  db.run(`
+    CREATE TABLE IF NOT EXISTS ${SCHEMA.tables.COMPLIANCE_RECORDS} (
+      ${SCHEMA.columns.ID} TEXT PRIMARY KEY,
+      ${SCHEMA.columns.TOOL_NAME} TEXT NOT NULL,
+      ${SCHEMA.columns.OWNER} TEXT NOT NULL,
+      ${SCHEMA.columns.REPO} TEXT NOT NULL,
+      ${SCHEMA.columns.TITLE} TEXT,
+      ${SCHEMA.columns.CONTENT_HASH} TEXT NOT NULL,
+      ${SCHEMA.columns.GITHUB_USERNAME} TEXT NOT NULL,
+      ${SCHEMA.columns.APPROVED_AT} TEXT NOT NULL,
+      ${SCHEMA.columns.EXPIRES_AT} TEXT NOT NULL,
+      ${SCHEMA.columns.STATUS} TEXT DEFAULT '${RECORD_STATUS.PENDING}',
+      ${SCHEMA.columns.CREATED_AT} TEXT NOT NULL,
+      ${SCHEMA.columns.CLIENT_NAME} TEXT DEFAULT 'opencode',
+      ${SCHEMA.columns.POLICY_VERSION} TEXT DEFAULT '1.0',
+      UNIQUE(${SCHEMA.columns.TOOL_NAME}, ${SCHEMA.columns.OWNER}, ${SCHEMA.columns.REPO}, ${SCHEMA.columns.CONTENT_HASH})
+    )
+  `);
+
+  // Individual checks performed for each record
+  db.run(`
+    CREATE TABLE IF NOT EXISTS ${SCHEMA.tables.COMPLIANCE_CHECKS} (
+      ${SCHEMA.columns.ID} TEXT PRIMARY KEY,
+      ${SCHEMA.columns.COMPLIANCE_RECORD_ID} TEXT NOT NULL,
+      ${SCHEMA.columns.CHECK_TYPE} TEXT NOT NULL,
+      ${SCHEMA.columns.CHECK_PASSED} INTEGER NOT NULL,
+      ${SCHEMA.columns.DETAILS} TEXT,
+      FOREIGN KEY (${SCHEMA.columns.COMPLIANCE_RECORD_ID}) REFERENCES ${SCHEMA.tables.COMPLIANCE_RECORDS}(${SCHEMA.columns.ID}) ON DELETE CASCADE
+    )
+  `);
+
+  // Audit log of all successful operations
+  db.run(`
+    CREATE TABLE IF NOT EXISTS ${SCHEMA.tables.AUDIT_LOG} (
+      ${SCHEMA.columns.ID} TEXT PRIMARY KEY,
+      ${SCHEMA.columns.COMPLIANCE_RECORD_ID} TEXT,
+      ${SCHEMA.columns.TOOL_NAME} TEXT NOT NULL,
+      ${SCHEMA.columns.OWNER} TEXT NOT NULL,
+      ${SCHEMA.columns.REPO} TEXT NOT NULL,
+      ${SCHEMA.columns.GITHUB_USERNAME} TEXT NOT NULL,
+      ${SCHEMA.columns.STATUS} TEXT NOT NULL,
+      ${SCHEMA.columns.ERROR_MESSAGE} TEXT,
+      ${SCHEMA.columns.GITHUB_URL} TEXT,
+      ${SCHEMA.columns.GITHUB_ID} TEXT,
+      ${SCHEMA.columns.EXECUTED_AT} TEXT NOT NULL,
+      ${SCHEMA.columns.CLIENT_NAME} TEXT DEFAULT 'opencode',
+      ${SCHEMA.columns.CONTENT_PREVIEW} TEXT
+    )
+  `);
+
+  // Failed attempts for debugging and analysis
+  db.run(`
+    CREATE TABLE IF NOT EXISTS ${SCHEMA.tables.FAILED_ATTEMPTS} (
+      ${SCHEMA.columns.ID} TEXT PRIMARY KEY,
+      ${SCHEMA.columns.TOOL_NAME} TEXT NOT NULL,
+      ${SCHEMA.columns.OWNER} TEXT NOT NULL,
+      ${SCHEMA.columns.REPO} TEXT NOT NULL,
+      ${SCHEMA.columns.REASON} TEXT NOT NULL,
+      ${SCHEMA.columns.CONTENT_HASH} TEXT,
+      ${SCHEMA.columns.PROVIDED_RECORD_ID} TEXT,
+      ${SCHEMA.columns.ATTEMPTED_AT} TEXT NOT NULL,
+      ${SCHEMA.columns.GITHUB_USERNAME} TEXT,
+      ${SCHEMA.columns.ERROR_DETAILS} TEXT
+    )
+  `);
+
+  // Indexes for performance
+  db.run(`CREATE INDEX IF NOT EXISTS ${SCHEMA.indexes.COMPLIANCE_LOOKUP} ON ${SCHEMA.tables.COMPLIANCE_RECORDS}(${SCHEMA.columns.TOOL_NAME}, ${SCHEMA.columns.OWNER}, ${SCHEMA.columns.REPO}, ${SCHEMA.columns.STATUS})`);
+  db.run(`CREATE INDEX IF NOT EXISTS ${SCHEMA.indexes.COMPLIANCE_EXPIRES} ON ${SCHEMA.tables.COMPLIANCE_RECORDS}(${SCHEMA.columns.EXPIRES_AT})`);
+}
+
+/**
+ * Get the database instance, initializing if needed
+ */
+export async function getDatabase(): Promise<Database> {
+  if (!db) {
+    await initDatabase();
+  }
+  return db!;
+}
+
+// ============================================================================
+// Compliance Records
+// ============================================================================
+
+/**
+ * Look up a compliance record by tool, repo, and content hash
+ * 
+ * @param toolName - GitHub tool name (e.g., "issue_write")
+ * @param owner - Repository owner
+ * @param repo - Repository name
+ * @param contentHash - SHA256 hash of the content
+ * @returns Compliance record if found, null otherwise
+ */
+export async function getComplianceRecord(
+  toolName: string,
+  owner: string,
+  repo: string,
+  contentHash: string
+): Promise<ComplianceRecord | null> {
+  const database = await getDatabase();
+  const stmt = database.prepare(`
+    SELECT * FROM ${SCHEMA.tables.COMPLIANCE_RECORDS} 
+    WHERE ${SCHEMA.columns.TOOL_NAME} = ? 
+      AND ${SCHEMA.columns.OWNER} = ? 
+      AND ${SCHEMA.columns.REPO} = ? 
+      AND ${SCHEMA.columns.CONTENT_HASH} = ?
+  `);
+  
+  return stmt.get(toolName, owner, repo, contentHash) as ComplianceRecord | null;
+}
+
+/**
+ * Validation result returned by validateCompliance
+ */
+export interface ValidationResult {
+  valid: boolean;
+  reason: string;
+  message: string;
+}
+
+/**
+ * Validate a compliance record for a tool call
+ * 
+ * Checks:
+ * - Record exists
+ * - Status is 'approved' (not pending/used/expired)
+ * - Not expired (expires_at > now)
+ * 
+ * @param record - Compliance record to validate (or null)
+ * @param toolInfo - Tool information for context
+ * @returns Validation result with reason if invalid
+ */
+export async function validateCompliance(
+  record: ComplianceRecord | null,
+  toolInfo: { toolName: string; owner: string; repo: string; contentHash: string }
+): Promise<ValidationResult> {
+  if (!record) {
+    return {
+      valid: false,
+      reason: "NO_RECORD",
+      message: "No compliance record found for this operation."
+    };
+  }
+  
+  if (record.status === RECORD_STATUS.PENDING) {
+    return {
+      valid: false,
+      reason: "NOT_APPROVED",
+      message: "Compliance record exists but has not been approved by user."
+    };
+  }
+  
+  if (record.status === RECORD_STATUS.USED) {
+    return {
+      valid: false,
+      reason: "ALREADY_USED",
+      message: "This compliance record has already been used."
+    };
+  }
+  
+  if (record.status === RECORD_STATUS.EXPIRED) {
+    return {
+      valid: false,
+      reason: "EXPIRED",
+      message: "Compliance record has expired."
+    };
+  }
+  
+  const now = new Date();
+  const expiresAt = new Date(record.expires_at);
+  
+  if (now > expiresAt) {
+    return {
+      valid: false,
+      reason: "EXPIRED",
+      message: "Compliance record has expired."
+    };
+  }
+  
+  return { valid: true, reason: "", message: "" };
+}
+
+/**
+ * Mark a compliance record as 'used'
+ * 
+ * Called after successful tool execution to prevent replay.
+ * 
+ * @param recordId - ID of the record to mark as used
+ */
+export async function markRecordUsed(recordId: string): Promise<void> {
+  const database = await getDatabase();
+  const stmt = database.prepare(`
+    UPDATE ${SCHEMA.tables.COMPLIANCE_RECORDS} 
+    SET ${SCHEMA.columns.STATUS} = '${RECORD_STATUS.USED}' 
+    WHERE ${SCHEMA.columns.ID} = ?
+  `);
+  stmt.run(recordId);
+}
+
+/**
+ * Create a new compliance record after user approval
+ * 
+ * Called by the LLM via create_compliance_record tool after
+ * the user explicitly approves the draft.
+ * 
+ * @param data - Record data including checks performed
+ * @returns UUID of the created record
+ */
+export async function createComplianceRecord(data: CreateRecordInput): Promise<string> {
+  const database = await getDatabase();
+  const id = uuid();
+  const now = new Date();
+  const expiresAt = new Date(now.getTime() + RECORD_TTL_MS);
+  const contentHash = computeContentHash(data.title, data.body);
+  
+  const stmt = database.prepare(`
+    INSERT INTO ${SCHEMA.tables.COMPLIANCE_RECORDS} (
+      ${SCHEMA.columns.ID},
+      ${SCHEMA.columns.TOOL_NAME},
+      ${SCHEMA.columns.OWNER},
+      ${SCHEMA.columns.REPO},
+      ${SCHEMA.columns.TITLE},
+      ${SCHEMA.columns.CONTENT_HASH},
+      ${SCHEMA.columns.GITHUB_USERNAME},
+      ${SCHEMA.columns.APPROVED_AT},
+      ${SCHEMA.columns.EXPIRES_AT},
+      ${SCHEMA.columns.STATUS},
+      ${SCHEMA.columns.CREATED_AT}
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, '${RECORD_STATUS.APPROVED}', ?)
+  `);
+  
+  stmt.run(
+    id,
+    data.tool_name,
+    data.owner,
+    data.repo,
+    data.title || null,
+    contentHash,
+    data.github_username,
+    data.approved_at,
+    expiresAt.toISOString(),
+    now.toISOString()
+  );
+  
+  // Insert individual checks
+  for (const check of data.checks) {
+    const checkStmt = database.prepare(`
+      INSERT INTO ${SCHEMA.tables.COMPLIANCE_CHECKS} (
+        ${SCHEMA.columns.ID},
+        ${SCHEMA.columns.COMPLIANCE_RECORD_ID},
+        ${SCHEMA.columns.CHECK_TYPE},
+        ${SCHEMA.columns.CHECK_PASSED},
+        ${SCHEMA.columns.DETAILS}
+      ) VALUES (?, ?, ?, ?, ?)
+    `);
+    checkStmt.run(
+      uuid(),
+      id,
+      check.check_type,
+      check.passed ? 1 : 0,
+      JSON.stringify(check.details)
+    );
+  }
+  
+  return id;
+}
+
+/**
+ * Check if a valid compliance record exists
+ * 
+ * @param toolName - GitHub tool name
+ * @param owner - Repository owner
+ * @param repo - Repository name
+ * @param contentHash - SHA256 hash of content
+ * @returns Status of any existing record
+ */
+export async function getComplianceStatus(
+  toolName: string,
+  owner: string,
+  repo: string,
+  contentHash: string
+): Promise<{ exists: boolean; status: string | null; expires_at: string | null; approved_at: string | null }> {
+  const record = await getComplianceRecord(toolName, owner, repo, contentHash);
+  
+  if (!record) {
+    return { exists: false, status: null, expires_at: null, approved_at: null };
+  }
+  
+  return {
+    exists: true,
+    status: record.status,
+    expires_at: record.expires_at,
+    approved_at: record.approved_at
+  };
+}
+
+// ============================================================================
+// Audit Logging
+// ============================================================================
+
+/**
+ * Log a successful operation to the audit trail
+ * 
+ * @param entry - Audit entry with operation details
+ */
+export async function logAudit(entry: AuditEntry): Promise<void> {
+  const database = await getDatabase();
+  const stmt = database.prepare(`
+    INSERT INTO ${SCHEMA.tables.AUDIT_LOG} (
+      ${SCHEMA.columns.ID},
+      ${SCHEMA.columns.COMPLIANCE_RECORD_ID},
+      ${SCHEMA.columns.TOOL_NAME},
+      ${SCHEMA.columns.OWNER},
+      ${SCHEMA.columns.REPO},
+      ${SCHEMA.columns.GITHUB_USERNAME},
+      ${SCHEMA.columns.STATUS},
+      ${SCHEMA.columns.ERROR_MESSAGE},
+      ${SCHEMA.columns.GITHUB_URL},
+      ${SCHEMA.columns.GITHUB_ID},
+      ${SCHEMA.columns.EXECUTED_AT},
+      ${SCHEMA.columns.CLIENT_NAME},
+      ${SCHEMA.columns.CONTENT_PREVIEW}
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  stmt.run(
+    uuid(),
+    entry.compliance_record_id,
+    entry.tool_name,
+    entry.owner,
+    entry.repo,
+    entry.github_username,
+    entry.status,
+    entry.error_message || null,
+    entry.github_url || null,
+    entry.github_id || null,
+    entry.executed_at,
+    "opencode",
+    entry.content_preview ? entry.content_preview.substring(0, CONTENT_PREVIEW_MAX_LENGTH) : null
+  );
+}
+
+/**
+ * Log a failed/rejected attempt for debugging and analysis
+ * 
+ * @param entry - Failed attempt entry with rejection reason
+ */
+export async function logFailedAttempt(entry: FailedAttemptEntry): Promise<void> {
+  const database = await getDatabase();
+  const stmt = database.prepare(`
+    INSERT INTO ${SCHEMA.tables.FAILED_ATTEMPTS} (
+      ${SCHEMA.columns.ID},
+      ${SCHEMA.columns.TOOL_NAME},
+      ${SCHEMA.columns.OWNER},
+      ${SCHEMA.columns.REPO},
+      ${SCHEMA.columns.REASON},
+      ${SCHEMA.columns.CONTENT_HASH},
+      ${SCHEMA.columns.PROVIDED_RECORD_ID},
+      ${SCHEMA.columns.ATTEMPTED_AT},
+      ${SCHEMA.columns.GITHUB_USERNAME},
+      ${SCHEMA.columns.ERROR_DETAILS}
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  stmt.run(
+    uuid(),
+    entry.tool_name,
+    entry.owner,
+    entry.repo,
+    entry.reason,
+    entry.content_hash || null,
+    entry.provided_record_id || null,
+    new Date().toISOString(),
+    null,
+    entry.error_details || null
+  );
+}
+
+// ============================================================================
+// Cleanup
+// ============================================================================
+
+/**
+ * Mark all expired records as 'expired'
+ * Should be called periodically (e.g., on startup)
+ * 
+ * @returns Number of records marked as expired
+ */
+export async function cleanupExpiredRecords(): Promise<number> {
+  const database = await getDatabase();
+  const now = new Date().toISOString();
+  const stmt = database.prepare(`
+    UPDATE ${SCHEMA.tables.COMPLIANCE_RECORDS} 
+    SET ${SCHEMA.columns.STATUS} = '${RECORD_STATUS.EXPIRED}'
+    WHERE ${SCHEMA.columns.EXPIRES_AT} < ? 
+      AND ${SCHEMA.columns.STATUS} = '${RECORD_STATUS.APPROVED}'
+  `);
+  const result = stmt.run(now);
+  return result.changes;
+}
+
+/**
+ * Delete old records (older than 7 days)
+ * Cleanup job for maintenance
+ * 
+ * @returns Number of records deleted
+ */
+export async function cleanupOldRecords(): Promise<number> {
+  const database = await getDatabase();
+  const cutoff = new Date(Date.now() - RECORD_CLEANUP_AGE_MS).toISOString();
+  const stmt = database.prepare(`
+    DELETE FROM ${SCHEMA.tables.COMPLIANCE_RECORDS} 
+    WHERE ${SCHEMA.columns.EXPIRES_AT} < ?
+  `);
+  const result = stmt.run(cutoff);
+  return result.changes;
+}