feat(admin): profile freshness panel in data-quality (#81 phase B.4)

Adds a per-feature freshness summary to /admin/data-quality so the admin
can spot features that are systematically stale or never computed:

  totalEligible — distinct users with tip_views in the last 30 days
  missing       — eligible users with no row stored for the feature
  stale         — eligible users whose stored row is past its TTL

Backend exposes summarizeProfileFreshness() in profile/builder.ts; one
query per feature joins eligible users LEFT JOIN profile rows.
Coverage = (eligible − missing − stale) / eligible, colored
green/yellow/red via the new PctGood helper (high-is-good, opposite of
the existing Pct used for missing-feature/stale-token rates).

Refs #81.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

services/api/src/profile/builder.ts

@@ -120,6 +120,58 @@ export interface ProfileFeatureView {
   description: string;
 }
 
+export interface FeatureFreshnessSummary {
+  feature: string;
+  ttlSec: number;
+  /** Distinct users with tip activity in the last 30 days. */
+  totalEligible: number;
+  /** Eligible users with no row stored at all for this feature. */
+  missing: number;
+  /** Eligible users whose stored row is past its TTL. */
+  stale: number;
+}
+
+/**
+ * Per-feature staleness summary across all eligible users (anyone with a tip
+ * served in the last 30 days). Used by `/admin/data-quality` so the admin can
+ * spot features that are systematically stale or never computed.
+ *
+ * Hand-written SQL because this joins (eligible_users LEFT JOIN profile_rows)
+ * with conditional aggregations — drizzle's query builder is more pain than
+ * value here, and the column allowlist is the registry.
+ */
+export function summarizeProfileFreshness(): FeatureFreshnessSummary[] {
+  return FEATURES.map((f) => {
+    const row = rawSqlite
+      .prepare(`
+        WITH eligible AS (
+          SELECT DISTINCT user_id
+          FROM tip_views
+          WHERE served_at >= datetime('now', '-30 days')
+        )
+        SELECT
+          COUNT(*) AS total_eligible,
+          SUM(CASE WHEN upf.user_id IS NULL THEN 1 ELSE 0 END) AS missing,
+          SUM(CASE WHEN upf.user_id IS NOT NULL
+                    AND upf.ttl_sec > 0
+                    AND (julianday('now') - julianday(upf.updated_at)) * 86400.0 > upf.ttl_sec
+                   THEN 1 ELSE 0 END) AS stale
+        FROM eligible e
+        LEFT JOIN user_profile_features upf
+          ON upf.user_id = e.user_id AND upf.name = ?
+      `)
+      .get(f.name) as { total_eligible: number; missing: number; stale: number } | undefined;
+
+    return {
+      feature: f.name,
+      ttlSec: f.ttlSec,
+      totalEligible: Number(row?.total_eligible ?? 0),
+      missing: Number(row?.missing ?? 0),
+      stale: Number(row?.stale ?? 0),
+    };
+  });
+}
+
 /**
  * Inspection helper for the admin UI: returns one row per registered feature,
  * joining stored value + metadata. No compute — surface staleness; rebuild is

services/api/src/routes/__tests__/admin.test.ts

@@ -8,7 +8,7 @@ import { describe, it, expect, vi, beforeAll } from 'vitest';
 import express from 'express';
 import * as http from 'http';
 import { makeTestDb } from '../../test/db.js';
-import { users, integrationTokens, tipViews, tipFeedback, tipScores } from '../../db/schema.js';
+import { users, integrationTokens, tipViews, tipFeedback, tipScores, userProfileFeatures } from '../../db/schema.js';
 
 // ---- in-memory DB ----
 const testDb = makeTestDb();
@@ -422,6 +422,56 @@ describe('GET /api/admin/users/:id — edge cases', () => {
   });
 });
 
+describe('GET /api/admin/data-quality — #81 phase B.4 profile freshness', () => {
+  type Body = {
+    profileFreshness: Array<{
+      feature: string;
+      ttlSec: number;
+      totalEligible: number;
+      missing: number;
+      stale: number;
+    }>;
+  };
+
+  it('reports each registered feature once', async () => {
+    const { server, call } = await startServer(buildApp());
+    try {
+      const { status, body } = await call('GET', '/api/admin/data-quality');
+      expect(status).toBe(200);
+      const b = body as Body;
+      const names = b.profileFreshness.map((r) => r.feature).sort();
+      expect(names).toEqual([
+        'completion_rate_30d',
+        'dismiss_rate_30d',
+        'mean_dwell_ms_30d',
+        'preferred_hour',
+        'tip_volume_30d',
+      ]);
+    } finally {
+      server.close();
+    }
+  });
+
+  it('counts eligible users (with tip_views in 30d) and flags missing rows', async () => {
+    // Reset profile rows so this test is independent of any previous rebuild test
+    // that may have populated rows for some users.
+    await testDb.delete(userProfileFeatures);
+    const { server, call } = await startServer(buildApp());
+    try {
+      const { body } = await call('GET', '/api/admin/data-quality');
+      const b = body as Body;
+      // Seed has tip_views for user-1 and user-2 within 30d → 2 eligible.
+      const completion = b.profileFreshness.find((r) => r.feature === 'completion_rate_30d')!;
+      expect(completion.totalEligible).toBe(2);
+      // No profile rows seeded → both missing
+      expect(completion.missing).toBe(2);
+      expect(completion.stale).toBe(0);
+    } finally {
+      server.close();
+    }
+  });
+});
+
 describe('GET /api/admin/reward-analytics — #92 quality breakdowns', () => {
   type Row = {
     key: string | null;

services/api/src/routes/admin.ts

@@ -18,7 +18,7 @@ import { nanoid } from 'nanoid';
 import { bus } from '../events/bus.js';
 import { config } from '../config.js';
 import { getShadowPolicies, setPolicyActive } from './recommender.js';
-import { inspectProfile, rebuildProfile } from '../profile/builder.js';
+import { inspectProfile, rebuildProfile, summarizeProfileFreshness } from '../profile/builder.js';
 import { spawn } from 'child_process';
 import { existsSync, readFileSync, unlinkSync } from 'fs';
 import { resolve, dirname } from 'path';
@@ -514,6 +514,7 @@ router.get('/data-quality', async (req: AuthenticatedRequest, res: Response) =>
     totalTokens,
     staleTokens,
     dailyQuality,
+    profileFreshness: summarizeProfileFreshness(),
   });
 });