@bongos/core 1.19.316 → 1.19.318

package/modules/lifecycle/db-analytics.js

@@ -0,0 +1,719 @@
+// modules/lifecycle/db-analytics.js — estimation drift, grade aggregates, builder/ecosystem analytics, merge lease + peer-vote karma.
+//
+// Carved out of modules/lifecycle/db.js by task 1003204 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original db.js lines 4916-5598 unchanged. db.js remains the facade that
+// re-exports every name, so every existing db call site is unchanged.
+//
+// THE BOUNDARY (ADR 0093 §1): this file reaches core ONLY through the published
+// doorway ../../src/module-api.js — never a core internal, never a sibling module.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { pool, withTx } = api;
+const { SMOKE_NOT_LIKE, gradePassCount, gradeQualityWhere, median } = require('./db-shared.js');
+const { CREDITS_AWARDED_SUBQUERY } = require('./db-tasks.js');
+
+// -------------------------------------------------------------------------
+// Cost log + summary carved into modules/economy/cost.js (BV1.R77 / ADR 0093
+// §§1-2): logCost (the one cost_log writer), reconcileSessionCosts,
+// costSummary, and costCalibrationSummary left this monolith. routes/cost.js
+// + the reconciler + the public dashboard resolve them via the `reward` kernel
+// port. (The DAY_SERIES_CTE constant they shared moved with them.)
+// -------------------------------------------------------------------------
+
+// -------------------------------------------------------------------------
+// Recent shipped tasks (for status page feed)
+// -------------------------------------------------------------------------
+
+// GDS #191: optional `days` (positive integer) restricts to rows shipped within
+// the trailing N days. `null` / `undefined` / `0` means no date filter (all time).
+// Limit is still applied either way so the status page never pulls an unbounded
+// payload. Default keeps the historical 30-row "recent" feel for callers that
+// don't pass options.
+
+async function recentShippedTasks(limit = 30, { days = null } = {}) {
+  const params = [limit];
+  let whereClause = `t.status = 'shipped'
+        AND ${SMOKE_NOT_LIKE}`;
+  if (days && Number.isFinite(days) && days > 0) {
+    params.push(days);
+    whereClause += `\n        AND t.shipped_at > now() - ($${params.length}::int * interval '1 day')`;
+  }
+  const { rows } = await pool.query(
+    `SELECT t.id, t.title, t.value_summary, t.version_id, t.status, t.shipped_at, t.credits_reward,
+            ${CREDITS_AWARDED_SUBQUERY} AS credits_awarded,
+            t.est_minutes, t.actual_minutes,
+            b.github_login, b.display_name
+       FROM tasks t
+       LEFT JOIN builders b ON b.id = t.shipped_by
+      WHERE ${whereClause}
+      ORDER BY t.shipped_at DESC NULLS LAST
+      LIMIT $1`,
+    params
+  );
+  return rows;
+}
+
+// Rolling median of actual/est ratio for a builder's last N shipped tasks.
+// Returns null if there is insufficient data.
+
+async function getEstVsActualRatio(builderId, limit = 10) {
+  const { rows } = await pool.query(
+    `SELECT actual_minutes::float / est_minutes AS ratio
+       FROM tasks
+      WHERE shipped_by = $1
+        AND status = 'shipped'
+        AND actual_minutes IS NOT NULL
+        AND est_minutes IS NOT NULL
+        AND est_minutes > 0
+      ORDER BY shipped_at DESC NULLS LAST
+      LIMIT $2`,
+    [builderId, limit]
+  );
+  if (rows.length === 0) return null;
+  const ratios = rows.map((r) => Number(r.ratio));
+  const med = median(ratios);
+  return { median: Math.round(med * 100) / 100, sample_size: ratios.length };
+}
+
+// Aggregated estimation drift for the public status page.
+// Returns overall median ratio + per-version breakdown.
+
+async function estimationDriftSummary() {
+  const { rows } = await pool.query(
+    `SELECT version_id,
+            actual_minutes::float / est_minutes AS ratio
+       FROM tasks
+      WHERE status = 'shipped'
+        AND actual_minutes IS NOT NULL
+        AND est_minutes IS NOT NULL
+        AND est_minutes > 0
+        AND ${SMOKE_NOT_LIKE}
+      ORDER BY shipped_at DESC NULLS LAST`
+  );
+
+  if (rows.length === 0) {
+    return { overall_median: null, sample_size: 0, by_version: [] };
+  }
+
+  const allRatios = rows.map((r) => Number(r.ratio));
+  const overallMedian = Math.round(median(allRatios) * 100) / 100;
+
+  const byVersion = new Map();
+  for (const r of rows) {
+    if (!byVersion.has(r.version_id)) byVersion.set(r.version_id, []);
+    byVersion.get(r.version_id).push(Number(r.ratio));
+  }
+
+  const versionBreakdown = Array.from(byVersion.entries()).map(([version_id, ratios]) => ({
+    version_id,
+    median_ratio: Math.round(median(ratios) * 100) / 100,
+    task_count: ratios.length,
+  }));
+
+  return {
+    overall_median: overallMedian,
+    sample_size: allRatios.length,
+    by_version: versionBreakdown,
+  };
+}
+
+
+async function recentShippedTasksByBuilder(builderId, limit = 10) {
+  const { rows } = await pool.query(
+    `SELECT t.id, t.title, t.value_summary, t.version_id, t.status, t.shipped_at, t.credits_reward,
+            ${CREDITS_AWARDED_SUBQUERY} AS credits_awarded
+       FROM tasks t
+      WHERE t.shipped_by = $1
+        AND t.status = 'shipped'
+        AND t.title NOT LIKE '\\_\\_smoke\\_\\_%' ESCAPE '\\'
+      ORDER BY t.shipped_at DESC NULLS LAST
+      LIMIT $2`,
+    [builderId, limit]
+  );
+  return rows;
+}
+
+// -------------------------------------------------------------------------
+// Achievement getters (listAchievements / getBuilderAchievements /
+// getLeaderboardWithAchievements / getLockedAchievementsProgress /
+// renderProgressText) carved into modules/economy/achievements.js (BV1.R77 /
+// ADR 0093 §§1-2). me.js + public.js resolve them via the `reward` kernel port.
+// -------------------------------------------------------------------------
+
+// -------------------------------------------------------------------------
+// Karma feed (V3.R28 / #248)
+// -------------------------------------------------------------------------
+
+// Last N karma_log entries for this builder, newest first. Powers the
+// proposer's karma feed — the "Done when: visible in the proposer's karma
+// feed" criterion for V3.R28. When R26 (#246) ships the profile-page karma
+// trend UI, the page reads from this helper. Lightweight join to builders
+// so the UI can render "granted by @<login>" without a second query.
+//
+// Append-only by construction (karma_log has no DELETE/UPDATE paths), so
+// this is safe to call freely.
+
+async function recentGradesForBuilder(builderId, limit = 5) {
+  // panel_outcome rides along so consumers can LABEL an outage row ("not
+  // graded") instead of rendering its placeholder 0.0 as a fail (task 1002652).
+  // A list read stays unfiltered — honesty here means labeling, not hiding.
+  const { rows } = await pool.query(
+    `SELECT g.task_id, g.score, g.passed, g.threshold, g.graded_at,
+            g.grader_kind, g.grader_version, g.rubric_scores,
+            g.signals->>'panel_outcome' AS panel_outcome,
+            COALESCE(g.signals->'issues', '[]'::jsonb) AS issues,
+            COALESCE((g.signals->>'confidence')::numeric, NULL) AS confidence,
+            t.title, t.kind, t.discipline
+       FROM task_grades g
+       JOIN tasks t ON t.id = g.task_id
+      WHERE t.shipped_by = $1
+      ORDER BY g.graded_at DESC
+      LIMIT $2`,
+    [builderId, limit]
+  );
+  return rows;
+}
+
+// Rolling 7d avg grade across ALL builders, plus pass-rate. Powers the
+// public status tile + leaderboard hover.
+
+async function rollingAvgGrade(days = 7) {
+  // Quality stats aggregate ONLY quality-graded rows; outage / null-axis rows
+  // are counted apart as n_unavailable (task 1002652 — 21 outage rows once
+  // read as a month of pass_rate 0.000).
+  const q = gradeQualityWhere();
+  const { rows } = await pool.query(
+    `SELECT
+       COUNT(*) FILTER (WHERE ${q})::int                         AS n,
+       COALESCE(AVG(score) FILTER (WHERE ${q}), 0)::numeric(3,1) AS avg_score,
+       ${gradePassCount('passed', { where: q })} AS n_passed,
+       COALESCE(MIN(score) FILTER (WHERE ${q}), 0)::numeric(3,1) AS min_score,
+       COALESCE(MAX(score) FILTER (WHERE ${q}), 0)::numeric(3,1) AS max_score,
+       COUNT(*) FILTER (WHERE NOT ${q})::int                     AS n_unavailable
+       FROM task_grades
+      WHERE graded_at >= now() - ($1 || ' days')::interval`,
+    [String(days)]
+  );
+  return rows[0] || { n: 0, avg_score: 0, n_passed: 0, min_score: 0, max_score: 0, n_unavailable: 0 };
+}
+
+// Per-builder rolling avg, last `days` days. Powers the /builders profile.
+
+async function gradeByBuilder(days = 30) {
+  // pass_rate is NULL (not 0.000) for a builder whose window holds only
+  // outage / null-axis rows — "no graded work", never a fabricated fail-streak
+  // (task 1002652). fmtPct-style consumers already render null as '—'.
+  const q = gradeQualityWhere('g');
+  const { rows } = await pool.query(
+    `SELECT
+       t.shipped_by                                             AS builder_id,
+       b.github_login,
+       b.display_name,
+       b.avatar_url,
+       COUNT(*) FILTER (WHERE ${q})::int                        AS n,
+       COALESCE(AVG(g.score) FILTER (WHERE ${q}), 0)::numeric(3,1) AS avg_score,
+       ${gradePassCount('g.passed', { where: q })} AS n_passed,
+       ROUND(AVG(CASE WHEN g.passed THEN 1 ELSE 0 END) FILTER (WHERE ${q}), 3) AS pass_rate,
+       COUNT(*) FILTER (WHERE NOT ${q})::int                    AS n_unavailable,
+       MAX(g.graded_at)                                         AS last_graded_at
+       FROM task_grades g
+       JOIN tasks t    ON t.id = g.task_id
+       LEFT JOIN builders b ON b.id = t.shipped_by
+      WHERE g.graded_at >= now() - ($1 || ' days')::interval
+        AND t.shipped_by IS NOT NULL
+      GROUP BY t.shipped_by, b.github_login, b.display_name, b.avatar_url
+      ORDER BY n DESC, avg_score DESC`,
+    [String(days)]
+  );
+  return rows;
+}
+
+// Public grade-trend timeline — array of { day, n, avg_score }. Powers a
+// chart on status.amazonprimea.com.
+
+async function gradeTrendByDay(days = 30) {
+  // A day whose rows are all outages keeps its row (n=0, avg_score NULL,
+  // n_unavailable>0) so a chart can show "grader down", never a 0.0-score day
+  // (task 1002652 — the 2026-07-12..19 zero-score week was five outage days).
+  const q = gradeQualityWhere();
+  const { rows } = await pool.query(
+    `SELECT
+       to_char(date_trunc('day', graded_at), 'YYYY-MM-DD') AS day,
+       COUNT(*) FILTER (WHERE ${q})::int AS n,
+       AVG(score) FILTER (WHERE ${q})::numeric(3,1) AS avg_score,
+       ${gradePassCount('passed', { where: q })} AS n_passed,
+       COUNT(*) FILTER (WHERE NOT ${q})::int AS n_unavailable
+       FROM task_grades
+      WHERE graded_at >= now() - ($1 || ' days')::interval
+      GROUP BY date_trunc('day', graded_at)
+      ORDER BY day ASC`,
+    [String(days)]
+  );
+  return rows;
+}
+
+// -------------------------------------------------------------------------
+// Builder analytics — the "AI dev curve" (V3.R72 / #291, criterion C5).
+//
+// Per-builder historical time-series powering the /builders profile analytics
+// panel and (aggregated, individuals stripped) the public /status ecosystem
+// tile. Everything derives from existing columns — tasks.shipped_at /
+// actual_minutes / est_minutes / kind, cost_log.builder_id (migration 046),
+// claims.outcome, and task_grades — so no migration is needed. Smoke tasks
+// (`__smoke__*`) are excluded everywhere, mirroring the other status feeds.
+// One round trip per series, fanned out with Promise.all.
+// (SMOKE_NOT_LIKE is now declared once at module top — task 1087, C3.)
+// -------------------------------------------------------------------------
+
+
+async function builderAnalytics(builderId, days = 90) {
+  const d = String(days);
+  const [shipRate, costTrend, durationTrend, gradeTrend, topKinds, headline, claimRollup] =
+    await Promise.all([
+      // Ships per day — the core "dev curve".
+      pool.query(
+        `SELECT to_char(date_trunc('day', shipped_at), 'YYYY-MM-DD') AS day,
+                COUNT(*)::int AS n
+           FROM tasks
+          WHERE shipped_by = $1 AND status = 'shipped'
+            AND shipped_at >= now() - ($2 || ' days')::interval
+            AND ${SMOKE_NOT_LIKE}
+          GROUP BY 1 ORDER BY 1 ASC`,
+        [builderId, d]
+      ),
+      // Cost per day + tasks touched that day → cost-per-task in JS.
+      pool.query(
+        `SELECT to_char(date_trunc('day', recorded_at), 'YYYY-MM-DD') AS day,
+                SUM(amount_usd)::numeric(12,2) AS total_usd,
+                COUNT(DISTINCT task_id)::int AS n_tasks
+           FROM cost_log
+          WHERE builder_id = $1
+            AND recorded_at >= now() - ($2 || ' days')::interval
+          GROUP BY 1 ORDER BY 1 ASC`,
+        [builderId, d]
+      ),
+      // Avg actual vs estimated minutes per day (the "getting faster" curve).
+      pool.query(
+        `SELECT to_char(date_trunc('day', shipped_at), 'YYYY-MM-DD') AS day,
+                ROUND(AVG(actual_minutes))::int AS avg_actual,
+                ROUND(AVG(est_minutes))::int AS avg_est
+           FROM tasks
+          WHERE shipped_by = $1 AND status = 'shipped'
+            AND actual_minutes IS NOT NULL AND est_minutes IS NOT NULL
+            AND shipped_at >= now() - ($2 || ' days')::interval
+            AND ${SMOKE_NOT_LIKE}
+          GROUP BY 1 ORDER BY 1 ASC`,
+        [builderId, d]
+      ),
+      // Grade pass-rate per day (quality holding up as throughput rises?).
+      // Quality-graded rows only — outage / null-axis rows would read as
+      // fail-days (task 1002652); headline.grade_pass_rate derives from these
+      // rows so it inherits the same honesty.
+      pool.query(
+        `SELECT to_char(date_trunc('day', g.graded_at), 'YYYY-MM-DD') AS day,
+                COUNT(*) FILTER (WHERE ${gradeQualityWhere('g')})::int AS n,
+                ${gradePassCount('g.passed', { where: gradeQualityWhere('g') })} AS n_passed,
+                AVG(g.score) FILTER (WHERE ${gradeQualityWhere('g')})::numeric(3,1) AS avg_score
+           FROM task_grades g
+           JOIN tasks t ON t.id = g.task_id
+          WHERE t.shipped_by = $1
+            AND g.graded_at >= now() - ($2 || ' days')::interval
+          GROUP BY 1 ORDER BY 1 ASC`,
+        [builderId, d]
+      ),
+      // Top kinds shipped (all-time — a "what do I build" fingerprint).
+      pool.query(
+        `SELECT COALESCE(kind, 'unspecified') AS kind, COUNT(*)::int AS n
+           FROM tasks
+          WHERE shipped_by = $1 AND status = 'shipped'
+            AND ${SMOKE_NOT_LIKE}
+          GROUP BY 1 ORDER BY n DESC, kind ASC`,
+        [builderId]
+      ),
+      // Window headline numbers.
+      pool.query(
+        `SELECT COUNT(*) FILTER (WHERE status = 'shipped')::int AS total_shipped,
+                COALESCE(SUM(actual_minutes) FILTER (
+                  WHERE status = 'shipped' AND actual_minutes IS NOT NULL), 0)::int AS total_minutes,
+                COALESCE(ROUND(AVG(actual_minutes) FILTER (
+                  WHERE status = 'shipped' AND actual_minutes IS NOT NULL)), 0)::int AS avg_duration_min
+           FROM tasks
+          WHERE shipped_by = $1
+            AND ${SMOKE_NOT_LIKE}
+            AND (shipped_at IS NULL OR shipped_at >= now() - ($2 || ' days')::interval)`,
+        [builderId, d]
+      ),
+      // Confirmation rate — share of resolved claims that ended in a ship
+      // (vs. abandoned / expired / partial). Distinct from the grade pass-rate.
+      pool.query(
+        `SELECT COUNT(*)::int AS resolved_claims,
+                SUM(CASE WHEN outcome = 'shipped' THEN 1 ELSE 0 END)::int AS shipped_claims
+           FROM claims
+          WHERE builder_id = $1 AND outcome IS NOT NULL
+            AND claimed_at >= now() - ($2 || ' days')::interval`,
+        [builderId, d]
+      ),
+    ]);
+
+  // task 1503: the "Cost / work ($)" chart plots per-day cost-per-work. The old
+  // per_task = day's cost / COUNT(DISTINCT cost_log.task_id) flat-lined at 0 —
+  // most cost rows carry a NULL task_id (session-token / infra / api spend), so
+  // the DISTINCT count was 0 for those days and per_task fell to 0; on the rare
+  // task-attributed day it spiked wildly. Cost (recorded_at) and works
+  // (shipped_at) don't align by day, so a same-day ratio can't be meaningful.
+  // Instead expose the CUMULATIVE cost-per-work as of each day — running total
+  // spend / running works shipped — which is always defined once there's a ship
+  // and converges to headline.cost_per_task.
+  const shipsByDay = new Map(shipRate.rows.map((r) => [r.day, Number(r.n) || 0]));
+  const costByDay = new Map(costTrend.rows.map((r) => [r.day, Number(r.total_usd) || 0]));
+  const curveDays = Array.from(new Set([
+    ...costTrend.rows.map((r) => r.day),
+    ...shipRate.rows.map((r) => r.day),
+  ])).sort();
+  let cumCost = 0;
+  let cumShips = 0;
+  const perWorkByDay = new Map();
+  for (const day of curveDays) {
+    cumCost += costByDay.get(day) || 0;
+    cumShips += shipsByDay.get(day) || 0;
+    perWorkByDay.set(day, cumShips > 0 ? Math.round((cumCost / cumShips) * 100) / 100 : 0);
+  }
+  const cost_trend = costTrend.rows.map((r) => ({
+    day: r.day,
+    total_usd: Number(r.total_usd),
+    n_tasks: r.n_tasks,
+    // Cumulative cost-per-work as of this day (see note above). Converges to
+    // headline.cost_per_task; never the old all-zero flat line.
+    per_work: perWorkByDay.get(r.day) ?? 0,
+  }));
+  const totalCost = cost_trend.reduce((s, r) => s + r.total_usd, 0);
+
+  const h = headline.rows[0] || { total_shipped: 0, total_minutes: 0, avg_duration_min: 0 };
+  const c = claimRollup.rows[0] || { resolved_claims: 0, shipped_claims: 0 };
+  const grades = gradeTrend.rows;
+  const gradedN = grades.reduce((s, r) => s + r.n, 0);
+  const gradedPassed = grades.reduce((s, r) => s + r.n_passed, 0);
+
+  return {
+    window_days: days,
+    ship_rate: shipRate.rows, // [{ day, n }]
+    cost_trend, // [{ day, total_usd, n_tasks, per_work }] — per_work is cumulative (task 1503)
+    duration_trend: durationTrend.rows, // [{ day, avg_actual, avg_est }]
+    grade_trend: grades, // [{ day, n, n_passed, avg_score }]
+    top_kinds: topKinds.rows, // [{ kind, n }]
+    headline: {
+      total_shipped: h.total_shipped,
+      total_cost_usd: Math.round(totalCost * 100) / 100,
+      cost_per_task: h.total_shipped > 0 ? Math.round((totalCost / h.total_shipped) * 100) / 100 : 0,
+      avg_duration_min: h.avg_duration_min,
+      confirmation_rate: c.resolved_claims > 0 ? Math.round((c.shipped_claims / c.resolved_claims) * 100) / 100 : null,
+      resolved_claims: c.resolved_claims,
+      grade_pass_rate: gradedN > 0 ? Math.round((gradedPassed / gradedN) * 100) / 100 : null,
+      graded_n: gradedN,
+    },
+  };
+}
+
+// Ecosystem-wide aggregate — the SAME shape of series as builderAnalytics but
+// summed across every builder, with NO per-builder identity. This is the only
+// analytics surface the public /status page is allowed to render (individuals
+// stay behind the authenticated /analytics/builder/:id route). Grade + cost
+// daily series already have public feeds (/public/grades, /public/cost-summary),
+// so this adds just the ship-rate, duration, top-kinds, and headline aggregates.
+
+async function ecosystemAnalytics(days = 90) {
+  const d = String(days);
+  const [shipRate, durationTrend, topKinds, headline] = await Promise.all([
+    pool.query(
+      `SELECT to_char(date_trunc('day', shipped_at), 'YYYY-MM-DD') AS day,
+              COUNT(*)::int AS n
+         FROM tasks
+        WHERE status = 'shipped' AND shipped_by IS NOT NULL
+          AND shipped_at >= now() - ($1 || ' days')::interval
+          AND ${SMOKE_NOT_LIKE}
+        GROUP BY 1 ORDER BY 1 ASC`,
+      [d]
+    ),
+    pool.query(
+      `SELECT to_char(date_trunc('day', shipped_at), 'YYYY-MM-DD') AS day,
+              ROUND(AVG(actual_minutes))::int AS avg_actual,
+              ROUND(AVG(est_minutes))::int AS avg_est
+         FROM tasks
+        WHERE status = 'shipped'
+          AND actual_minutes IS NOT NULL AND est_minutes IS NOT NULL
+          AND shipped_at >= now() - ($1 || ' days')::interval
+          AND ${SMOKE_NOT_LIKE}
+        GROUP BY 1 ORDER BY 1 ASC`,
+      [d]
+    ),
+    pool.query(
+      `SELECT COALESCE(kind, 'unspecified') AS kind, COUNT(*)::int AS n
+         FROM tasks
+        WHERE status = 'shipped' AND shipped_by IS NOT NULL
+          AND shipped_at >= now() - ($1 || ' days')::interval
+          AND ${SMOKE_NOT_LIKE}
+        GROUP BY 1 ORDER BY n DESC, kind ASC`,
+      [d]
+    ),
+    pool.query(
+      `SELECT COUNT(*)::int AS total_shipped,
+              COUNT(DISTINCT shipped_by)::int AS active_builders,
+              COALESCE(ROUND(AVG(actual_minutes) FILTER (
+                WHERE actual_minutes IS NOT NULL)), 0)::int AS avg_duration_min
+         FROM tasks
+        WHERE status = 'shipped' AND shipped_by IS NOT NULL
+          AND shipped_at >= now() - ($1 || ' days')::interval
+          AND ${SMOKE_NOT_LIKE}`,
+      [d]
+    ),
+  ]);
+
+  const h = headline.rows[0] || { total_shipped: 0, active_builders: 0, avg_duration_min: 0 };
+  return {
+    window_days: days,
+    ship_rate: shipRate.rows,
+    duration_trend: durationTrend.rows,
+    top_kinds: topKinds.rows,
+    headline: {
+      total_shipped: h.total_shipped,
+      active_builders: h.active_builders,
+      avg_duration_min: h.avg_duration_min,
+    },
+  };
+}
+
+// -------------------------------------------------------------------------
+// audit_log (V3.R35 / #256) — append-only stream of authenticated writes.
+//
+// The writing middleware (src/bongos/middleware/audit.js) calls insertAuditLog
+// AFTER the response has been sent, wrapped in try/catch — so the request
+// path never blocks on this insert and a DB failure here can never break a
+// real user request. The reader is the archon-only GET /api/gds/audit-log
+// endpoint backed by listAuditLog below (paginated, newest-first).
+// -------------------------------------------------------------------------
+
+// insertAuditLog — the append-only audit write — moved to ./db-kernel (BV1.R69 /
+// ADR 0091 §2: audit is a kernel primitive). Imported + re-exported at the top
+// of this file; the writing middleware + the listAuditLog reader below unchanged.
+
+// listAuditLog — paginated, newest-first. Clamps limit to 1..500 and offset to
+// >= 0 at the route layer; this helper trusts its inputs.
+//
+// Optional filters:
+//   builderId — only entries for that builder
+//   method    — one of POST/PATCH/PUT/DELETE
+//   surface   — originating surface (e.g. 'discord_bot'); the literal string
+//               'none' selects direct human writes (surface IS NULL). This is
+//               what makes the documented forensic isolation of bot-origin
+//               writes actually queryable through the API, not just via psql
+//               (ADR 0033 §1 / F4 finding).
+
+async function logGradeAttempt({ taskId, builderId, passed, score }, queryFn) {
+  const q = queryFn || ((text, params) => pool.query(text, params));
+  try {
+    await q(
+      `INSERT INTO grade_attempts (task_id, builder_id, passed, score) VALUES ($1, $2, $3, $4)`,
+      [
+        Number(taskId),
+        builderId == null ? null : Number(builderId),
+        passed === true,
+        score == null ? null : Number(score),
+      ]
+    );
+    return true;
+  } catch (err) {
+    console.error('[gds] logGradeAttempt (non-blocking):', err && err.message ? err.message : err);
+    return false;
+  }
+}
+
+// countGradeAttempts — how many times a task has been graded (re-grade thrash).
+
+async function countGradeAttempts(taskId, queryFn) {
+  const q = queryFn || ((text, params) => pool.query(text, params));
+  const { rows } = await q(`SELECT COUNT(*)::int AS n FROM grade_attempts WHERE task_id = $1`, [Number(taskId)]);
+  return rows[0] ? rows[0].n : 0;
+}
+
+// gradeAttemptStats — the grade_attempts READER (task 1002661). The table has
+// been written on every grade since 6D.6 and read by nothing, leaving
+// remediation rate structurally unmeasurable. Windowed per-task rollup:
+// remediation_rate = of the tasks that FAILED at least one attempt, the share
+// whose latest attempt passed (null when no task failed — no denominator).
+// waived_zero_issue_passes counts the ADR 0164 implausible_pass_waived audit
+// markers in the same window, so the views can tell "waived on panel
+// evidence" from "never evaluated" at a glance.
+async function gradeAttemptStats(days = 7, queryFn) {
+  const q = queryFn || ((text, params) => pool.query(text, params));
+  const d = Number.isFinite(Number(days)) && Number(days) > 0 ? Math.min(Number(days), 90) : 7;
+  const [{ rows }, waived] = await Promise.all([q(
+    `SELECT
+        COALESCE(SUM(n), 0)::int                              AS total_attempts,
+        COUNT(*)::int                                         AS graded_tasks,
+        COUNT(*) FILTER (WHERE n > 1)::int                    AS retried_tasks,
+        COUNT(*) FILTER (WHERE had_fail)::int                 AS tasks_with_fail,
+        COUNT(*) FILTER (WHERE had_fail AND last_passed)::int AS remediated_tasks
+       FROM (
+         SELECT task_id,
+                COUNT(*) AS n,
+                BOOL_OR(NOT passed) AS had_fail,
+                (ARRAY_AGG(passed ORDER BY attempted_at DESC))[1] AS last_passed
+           FROM grade_attempts
+          WHERE attempted_at > now() - ($1 * interval '1 day')
+          GROUP BY task_id
+       ) t`,
+    [d]
+  ), q(
+    `SELECT COUNT(*)::int AS n
+       FROM task_grades
+      WHERE graded_at > now() - ($1 * interval '1 day')
+        AND signals->'server_guard'->>'implausible_pass_waived' IS NOT NULL`,
+    [d]
+  )]);
+  const s = rows[0] || {};
+  const tasksWithFail = Number(s.tasks_with_fail) || 0;
+  const remediated = Number(s.remediated_tasks) || 0;
+  return {
+    window_days: d,
+    total_attempts: Number(s.total_attempts) || 0,
+    graded_tasks: Number(s.graded_tasks) || 0,
+    retried_tasks: Number(s.retried_tasks) || 0,
+    tasks_with_fail: tasksWithFail,
+    remediated_tasks: remediated,
+    remediation_rate: tasksWithFail > 0 ? Math.round((remediated / tasksWithFail) * 100) / 100 : null,
+    waived_zero_issue_passes: (waived.rows[0] && Number(waived.rows[0].n)) || 0,
+  };
+}
+
+// ---- security_docs: Archon-only sensitive security documents (task 991) -----
+//
+// The DATED security engagement reports (exploit detail) live in the DB, NOT in
+// the git clone (threat-model §6.3 / ADR 0020). The route layer gates every read
+// to requireRank('archon'); these helpers are pure parameterized SQL.
+
+// Upsert a doc by slug — insert if new, update title/content (and bump
+// updated_at) if the slug already exists. Returns the full row.
+
+async function acquireMergeLease({ key = 'main', holder, ttlSeconds = 600 } = {}) {
+  if (!holder) throw new Error('acquireMergeLease: holder is required');
+  const { rows } = await pool.query(
+    `INSERT INTO merge_lease (key, holder, acquired_at, expires_at)
+          VALUES ($1, $2, now(), now() + make_interval(secs => $3))
+     ON CONFLICT (key) DO UPDATE
+          SET holder = EXCLUDED.holder, acquired_at = now(), expires_at = EXCLUDED.expires_at
+        WHERE merge_lease.expires_at <= now() OR merge_lease.holder = EXCLUDED.holder
+     RETURNING holder, expires_at`,
+    [key, holder, ttlSeconds]
+  );
+  if (rows.length) return { acquired: true, holder, expires_at: rows[0].expires_at };
+  const cur = await pool.query('SELECT holder, expires_at FROM merge_lease WHERE key = $1', [key]);
+  return { acquired: false, holder: cur.rows[0]?.holder ?? null, expires_at: cur.rows[0]?.expires_at ?? null };
+}
+
+// Release the lease IFF still held by this holder (defensive against releasing a lease that was
+// already reclaimed + re-acquired by someone else after a TTL expiry). Returns { released }.
+
+async function releaseMergeLease({ key = 'main', holder } = {}) {
+  if (!holder) throw new Error('releaseMergeLease: holder is required');
+  const { rowCount } = await pool.query(
+    'DELETE FROM merge_lease WHERE key = $1 AND holder = $2',
+    [key, holder]
+  );
+  return { released: rowCount > 0 };
+}
+
+// Current lease holder + expiry (null if free). Read-only; safe on the request path.
+
+async function mergeLeaseStatus({ key = 'main' } = {}) {
+  const { rows } = await pool.query(
+    `SELECT key, holder, acquired_at, expires_at, (expires_at <= now()) AS expired
+       FROM merge_lease WHERE key = $1`,
+    [key]
+  );
+  return rows[0] ?? null;
+}
+
+// Peer-vote → karma fold-in (V3.R25 / #245). The exact transaction that
+// POST /tasks/peer-votes/tally runs, extracted so the route AND the
+// server-internal weekly timer (the carved autonomy module's poller,
+// modules/autonomy/pollers/routine-timers.js — it reaches this via the doorway
+// `api.tallyPeerVotes`, BV1.R83 / ADR 0078 amendment) share ONE code path and
+// can never diverge on tally semantics. Idempotent:
+// only folds matured (>= lag days), not-yet-tallied votes, then stamps them
+// tallied_at = now() — a re-run within the week finds nothing new. Writes
+// karma_log with granted_by = NULL (a system fold-in has no requester); the
+// route's Archon gate is an HTTP-auth concern, not a property of this SQL. The
+// `FOR UPDATE OF pv` row lock is the real multi-instance guard: two processes
+// (e.g. the timer + a manual run, or a second instance on the same DB) can't
+// double-fold the same votes — the loser blocks, then sees tallied_at set.
+
+const PEER_VOTE_KARMA_LAG_DAYS = 7;
+
+
+async function tallyPeerVotes() {
+  return withTx(async (client) => {
+    const { rows: matured } = await client.query(
+      `SELECT pv.id, t.shipped_by AS builder_id, pv.vote
+         FROM peer_votes pv
+         JOIN tasks t ON t.id = pv.target_task_id
+        WHERE pv.tallied_at IS NULL
+          AND pv.recorded_at <= now() - ($1::int * interval '1 day')
+          AND t.shipped_by IS NOT NULL
+        FOR UPDATE OF pv`,
+      [PEER_VOTE_KARMA_LAG_DAYS]
+    );
+    const netByBuilder = new Map();
+    const voteIds = [];
+    for (const r of matured) {
+      voteIds.push(r.id);
+      netByBuilder.set(r.builder_id, (netByBuilder.get(r.builder_id) || 0) + r.vote);
+    }
+    const karmaRows = [];
+    for (const [builderId, net] of netByBuilder) {
+      if (net === 0) continue; // no net signal → no karma row, but still mark tallied
+      await client.query(
+        `INSERT INTO karma_log (builder_id, delta, reason, granted_by)
+         VALUES ($1, $2, 'peer_vote_weekly', NULL)`,
+        [builderId, net]
+      );
+      karmaRows.push({ builder_id: builderId, delta: net });
+    }
+    if (voteIds.length) {
+      await client.query(
+        `UPDATE peer_votes SET tallied_at = now() WHERE id = ANY($1::bigint[])`,
+        [voteIds]
+      );
+    }
+    return {
+      ok: true,
+      votes_tallied: voteIds.length,
+      builders_credited: karmaRows.length,
+      karma: karmaRows,
+      lag_days: PEER_VOTE_KARMA_LAG_DAYS,
+    };
+  });
+}
+
+module.exports = {
+  PEER_VOTE_KARMA_LAG_DAYS,
+  acquireMergeLease,
+  builderAnalytics,
+  countGradeAttempts,
+  ecosystemAnalytics,
+  estimationDriftSummary,
+  getEstVsActualRatio,
+  gradeAttemptStats,
+  gradeByBuilder,
+  gradeTrendByDay,
+  logGradeAttempt,
+  mergeLeaseStatus,
+  recentGradesForBuilder,
+  recentShippedTasks,
+  recentShippedTasksByBuilder,
+  releaseMergeLease,
+  rollingAvgGrade,
+  tallyPeerVotes,
+};