v0.8.0: dashboard audit overhaul — ISO timestamps, rejection_reason, audit_log

Bug 1 — ISO 8601 UTC timestamps with Z suffix:
  SQLite CURRENT_TIMESTAMP ("YYYY-MM-DD HH:MM:SS") is ambiguous about
  timezone and is parsed as local time by the browser. Switched every
  write path to datetime.now(timezone.utc) serialized as
  "YYYY-MM-DDTHH:MM:SSZ". Legacy rows are rewritten in-place on first
  open.

Bug 2 — rejection_reason persisted:
  The issued_seals table had no rejection_reason column, so the
  dashboard REJECTION_LOG always showed an empty REASON cell. Added the
  column, wired client.py to pass the reason through for all three
  rejection paths (budget, engine, success→null), and the dashboard
  now selects and renders it.

audit_log feature:
  New audit_log table (id, event_type, vendor, reasoning, timestamp).
  mcp_server.request_purchaser_info now calls record_audit_event on
  every invocation, wrapped in try/except so logging can never block
  the main flow. New /api/audit dashboard endpoint + AUDIT_LOG section
  in the UI.

Schema migration (upgrade-safe, idempotent):
  (1) rebuild issued_seals if it still has card_number/cvv columns
      (very-legacy path — preserves masked data)
  (2) ALTER ADD rejection_reason if missing
  (3) UPDATE timestamp format from "YYYY-MM-DD HH:MM:SS" to
      "YYYY-MM-DDTHH:MM:SSZ"
  (4) CREATE audit_log table if missing
  Running migration twice is a no-op.

Dashboard/tracker schema drift fix:
  dashboard/server.py no longer runs its own CREATE TABLE for
  issued_seals — it delegates to PopStateTracker so the dashboard and
  MCP server always agree on schema, even when the dashboard is
  launched first against a legacy DB.

Other:
  - datetime.utcnow() → datetime.now(timezone.utc) (3.12+ compat)
  - CONTRIBUTING.md: schema-change SOP, port 3210 rationale
  - 14 new regression tests in tests/test_audit_and_migration.py
    (156 total passing)

Author: TPEmist

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-04-10
+
+### Added
+- **`audit_log` table:** informational audit trail for MCP tool invocations. Every `request_purchaser_info` call now logs `event_type`, `vendor`, `reasoning`, and an ISO 8601 UTC timestamp. Non-blocking — failures to log never interrupt the main flow.
+- **Dashboard AUDIT_LOG section:** new table rendering `/api/audit` events (id, event_type, vendor, reasoning, timestamp).
+- **`PopStateTracker.record_audit_event()` / `.get_audit_events()`:** public API for emitting and reading audit events.
+
+### Fixed
+- **Bug 1 — timestamps now ISO 8601 with `Z` suffix:** `issued_seals.timestamp` previously used SQLite `CURRENT_TIMESTAMP` (`YYYY-MM-DD HH:MM:SS`), which is ambiguous about timezone and parsed as local time by browsers. New inserts use `datetime.now(timezone.utc)` serialized as `YYYY-MM-DDTHH:MM:SSZ`. Legacy rows are migrated in-place on first open.
+- **Bug 2 — `rejection_reason` column now persisted:** dashboard REJECTION_LOG previously showed an empty REASON column because `issued_seals` had no `rejection_reason` column. Added column + wired `client.py` to pass the reason through for all three rejection paths (budget, engine, success→null). Migration adds the column to legacy DBs.
+- **Dashboard/tracker schema drift:** `dashboard/server.py` used to run its own `init_db()` which didn't know about new columns. It now delegates schema creation + migration to `PopStateTracker`, so the dashboard and MCP server always agree on schema even if the dashboard is launched first against a legacy DB.
+
+### Changed
+- **Schema migration (upgrade-safe):** opening a legacy DB now (1) rebuilds `issued_seals` if it still has `card_number`/`cvv` columns (very-legacy path, preserves masked data); (2) adds `rejection_reason` if missing; (3) rewrites legacy `YYYY-MM-DD HH:MM:SS` timestamps to ISO 8601 Z format; (4) creates `audit_log` table. Migration is idempotent — running twice is a no-op.
+- **`datetime.utcnow()` → `datetime.now(timezone.utc)`:** the former is deprecated in Python 3.12+ and returns a naive datetime. The latter is timezone-aware and future-proof.
+- **Dashboard port 3210:** no functional change, but documented: port was chosen arbitrarily during initial dashboard bring-up and is kept for continuity with existing user bookmarks.
+
 ## [0.6.34] - 2026-04-06
 
 ### Fixed

CONTRIBUTING.md

@@ -68,6 +68,19 @@ We use `pytest` for our test suite. To run all tests:
 pytest
 ```
 
+### Schema Changes
+
+`PopStateTracker` (`pop_pay/core/state.py`) is the single source of truth for the SQLite schema. The dashboard (`dashboard/server.py`) delegates all table creation and migration to `PopStateTracker` on startup. If you add or modify a column:
+
+1. Update the `CREATE TABLE` in `PopStateTracker.__init__` so fresh DBs get the new shape.
+2. Add a migration branch next to the existing ones (add-column / rebuild) so legacy DBs upgrade in place. **Migrations must be idempotent** — running them on an already-migrated DB must be a no-op.
+3. Use ISO 8601 UTC with a `Z` suffix for all timestamps (`datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")`). Do **not** use SQLite `CURRENT_TIMESTAMP`, which is ambiguous about timezone and parses as local time in browsers.
+4. Add a regression test in `tests/test_audit_and_migration.py` that constructs a pre-change DB, opens it with `PopStateTracker`, and asserts the new shape.
+
+### Dashboard Port
+
+The local dashboard listens on **port 3210** by default. This number was chosen arbitrarily during initial bring-up; it has no special meaning and is kept stable so existing user bookmarks continue to work. Override with the `--port` flag if you need to run multiple dashboards side-by-side.
+
 ---
 
 ## Call for Contributions
@@ -112,7 +125,7 @@ The `PopBrowserInjector` uses Playwright's `connectOverCDP` for cross-origin ifr
 **Implementation notes:**
 - `mcp_server.py` `request_virtual_card` and `request_purchaser_info` should catch all rejection/block paths and return the opaque string before returning to the agent.
 - `pop_state.db` audit log already stores structured data — the detailed reason should continue to be written there.
-- A new `rejection_detail` column (or existing `rejection_reason`) in `issued_seals` / audit log should surface in the Dashboard's transaction table.
+- The `rejection_reason` column on `issued_seals` (added in v0.8.0) already surfaces in the Dashboard's REJECTION_LOG table. Any new opaque-response work should continue to write the full reason there while returning the generic string to the MCP caller.
 - Edge case: injection failures that require agent action (e.g. "card fields not found — pass page_url") are UX errors, not security rejections, and may still return actionable messages to the agent.
 
 ### 7. Known Payment Processors List

dashboard/dashboard.js

@@ -5,10 +5,27 @@ document.addEventListener('DOMContentLoaded', () => {
     const utilizationFillEl = document.getElementById('utilization-fill');
     const sealsBody = document.getElementById('seals-body');
     const rejectedBody = document.getElementById('rejected-body');
+    const auditBody = document.getElementById('audit-body');
     const refreshBtn = document.getElementById('refresh-btn');
     const maxBudgetInput = document.getElementById('max-daily-budget');
     const saveSettingsBtn = document.getElementById('save-settings');
 
+    const escapeHtml = (value) => {
+        if (value === null || value === undefined) return '';
+        return String(value)
+            .replace(/&/g, '&')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&#39;');
+    };
+
+    const formatTimestamp = (ts) => {
+        if (!ts) return '';
+        const d = new Date(ts);
+        return isNaN(d.getTime()) ? ts : d.toLocaleString();
+    };
+
     let sealsData = [];
 
     const formatCurrency = (amount) => {
@@ -20,19 +37,22 @@ document.addEventListener('DOMContentLoaded', () => {
 
     const fetchData = async () => {
         try {
-            const [budgetRes, sealsRes, rejectedRes] = await Promise.all([
+            const [budgetRes, sealsRes, rejectedRes, auditRes] = await Promise.all([
                 fetch('/api/budget/today'),
                 fetch('/api/seals'),
-                fetch('/api/seals?status=rejected')
+                fetch('/api/seals?status=rejected'),
+                fetch('/api/audit')
             ]);
 
             const budget = await budgetRes.json();
             sealsData = await sealsRes.json();
             const rejected = await rejectedRes.json();
+            const audit = await auditRes.json();
 
             updateBudget(budget);
             renderSeals(sealsData);
             renderRejected(rejected);
+            renderAudit(audit);
         } catch (error) {
             console.error('Failed to fetch dashboard data:', error);
         }
@@ -63,12 +83,12 @@ document.addEventListener('DOMContentLoaded', () => {
         seals.forEach(seal => {
             const row = document.createElement('tr');
             row.innerHTML = `
-                <td>${seal.seal_id}</td>
+                <td>${escapeHtml(seal.seal_id)}</td>
                 <td>${formatCurrency(seal.amount)}</td>
-                <td>${seal.vendor}</td>
-                <td style="color: ${getStatusColor(seal.status)}">${seal.status}</td>
-                <td>${seal.masked_card || 'N/A'}</td>
-                <td>${new Date(seal.timestamp).toLocaleString()}</td>
+                <td>${escapeHtml(seal.vendor)}</td>
+                <td style="color: ${getStatusColor(seal.status)}">${escapeHtml(seal.status)}</td>
+                <td>${escapeHtml(seal.masked_card || 'N/A')}</td>
+                <td>${escapeHtml(formatTimestamp(seal.timestamp))}</td>
             `;
             sealsBody.appendChild(row);
         });
@@ -79,16 +99,32 @@ document.addEventListener('DOMContentLoaded', () => {
         rejected.forEach(seal => {
             const row = document.createElement('tr');
             row.innerHTML = `
-                <td>${seal.seal_id}</td>
+                <td>${escapeHtml(seal.seal_id)}</td>
                 <td>${formatCurrency(seal.amount)}</td>
-                <td>${seal.vendor}</td>
-                <td>${seal.status}</td>
-                <td>${new Date(seal.timestamp).toLocaleString()}</td>
+                <td>${escapeHtml(seal.vendor)}</td>
+                <td>${escapeHtml(seal.rejection_reason || '')}</td>
+                <td>${escapeHtml(formatTimestamp(seal.timestamp))}</td>
             `;
             rejectedBody.appendChild(row);
         });
     };
 
+    const renderAudit = (events) => {
+        if (!auditBody) return;
+        auditBody.innerHTML = '';
+        events.forEach(event => {
+            const row = document.createElement('tr');
+            row.innerHTML = `
+                <td>${escapeHtml(event.id)}</td>
+                <td>${escapeHtml(event.event_type)}</td>
+                <td>${escapeHtml(event.vendor || '')}</td>
+                <td>${escapeHtml(event.reasoning || '')}</td>
+                <td>${escapeHtml(formatTimestamp(event.timestamp))}</td>
+            `;
+            auditBody.appendChild(row);
+        });
+    };
+
     const getStatusColor = (status) => {
         switch (status.toLowerCase()) {
             case 'issued': return 'var(--accent-green)';

dashboard/index.html

@@ -82,6 +82,26 @@ <h3>REJECTION_LOG</h3>
                 </table>
             </div>
         </section>
+
+        <section class="audit-log">
+            <h3>AUDIT_LOG</h3>
+            <div class="table-container">
+                <table id="audit-table">
+                    <thead>
+                        <tr>
+                            <th>ID</th>
+                            <th>EVENT_TYPE</th>
+                            <th>VENDOR</th>
+                            <th>REASONING</th>
+                            <th>TIMESTAMP</th>
+                        </tr>
+                    </thead>
+                    <tbody id="audit-body">
+                        <!-- Data injected here -->
+                    </tbody>
+                </table>
+            </div>
+        </section>
     </main>
 
     <script src="dashboard.js"></script>

dashboard/server.py

@@ -33,6 +33,13 @@ def do_GET(self):
             query = parse_qs(parsed_path.query)
             status_filter = query.get("status", [None])[0]
             self.get_seals(status_filter)
+        elif path == "/api/audit":
+            query = parse_qs(parsed_path.query)
+            try:
+                limit = int(query.get("limit", ["100"])[0])
+            except ValueError:
+                limit = 100
+            self.get_audit(limit)
         elif path.startswith("/api/"):
             self._set_headers(404)
             self.wfile.write(json.dumps({"error": "Not Found"}).encode())
@@ -113,12 +120,12 @@ def get_seals(self, status_filter=None):
 
         if status_filter:
             cursor.execute(
-                "SELECT seal_id, amount, vendor, status, masked_card, timestamp FROM issued_seals WHERE LOWER(status) = LOWER(?) ORDER BY timestamp DESC",
+                "SELECT seal_id, amount, vendor, status, masked_card, timestamp, rejection_reason FROM issued_seals WHERE LOWER(status) = LOWER(?) ORDER BY timestamp DESC",
                 (status_filter,)
             )
         else:
             cursor.execute(
-                "SELECT seal_id, amount, vendor, status, masked_card, timestamp FROM issued_seals ORDER BY timestamp DESC"
+                "SELECT seal_id, amount, vendor, status, masked_card, timestamp, rejection_reason FROM issued_seals ORDER BY timestamp DESC"
             )
 
         rows = cursor.fetchall()
@@ -148,6 +155,30 @@ def get_seals(self, status_filter=None):
         self._set_headers()
         self.wfile.write(json.dumps(seals).encode())
 
+    def get_audit(self, limit: int = 100):
+        conn = self.get_db_connection()
+        conn.row_factory = sqlite3.Row
+        cursor = conn.cursor()
+        # audit_log is created on first MCP server / tracker init; if the
+        # dashboard is launched before that, the table may not yet exist.
+        cursor.execute(
+            "CREATE TABLE IF NOT EXISTS audit_log ("
+            "id INTEGER PRIMARY KEY AUTOINCREMENT, "
+            "event_type TEXT NOT NULL, "
+            "vendor TEXT, "
+            "reasoning TEXT, "
+            "timestamp TEXT NOT NULL)"
+        )
+        cursor.execute(
+            "SELECT id, event_type, vendor, reasoning, timestamp "
+            "FROM audit_log ORDER BY timestamp DESC, id DESC LIMIT ?",
+            (limit,),
+        )
+        rows = [dict(r) for r in cursor.fetchall()]
+        conn.close()
+        self._set_headers()
+        self.wfile.write(json.dumps(rows).encode())
+
     def put_setting(self, key):
         content_length = int(self.headers.get('Content-Length', 0))
         body = self.rfile.read(content_length)
@@ -172,25 +203,15 @@ def put_setting(self, key):
         self.wfile.write(json.dumps({"key": key, "value": value}).encode())
 
 def init_db(db_path):
+    # Delegate schema creation + migrations to the canonical tracker so
+    # dashboard and MCP server always agree on the schema, even if the
+    # dashboard is launched first against a legacy DB.
+    from pop_pay.core.state import PopStateTracker
+    tracker = PopStateTracker(db_path=db_path)
+    tracker.close()
+
     conn = sqlite3.connect(db_path)
     cursor = conn.cursor()
-    cursor.execute("""
-        CREATE TABLE IF NOT EXISTS daily_budget (
-            date TEXT PRIMARY KEY,
-            spent_amount FLOAT
-        )
-    """)
-    cursor.execute("""
-        CREATE TABLE IF NOT EXISTS issued_seals (
-            seal_id TEXT PRIMARY KEY,
-            amount FLOAT,
-            vendor TEXT,
-            status TEXT,
-            masked_card TEXT,
-            expiration_date TEXT,
-            timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
-        )
-    """)
     cursor.execute("""
         CREATE TABLE IF NOT EXISTS dashboard_settings (
             key TEXT PRIMARY KEY,

pop_pay/client.py

@@ -23,10 +23,11 @@ async def process_payment(self, intent: PaymentIntent) -> VirtualSeal:
             )
             # Record rejection
             self.state_tracker.record_seal(
-                seal.seal_id, 
-                seal.authorized_amount, 
-                intent.target_vendor, 
-                status=seal.status
+                seal.seal_id,
+                seal.authorized_amount,
+                intent.target_vendor,
+                status=seal.status,
+                rejection_reason=seal.rejection_reason,
             )
             return seal
 
@@ -41,10 +42,11 @@ async def process_payment(self, intent: PaymentIntent) -> VirtualSeal:
             )
             # Record rejection
             self.state_tracker.record_seal(
-                seal.seal_id, 
-                seal.authorized_amount, 
-                intent.target_vendor, 
-                status=seal.status
+                seal.seal_id,
+                seal.authorized_amount,
+                intent.target_vendor,
+                status=seal.status,
+                rejection_reason=seal.rejection_reason,
             )
             return seal
 
@@ -64,7 +66,8 @@ async def process_payment(self, intent: PaymentIntent) -> VirtualSeal:
             intent.target_vendor,
             status=record_status,
             masked_card=f"****-****-****-{seal.card_number[-4:]}" if seal.card_number else "****-****-****-????",
-            expiration_date=seal.expiration_date
+            expiration_date=seal.expiration_date,
+            rejection_reason=seal.rejection_reason,
         )
 
         if seal.status.lower() != "rejected":