v0.3.0 — cost accountability + LLM call audit trail (#7)

Per-call recording of cost and I/O for every LLM probe. New tables prv_call_meta (schema v3) and prv_call_io. New admin pages: Costs (spend drill-down vs $5 cap) and Call Log (paginated + detail drawer). 90-day I/O retention prune via prv_daily_prune cron. P0 security: key never stored; gateway client exposes HTTP status only. QA APPROVED 2026-06-15 SHA 09dc6db9ce
2026-06-15 17:07:08 +07:00
parent 2f4c1b2c72
commit 2e2c72cac6
37 changed files with 3246 additions and 325 deletions
--- a/includes/core/class-prv-call-meta-table.php
+++ b/includes/core/class-prv-call-meta-table.php
@@ -0,0 +1,112 @@
+<?php
+/**
+ * Database schema for per-call cost/metadata table (v0.3.0).
+ *
+ * @package PrVision
+ */
+
+declare(strict_types=1);
+
+/**
+ * Manages the prv_call_meta table: per-call cost + metadata kept indefinitely.
+ *
+ * Two tables separate concerns introduced in v0.3.0:
+ *   prv_call_meta  — cost + metadata KEPT (this class).
+ *   prv_call_io    — rendered prompt + raw response PRUNED (PRV_Call_Io_Table).
+ *
+ * Schema is forward-only: dbDelta adds columns; no destructive ALTER.
+ * SCHEMA_VERSION bumped to 3 to trigger the migration guard in PRV_Upgrader.
+ *
+ * Who triggers: PRV_Upgrader::run() on every plugins_loaded (idempotent).
+ * Dependencies: $wpdb, dbDelta(), PRV_Table_Manager (existing table retained).
+ *
+ * @see class-prv-call-io-table.php   — Companion prunable I/O table.
+ * @see class-prv-upgrader.php        — Calls create_table() on upgrade.
+ * @see class-prv-capture-writer.php  — Writes rows to this table.
+ * @see ARCHITECTURE.md               — §Storage v0.3.0.
+ * @package PrVision
+ */
+class PRV_Call_Meta_Table {
+
+	/**
+	 * Table base name (without $wpdb->prefix).
+	 */
+	const TABLE_BASE = 'prv_call_meta';
+
+	/**
+	 * Schema version introduced by this table.
+	 */
+	const SCHEMA_VERSION = 3;
+
+	/**
+	 * Create or upgrade the call-meta table via dbDelta.
+	 *
+	 * Safe to call on every plugins_loaded — dbDelta is idempotent.
+	 * Side effects: Database write; may update prv_schema_version option.
+	 *
+	 * @return void
+	 */
+	public static function create_table(): void {
+		global $wpdb;
+
+		$table           = $wpdb->prefix . self::TABLE_BASE;
+		$vis_table       = $wpdb->prefix . 'prv_ai_visibility';
+		$charset_collate = $wpdb->get_charset_collate();
+
+		$sql = "CREATE TABLE {$table} (
+			id             BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+			visibility_row BIGINT(20) UNSIGNED NULL     DEFAULT NULL,
+			run_id         VARCHAR(36)         NOT NULL DEFAULT '',
+			peptide_slug   VARCHAR(200)        NOT NULL DEFAULT '',
+			model          VARCHAR(200)        NOT NULL DEFAULT '',
+			intent_label   VARCHAR(200)        NOT NULL DEFAULT '',
+			tokens_in      INT(11)             NULL     DEFAULT NULL,
+			tokens_out     INT(11)             NULL     DEFAULT NULL,
+			cost_usd       DECIMAL(12,8)       NOT NULL DEFAULT 0.00000000,
+			latency_ms     INT(11)             NULL     DEFAULT NULL,
+			cited          TINYINT(1)          NULL     DEFAULT NULL,
+			http_status    INT(11)             NOT NULL DEFAULT 200,
+			captured_at    DATETIME            NOT NULL,
+			config_version INT(11)             NULL     DEFAULT NULL,
+			io_captured    TINYINT(1)          NOT NULL DEFAULT 0,
+			PRIMARY KEY (id),
+			KEY visibility_row (visibility_row),
+			KEY run_id (run_id),
+			KEY peptide_slug (peptide_slug),
+			KEY model (model),
+			KEY captured_at (captured_at)
+		) {$charset_collate};";
+
+		if ( ! function_exists( 'dbDelta' ) ) {
+			require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+		}
+
+		dbDelta( $sql );
+
+		update_option( 'prv_schema_version', self::SCHEMA_VERSION );
+	}
+
+	/**
+	 * Get the full table name including WP prefix.
+	 *
+	 * @return string
+	 */
+	public static function get_table_name(): string {
+		global $wpdb;
+		return $wpdb->prefix . self::TABLE_BASE;
+	}
+
+	/**
+	 * Drop the table. Called from uninstall.php only.
+	 *
+	 * Side effects: Permanently destroys all call metadata.
+	 *
+	 * @return void
+	 */
+	public static function drop_table(): void {
+		global $wpdb;
+		$table = $wpdb->prefix . self::TABLE_BASE;
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.NoCaching
+		$wpdb->query( "DROP TABLE IF EXISTS {$table}" );
+	}
+}