feat: Foundry sync diagnostics, error recovery & validation report (Sprint F-QoL)

Server-side:
- ValidationReport type with BuildValidationReport() on SystemManifest
- Analyzes categories, fields, presets, Foundry compatibility, warnings
- SystemValidationReport templ component shows capability badges after upload

Foundry module:
- api-client.mjs: health metrics (success/error counts, uptime, reconnects),
  structured error log, retry queue for failed writes (auto-retries on reconnect)
- sync-dashboard.mjs: Status tab now shows diagnostics grid, error log,
  field mapping debug info (adapter type, system ID, character type)
- sync-dashboard.hbs: new diagnostics, error log, and field mapping sections
- chronicle-sync.css: diagnostics grid and error log styles

3 new tests for ValidationReport. Dagger Heart added to future systems list.

https://claude.ai/code/session_01PeB1HsjEYNPSY2iqa7sqqR

Author: claude

.ai/status.md

@@ -8,7 +8,17 @@
 <!-- ====================================================================== -->
 
 ## Last Updated
-2026-03-12 -- **Sprint F-4.5: Generic System Adapter & Dynamic Matching.**
+2026-03-12 -- **Sprint F-QoL: Foundry Sync Diagnostics & Error Handling.**
+
+38. **Sprint F-QoL: Foundry Sync Diagnostics (DONE).**
+    - **Validation report** — New `ValidationReport` type and `BuildValidationReport()` on `SystemManifest`. Analyzes categories, fields, presets, Foundry compatibility, mapped/writable fields, and generates warnings. Shown in custom system section after upload.
+    - **Template update** — `SystemValidationReport` templ component renders capability badges (categories, fields, presets, character fields), Foundry compatibility status, field mapping summary, and warnings.
+    - **API client health metrics** — `api-client.mjs` now tracks REST success/error counts, reconnect attempts, connection uptime, last success/error timestamps. New `_errorLog` array with structured error entries (method, path, status, message). `getUptimePercent()` computes session uptime.
+    - **Retry queue** — New `queueForRetry()` method for failed write operations. `processRetryQueue()` runs on WebSocket reconnect, retrying up to 3 times with structured logging. Queue capped at 50 entries.
+    - **Dashboard diagnostics** — Status tab now shows: 4-column diagnostics grid (uptime%, API OK, API errors, reconnects), last success/error timestamps, pending retry count, field mapping debug info (adapter type, system ID, character type slug), and separate error log section.
+    - **Dashboard CSS** — Added `.diagnostics-grid`, `.diagnostics-detail`, `.error-value`, `.error-text`, `.error-log` styles.
+    - **Tests** — 3 new tests: `BuildValidationReport_FullSystem`, `BuildValidationReport_MinimalSystem`, `BuildValidationReport_NoFoundryPaths`. All pass.
+    - **Dagger Heart** added to deferred systems list alongside Draw Steel.
 
 37. **Sprint F-4.5: Generic System Adapter (DONE).**
     - **Manifest schema** — Added `foundry_system_id` to `SystemManifest`, `foundry_path` and `foundry_writable` to `FieldDef`. `IsFoundryWritable()` helper defaults to true when nil. New `CharacterFieldsForAPI()` builds API response with field annotations.

.ai/todo.md

@@ -279,7 +279,7 @@ _WASM-sandboxed backend logic via Extism/wazero. See ADR-021._
 - [x] **Sprint R-3: Write Host Functions** — 6 write host functions (update_entity_fields, create_event, set_entity_tags, get_entity_tags, create_relation, send_message). 5 new capabilities. 4 write adapters. Plugin-to-plugin async messaging. 10 new tests (48 total).
 - [x] **Sprint R-4: Plugin SDK & Developer Tools** — Example WASM plugins (Rust auto-tagger, Go session-logger). Go SDK with MockHost test harness (9 tests). Plugin development guide. 7 new manifest tests. **Phase R complete.**
 
-### Phase F: Foundry Sync Enhancements & Character Integration ← CURRENT (F-QoL next)
+### Phase F: Foundry Sync Enhancements & Character Integration ← CURRENT (F-5 next)
 
 _Improve Foundry VTT sync fidelity. Add system-aware character sheet sync. Build toward inventory/NPC features._
 
@@ -288,7 +288,7 @@ _Improve Foundry VTT sync fidelity. Add system-aware character sheet sync. Build
 - [x] **Sprint F-3: System Detection & Character Field Templates** — Expanded dnd5e character preset (15 fields: class, level, race, alignment + 6 ability scores + HP/AC/speed/proficiency). Added pf2e character preset (15 fields: class, level, ancestry, heritage + 6 ability mods + HP/AC/perception/speed). `CharacterPreset()` helper on `SystemManifest`. New `GET /api/v1/campaigns/:id/systems` endpoint returns available systems with enabled flag. Foundry module: `syncCharacters` + `detectedSystem` settings, `SYSTEM_MAP` table, `_detectSystem()` on start, `getMatchedSystem()` accessor. Dashboard Status tab shows system match info and character sync availability.
 - [x] **Sprint F-4: Actor ↔ Entity Sync** — `actor-sync.mjs` with bidirectional Actor ↔ entity sync. System adapters: `dnd5e-adapter.mjs` (15 fields), `pf2e-adapter.mjs` (HP/name back only). Dashboard Characters tab with Push button. Registered in module.mjs. TESTING.md updated. **Note: adapters and SYSTEM_MAP are hardcoded — see F-4.5.**
 - [x] **Sprint F-4.5: Generic System Adapter & Dynamic Matching** — Added `foundry_system_id` to manifest, `foundry_path`/`foundry_writable` to FieldDef. New `GET /systems/:id/character-fields` API. `_detectSystem()` now API-driven (matches by `foundry_system_id`). New `generic-adapter.mjs` auto-generates field mappings from API. dnd5e (15 fields), pf2e (15 fields, most read-only), drawsteel annotated. actor-sync.mjs falls back to generic adapter. 7 new tests.
-- [ ] **Sprint F-QoL: Foundry Sync Diagnostics & Error Handling** — Validation report UI on system upload (field count, presets, Foundry compatibility). System preview before enabling. Foundry sync health dashboard (connection uptime, last sync timestamps, error log, retry buttons). Graceful error recovery (queue pending changes on disconnect, retry on reconnect). Field mapping debug view in Foundry dashboard.
+- [x] **Sprint F-QoL: Foundry Sync Diagnostics & Error Handling** — `ValidationReport` type with `BuildValidationReport()` analyzing categories, fields, presets, Foundry compatibility, warnings. Templ component shows capability badges + warnings after upload. API client health metrics (success/error counts, uptime, reconnect attempts). Structured error log. Retry queue for failed writes (processes on reconnect, max 3 retries). Dashboard Status tab: diagnostics grid, error log, field mapping debug info. 3 new tests.
 - [ ] **Sprint F-5: NPC Viewer / Hall (Plugin + Widget + Foundry Sync)** — Full NPC plugin at `internal/plugins/npcs/` with handler/service/repo/templates. Campaign route `/campaigns/:id/npcs` — gallery/grid of revealed NPCs (non-private character entities). Portrait, name, description, location, faction. Filters by location/organization/relation. "Reveal" = DM toggles visibility. `npc_gallery` layout block type for entity pages and dashboards. Foundry sync: NPC visibility changes sync bidirectionally — DM reveals/hides NPC in Foundry → Chronicle entity visibility updates and vice versa via actor-sync. Long-term: NPC relationship map (filtered relation graph).
 - [ ] **Sprint F-6: Armory / Inventory System** — Items as entities with game-mechanic fields (weight, cost, rarity, damage, properties). Character "Inventory" tab/block via entity relations. Relation metadata: equipped, quantity, attunement. System-specific item templates (dnd5e ≠ pf2e). Foundry sync: Actor inventory ↔ Chronicle inventory relations. "Armory" campaign page showing all catalogued items.
 - [ ] **Sprint F-7: Shop / Marketplace Enhancement** — Transaction logging (who bought what, when). Currency tracking per character. Stock management (auto-deplete on purchase). Foundry: purchase from shop window → update character inventory on both sides.
@@ -308,7 +308,8 @@ is truly modular and self-service._
 ### Deferred to Phase S+ (or community contributions)
 
 - [ ] **Module Builder UI** — Guided wizard that helps users create custom game system modules through the web UI. Step-by-step: name/metadata → define categories → define fields per category → paste/upload reference data → preview tooltips → export as module directory. Eliminates need to hand-write manifest.json + data files.
-- [ ] Draw Steel module
+- [ ] Draw Steel module (system data + Foundry adapter)
+- [ ] Dagger Heart module (system data + Foundry adapter)
 - [ ] Whiteboards / freeform canvas (Tldraw/Excalidraw)
 - [ ] Offline mode / service worker caching
 - [ ] Collaborative editing presence indicators

foundry-module/scripts/api-client.mjs

@@ -2,8 +2,9 @@
  * Chronicle Sync - API Client
  *
  * Handles both REST API calls and WebSocket connection to the Chronicle server.
- * Provides auto-reconnect with exponential backoff for WebSocket, and a
- * message queue for offline buffering.
+ * Provides auto-reconnect with exponential backoff for WebSocket, a message
+ * queue for offline buffering, health metrics, error logging, and a retry
+ * queue for failed write operations.
  */
 
 import { getSetting } from './settings.mjs';
@@ -37,12 +38,45 @@ export class ChronicleAPI {
 
     /** @type {Set<Function>} Callbacks invoked when connection state changes. */
     this._stateChangeCallbacks = new Set();
+
+    // --- Health metrics (F-QoL) ---
+
+    /** @type {object} Connection and sync health metrics. */
+    this.health = {
+      /** Total successful REST API calls this session. */
+      restSuccessCount: 0,
+      /** Total failed REST API calls this session. */
+      restErrorCount: 0,
+      /** Total WebSocket reconnection attempts this session. */
+      reconnectAttempts: 0,
+      /** Timestamp (ms) of when the current connection was established. */
+      connectedSince: null,
+      /** Total time connected (ms), excluding current connection. */
+      totalConnectedMs: 0,
+      /** Timestamp (ms) of last successful REST call. */
+      lastRestSuccess: null,
+      /** Timestamp (ms) of last REST error. */
+      lastRestError: null,
+    };
+
+    /** @type {Array<{time: number, level: string, method: string, path: string, status: number|null, message: string}>} */
+    this._errorLog = [];
+
+    /** @type {number} Maximum error log entries. */
+    this._maxErrorLogEntries = 50;
+
+    /** @type {Array<{method: string, path: string, body: string|null, retries: number, maxRetries: number}>} */
+    this._retryQueue = [];
+
+    /** @type {boolean} Whether we're currently processing the retry queue. */
+    this._retryProcessing = false;
   }
 
   // --- REST API ---
 
   /**
    * Make an authenticated REST API call to Chronicle.
+   * Tracks health metrics and logs errors.
    * @param {string} path - API path (e.g., '/entities').
    * @param {object} [options] - Fetch options.
    * @returns {Promise<any>} Parsed JSON response.
@@ -53,23 +87,40 @@ export class ChronicleAPI {
     const campaignId = getSetting('campaignId');
 
     const url = `${baseUrl}/api/v1/campaigns/${campaignId}${path}`;
+    const method = options.method || 'GET';
 
     const headers = {
       'Authorization': `Bearer ${apiKey}`,
       'Content-Type': 'application/json',
       ...options.headers,
     };
 
-    const response = await fetch(url, {
-      ...options,
-      headers,
-    });
+    let response;
+    try {
+      response = await fetch(url, {
+        ...options,
+        headers,
+      });
+    } catch (err) {
+      // Network error (no response at all).
+      this.health.restErrorCount++;
+      this.health.lastRestError = Date.now();
+      this._logError('error', method, path, null, err.message || 'Network error');
+      throw err;
+    }
 
     if (!response.ok) {
       const errorBody = await response.text();
+      this.health.restErrorCount++;
+      this.health.lastRestError = Date.now();
+      this._logError('error', method, path, response.status, errorBody);
       throw new Error(`Chronicle API error ${response.status}: ${errorBody}`);
     }
 
+    // Success.
+    this.health.restSuccessCount++;
+    this.health.lastRestSuccess = Date.now();
+
     // Handle 204 No Content.
     if (response.status === 204) return null;
 
@@ -157,12 +208,163 @@ export class ChronicleAPI {
     );
 
     if (!response.ok) {
+      this.health.restErrorCount++;
+      this.health.lastRestError = Date.now();
+      this._logError('error', 'POST', '/media', response.status, 'Media upload failed');
       throw new Error(`Media upload failed: ${response.status}`);
     }
 
+    this.health.restSuccessCount++;
+    this.health.lastRestSuccess = Date.now();
     return response.json();
   }
 
+  // --- Retry queue (F-QoL) ---
+
+  /**
+   * Queue a failed write operation for retry on reconnect.
+   * Only queues POST/PUT/PATCH/DELETE — never retries GETs.
+   * @param {string} method - HTTP method.
+   * @param {string} path - API path.
+   * @param {object|null} body - Request body (will be JSON-stringified).
+   * @param {number} [maxRetries=3] - Maximum retry attempts.
+   */
+  queueForRetry(method, path, body = null, maxRetries = 3) {
+    if (method === 'GET') return; // Never retry reads.
+    if (this._retryQueue.length >= 50) {
+      // Cap queue size to prevent memory issues.
+      this._logError('warn', method, path, null, 'Retry queue full, dropping operation');
+      return;
+    }
+    this._retryQueue.push({
+      method,
+      path,
+      body: body ? JSON.stringify(body) : null,
+      retries: 0,
+      maxRetries,
+    });
+    console.log(`Chronicle: Queued ${method} ${path} for retry (${this._retryQueue.length} pending)`);
+  }
+
+  /**
+   * Process the retry queue. Called after reconnection.
+   * @returns {Promise<{success: number, failed: number}>}
+   */
+  async processRetryQueue() {
+    if (this._retryProcessing || this._retryQueue.length === 0) {
+      return { success: 0, failed: 0 };
+    }
+
+    this._retryProcessing = true;
+    let success = 0;
+    let failed = 0;
+
+    // Process a snapshot of the queue.
+    const pending = [...this._retryQueue];
+    this._retryQueue = [];
+
+    for (const item of pending) {
+      try {
+        await this.fetch(item.path, {
+          method: item.method,
+          body: item.body,
+        });
+        success++;
+      } catch (err) {
+        item.retries++;
+        if (item.retries < item.maxRetries) {
+          this._retryQueue.push(item);
+          console.warn(`Chronicle: Retry ${item.retries}/${item.maxRetries} failed for ${item.method} ${item.path}`);
+        } else {
+          failed++;
+          this._logError('error', item.method, item.path, null,
+            `Permanently failed after ${item.maxRetries} retries: ${err.message}`);
+        }
+      }
+    }
+
+    this._retryProcessing = false;
+
+    if (success > 0 || failed > 0) {
+      console.log(`Chronicle: Retry queue processed — ${success} succeeded, ${failed} permanently failed, ${this._retryQueue.length} remaining`);
+    }
+
+    return { success, failed };
+  }
+
+  /**
+   * Get the number of pending retry operations.
+   * @returns {number}
+   */
+  getRetryQueueSize() {
+    return this._retryQueue.length;
+  }
+
+  // --- Health & error log (F-QoL) ---
+
+  /**
+   * Log a REST API error for dashboard display.
+   * @param {string} level - 'error' or 'warn'.
+   * @param {string} method - HTTP method.
+   * @param {string} path - API path.
+   * @param {number|null} status - HTTP status code.
+   * @param {string} message - Error message.
+   * @private
+   */
+  _logError(level, method, path, status, message) {
+    this._errorLog.unshift({
+      time: Date.now(),
+      timeFormatted: new Date().toLocaleTimeString(),
+      level,
+      method,
+      path,
+      status,
+      message: message.substring(0, 200), // Truncate long error bodies.
+    });
+    if (this._errorLog.length > this._maxErrorLogEntries) {
+      this._errorLog.length = this._maxErrorLogEntries;
+    }
+  }
+
+  /**
+   * Get the error log entries for dashboard display.
+   * @returns {Array<{time: number, level: string, method: string, path: string, status: number|null, message: string}>}
+   */
+  getErrorLog() {
+    return this._errorLog;
+  }
+
+  /**
+   * Clear the error log.
+   */
+  clearErrorLog() {
+    this._errorLog = [];
+  }
+
+  /**
+   * Get connection uptime percentage for the current session.
+   * @returns {number} 0-100 percentage.
+   */
+  getUptimePercent() {
+    const sessionStart = this.health.totalConnectedMs;
+    let connectedMs = sessionStart;
+
+    if (this.health.connectedSince) {
+      connectedMs += Date.now() - this.health.connectedSince;
+    }
+
+    // Approximate session duration from first success or first error.
+    const firstActivity = Math.min(
+      this.health.lastRestSuccess || Date.now(),
+      this.health.lastRestError || Date.now(),
+      this.health.connectedSince || Date.now()
+    );
+    const sessionDuration = Date.now() - firstActivity;
+
+    if (sessionDuration <= 0) return 100;
+    return Math.min(100, Math.round((connectedMs / sessionDuration) * 100));
+  }
+
   // --- WebSocket ---
 
   /**
@@ -181,6 +383,11 @@ export class ChronicleAPI {
     this._shouldConnect = false;
     this._clearReconnect();
     if (this._ws) {
+      // Track connected time before disconnecting.
+      if (this.health.connectedSince) {
+        this.health.totalConnectedMs += Date.now() - this.health.connectedSince;
+        this.health.connectedSince = null;
+      }
       this._ws.close(1000, 'Client disconnect');
       this._ws = null;
     }
@@ -243,28 +450,45 @@ export class ChronicleAPI {
       this._ws = new WebSocket(wsUrl);
     } catch (err) {
       console.error('Chronicle: WebSocket creation failed', err);
+      this._logError('error', 'WS', '/ws', null, err.message || 'WebSocket creation failed');
       this._scheduleReconnect();
       return;
     }
 
-    this._ws.onopen = () => {
+    this._ws.onopen = async () => {
       console.log('Chronicle: WebSocket connected');
       this._setState('connected');
       this._reconnectDelay = 1000; // Reset backoff.
+      this.health.connectedSince = Date.now();
 
       // Flush queued messages.
       while (this._messageQueue.length > 0) {
         const msg = this._messageQueue.shift();
         this._ws.send(JSON.stringify(msg));
       }
 
+      // Process retry queue on reconnect.
+      if (this._retryQueue.length > 0) {
+        const result = await this.processRetryQueue();
+        if (result.success > 0 || result.failed > 0) {
+          this._emit('sync.retryComplete', { payload: result });
+        }
+      }
+
       // Notify listeners.
       this._emit('sync.status', { status: 'connected' });
     };
 
     this._ws.onclose = (event) => {
       console.log(`Chronicle: WebSocket closed (code=${event.code})`);
       this._ws = null;
+
+      // Track connected time.
+      if (this.health.connectedSince) {
+        this.health.totalConnectedMs += Date.now() - this.health.connectedSince;
+        this.health.connectedSince = null;
+      }
+
       this._setState('disconnected');
 
       if (this._shouldConnect && event.code !== 1000) {
@@ -274,6 +498,7 @@ export class ChronicleAPI {
 
     this._ws.onerror = (error) => {
       console.error('Chronicle: WebSocket error', error);
+      this._logError('error', 'WS', '/ws', null, 'WebSocket connection error');
       // onclose will fire after onerror, triggering reconnect.
     };
 
@@ -294,9 +519,10 @@ export class ChronicleAPI {
   _scheduleReconnect() {
     this._clearReconnect();
     this._setState('reconnecting');
+    this.health.reconnectAttempts++;
 
     const delay = Math.min(this._reconnectDelay, 30000); // Cap at 30s.
-    console.log(`Chronicle: Reconnecting in ${delay}ms`);
+    console.log(`Chronicle: Reconnecting in ${delay}ms (attempt ${this.health.reconnectAttempts})`);
 
     this._reconnectTimer = setTimeout(() => {
       this._reconnectTimer = null;