@bongos/core 1.17.0

package/modules/economy/CLAUDE.md

@@ -0,0 +1,48 @@
+# `economy` module — credits, cost ledger, streaks, achievements, leaderboard + the `reward` kernel port
+
+> The **third CORE-domain** carved into a module (BV1.R77, [ADR 0093](../../docs/adr/<redacted>.md) §1-2) — after memory (R72) and grading (R73). Like grading, it follows ADR 0091 §4's load-bearing pattern: **keep the lifecycle state machine whole, extract the capability it invokes behind a kernel seam.** The lifecycle no longer imports the credit/achievement code directly; it resolves a `reward` PORT this module registers.
+
+Owns the **builder economy**: the cost-plus + kind-multiplier credit-allocation model (the real-money credit ledger), the idea-promotion bonus, the flat session-token reward, the net-negative (simplification) ship bonus, the cost ledger + dashboard rollups, builder streaks, achievements/gamification, and the leaderboard. `default: true` in `module.json` — every instance rewards its own builders, so it mounts unconditionally unless explicitly disabled.
+
+## The boundary (the one rule)
+
+This module reaches core **only** through the published doorway `../../src/module-api.js` (`coreVersion ^1.7.0` — it needs the R77 doorway addition: `llmPricing`, the shared token→USD pricing lib). It must **never** `require()` a core internal directly, and never another module. Core, in turn, must never `require()` a file in here — it reaches economy only through the `reward` port (below). Both directions are enforced by the BV1.R44/R45 fitness checks; R70's `kernel-imports-no-domain` check keeps the kernel from reaching back in.
+
+## The `reward` kernel PORT (ADR 0093 §1-2 — the headline of this carve)
+
+- **Provides — port `reward`** → the economy module's reward surface (`modules/economy/reward.js`). Registered in `routes/reward.js`'s factory (the loader runs it at boot, and again whenever a test rebuilds the GDS router — `hasProvider`-guarded so re-instantiation never trips the single-provider duplicate guard).
+- **It is a TRANSACTION-PARTICIPANT port** (unlike the stateless `grade` port): the credit-allocation methods (`insertMultipliedConfirmCredit`, `maybeAwardIdeaPromotionBonus`, `awardNetNegativeBonus`, `awardSessionTokenReward`) and the claim/ship gamification hooks (`evaluateAfterClaim/Ship/CreditAward`) take the **caller's tx `client` as the first arg**. The core lifecycle opens the `withTx`, runs the state-machine SQL (FOR UPDATE, `task_grades` upsert, `UPDATE tasks status`, claim-holder lookup, `logGradeAttempt`) itself, and calls `reward.*(client, …)` inside that same transaction — so the credit write commits atomically with the status flip. Extract the capability; keep the state machine (ADR 0091 §4).
+- **Core consumes it WITHOUT importing this module:**
+  - the LIFECYCLE — `db.applyGrade` / `db.confirmTask` / `db.decideOverrideRequest` / `db.claimTask` / `db.upsertSessionRecordWithReward` resolve it via `seams.resolveOptional('reward')` and call the credit/achievement methods inside their own `withTx`.
+  - the READ routes — `routes/me.js` (achievement getters + streak preview + `getBuilderCostStatus`), `routes/public.js` (`costSummary` + `getLeaderboardWithAchievements`), `routes/builders.js` (`setBuilderMonthlyBudget`), `routes/sessions.js` (`sumCreditsForTasks`), and `publish-reconciler.js` (`reconcileSessionCosts`) resolve the same port and call its read surface. economy registers ONE port; its provider exposes both the lifecycle methods and the read surface (the grading precedent registers the whole module surface on its single port too).
+- This replaced the former `const achievements = require('./achievements')` / `cost` / `cost-summary-shape` core→domain requires in `db.js`, the `db.leaderboard`/`db.logCost`/etc. monolith helpers, and the `require('../streak')` core-route imports.
+
+## Files
+
+| File | What |
+|---|---|
+| `credits.js` | the credit-allocation model: `KIND_MULTIPLIERS`/`IDEA_BONUS_FRACTION`/`REWARD_MARGIN_PCT`, `applyKindMultiplier`, `computeSessionTokenReward`, `insertMultipliedConfirmCredit`, `maybeAwardIdeaPromotionBonus`, `awardSessionTokenReward`, `awardNetNegativeBonus` (+ `NET_NEGATIVE_BONUS`/`SUBTRACTOR_THRESHOLD`/`netNegativeBonusAmount`), the `leaderboard`, and `sumCreditsForTasks`. Writes `credit_log`. |
+| `cost.js` | the cost ledger: `logCost` (the one `cost_log` writer), `reconcileSessionCosts`, `costSummary`/`costCalibrationSummary`, `getBuilderCostStatus`, `setBuilderMonthlyBudget`, `autonomousApiSpendMtd`. |
+| `cost-classify.js` | pure cost-attribution audit + budget classification (`classifyCostStatus`, `auditCostAttribution`, `formatAuditReport`, `OWNERLESS_CATEGORIES`, `SOFT_CAP_FRACTION`). Moved from `src/bongos/cost.js` (renamed to avoid colliding with `cost.js`). |
+| `cost-summary-shape.js` | pure cost-summary dimension shapers (`shapeBySource`/`shapeByTier`/`shapeSavings`/`shapeCostCalibration`). |
+| `streak.js` | streak math + anti-gaming guards (`computeStreak`, `wouldExtendStreak`, …). Reaches the shared pool through the doorway. |
+| `achievements.js` | the achievement evaluators (`evaluateAfterClaim/Ship/CreditAward`, `alreadyUnlocked`, `unlockAchievement`, `filesForBadges`) PLUS the getter slice moved from `db.js` (`listAchievements`, `getBuilderAchievements`, `getLeaderboardWithAchievements`, `getLockedAchievementsProgress`, `renderProgressText`). `require('./streak')` is an intra-module sibling. |
+| `reward.js` | the `reward` port provider surface — DELEGATES (does not spread) to `credits`/`achievements`/`cost`/`streak` so test stubs bite at call time. |
+| `routes/reward.js` | registers the `reward` port (above); no HTTP endpoint. |
+| `routes/cost.js` | `POST /cost` — log a cost row (idempotent). Reaches auth/validators via the doorway; the writer via `../cost`. |
+| `routes/leaderboard.js` | `GET /leaderboard` — public drachmae-ordered leaderboard, via `../credits`. |
+
+## NOT in this module (deliberately left in core)
+
+- **`llm-pricing.js`** — the shared token→USD pricing lib stays core shared LLM-cost infra (consumed by BOTH this module's reward/cost paths AND core cost scripts `ship.js`/`session-cost.js`, so it can't be economy-owned). It is exposed to this module on the doorway as `api.llmPricing` (a tracked R73-style domain leak, like `api.llmCache`). It relocates behind a port if/when an llm-infra domain is carved (tranche 2). The economy scope-map glob lists `src/bongos/llm-pricing.js` for task-affinity even though the FILE stays in core.
+- **The recent-ships feed + estimation-drift + grade-trend reads** (`db.recentShippedTasks`, `<redacted>`, `getEstVsActualRatio`, `estimationDriftSummary`, `recentGradesForBuilder`, `builderRollingAvgGrade`, `rollingAvgGrade`, `gradeTrendByDay`) — these stay `db.*` (lifecycle/sessions reads, not economy ledger SQL); out of scope for this carve.
+- **The karma feed** (`recentKarmaForBuilder`, `karmaDelta30d`, `karma_log`) — stays in core `db.js` (a separate social-signal domain).
+- **The economy-owned CLIs** — a command travels with its domain but stays under `scripts/`: `backfill-cost.js` (requires `../../modules/economy/cost-classify`), `diagnose-achievements.js` (requires `../../modules/economy/streak`). (The memory/grading-carve precedent.)
+
+## Tables
+
+None owned. `credit_log`, `cost_log`, `cost_baseline`, `achievements`, `builder_achievements` (+ their migrations) were created before the module system and stay in core `migrations/` (the schema-migrations stem-key makes a later relocation a no-op). The module owns the *queries*; any **new** economy migration belongs in `modules/economy/migrations/` namespaced `economy_*` (the additive rule).
+
+## Tests
+
+`tests/credit_grant.mjs` (credits.js), `tests/cost.mjs`/`tests/cost_audit.mjs`/`tests/cost_budget_status.mjs` (cost-classify.js), `tests/cost_summary_shape.mjs`, `tests/streak.mjs`, and `tests/diff_derived_signals.mjs` import from `modules/economy/…`. The lifecycle-attribution tests (`tests/grade_attribution.mjs`, `tests/confirm_attribution.mjs`, `tests/grade_server_authoritative.mjs`, `tests/override_attribution.mjs`, `tests/override_request_ownership.mjs`) register the `reward` port (and stub `achievements` on the live module object) before driving `db.applyGrade`/`confirmTask`/`decideOverrideRequest`. See ADR 0093.

package/modules/economy/achievements.js

@@ -0,0 +1,594 @@
+'use strict';
+
+// Achievement evaluation — runs inside existing DB transactions so unlocks
+// are atomic with the action that triggered them.
+//
+// Three entry points, each called by the relevant route:
+//   evaluateAfterClaim(client, builderId, claimId)
+//   evaluateAfterShip(client, builderId, taskId)
+//   evaluateAfterCreditAward(client, builderId, totalBefore, totalAfter)
+//
+// Each returns an array of { id, name, credit_bonus } for achievements just
+// unlocked in this call — the route adds them to its API response as
+// just_unlocked.
+
+const streak = require('./streak');
+// Carved into modules/economy/ (BV1.R77 / ADR 0093 §1-2): the achievement GETTER
+// slice (listAchievements/getBuilderAchievements/getLeaderboardWithAchievements/
+// getLockedAchievementsProgress/renderProgressText), moved from src/bongos/db.js,
+// reads the shared pool through the published doorway — a module never requires a
+// core internal. The evaluators above take a tx `client` from the caller.
+const { pool } = require('../../src/module-api');
+
+async function alreadyUnlocked(client, builderId, achievementId) {
+  const r = await client.query(
+    'SELECT 1 FROM builder_achievements WHERE builder_id=$1 AND achievement_id=$2',
+    [builderId, achievementId]
+  );
+  return r.rowCount > 0;
+}
+
+async function unlockAchievement(client, builderId, achievementId, taskId) {
+  const ach = await client.query(
+    'SELECT id, name, credit_bonus FROM achievements WHERE id=$1',
+    [achievementId]
+  );
+  if (ach.rowCount === 0) return null;
+  const { id, name, credit_bonus } = ach.rows[0];
+
+  await client.query(
+    `INSERT INTO builder_achievements (builder_id, achievement_id, unlocked_at, unlocked_by_task_id)
+     VALUES ($1, $2, now(), $3)
+     ON CONFLICT DO NOTHING`,
+    [builderId, id, taskId ?? null]
+  );
+
+  if (credit_bonus > 0) {
+    await client.query(
+      `INSERT INTO credit_log (builder_id, task_id, delta, reason, recorded_at)
+       VALUES ($1, $2, $3, $4, now())`,
+      [builderId, taskId ?? null, credit_bonus, `achievement.${id}`]
+    );
+    // trigger on credit_log bumps builders.total_credits automatically
+  }
+
+  return { id, name, credit_bonus };
+}
+
+async function evaluateAfterClaim(client, builderId, _claimId) {
+  const results = [];
+
+  // first-claim: this is the builder's very first claim
+  if (!await alreadyUnlocked(client, builderId, 'first-claim')) {
+    const count = await client.query(
+      'SELECT COUNT(*) FROM claims WHERE builder_id=$1',
+      [builderId]
+    );
+    if (Number(count.rows[0].count) === 1) {
+      const unlocked = await unlockAchievement(client, builderId, 'first-claim', null);
+      if (unlocked) results.push(unlocked);
+    }
+  }
+
+  return results;
+}
+
+// touches[] cleanup [3/8] (task 878): the prefix-keyed shipper badges should
+// reflect what was ACTUALLY shipped, not the predicted touches[]. ship.js
+// computes the committed changed-files for the grader (touches-independent per
+// #536) and passes them through /grade → applyGrade → here as `changedFiles`.
+// When that list is present we key the badges off it; otherwise we fall back to
+// the task's touches[] (manual confirms, older callers, or a ship with no diff
+// info). Once #882 backfills touches[] from the committed diff at ship time the
+// fallback itself becomes diff-accurate, so the two converge.
+function filesForBadges(changedFiles, touches) {
+  return Array.isArray(changedFiles) && changedFiles.length > 0
+    ? changedFiles
+    : Array.isArray(touches) ? touches : [];
+}
+
+async function evaluateAfterShip(client, builderId, taskId, changedFiles = null) {
+  const results = [];
+
+  // first-ship: this is the builder's very first ship.
+  //
+  // BUG FIX (PMS-V2 #190, 2026-05-11): originally queried session_logs and
+  // compared `=== 1`. That was wrong because the session_logs row for THIS
+  // ship is INSERTed in db.js AFTER evaluateAfterShip returns (line ~614),
+  // so at evaluator time the count reflects only PRIOR ships. The first
+  // ship therefore had count===0, never matched `=== 1`, and the
+  // achievement never fired.
+  //
+  // Switched to claims.outcome='shipped' (the claim row HAS been UPDATEd
+  // to outcome='shipped' + released_at=now() before this evaluator runs,
+  // per db.js line ~540) and check `=== 1` — the just-shipped claim is
+  // the only matching row, meaning this is the first ship.
+  if (!await alreadyUnlocked(client, builderId, 'first-ship')) {
+    const count = await client.query(
+      `SELECT COUNT(*) FROM claims
+       WHERE builder_id=$1 AND outcome='shipped'`,
+      [builderId]
+    );
+    if (Number(count.rows[0].count) === 1) {
+      const unlocked = await unlockAchievement(client, builderId, 'first-ship', taskId);
+      if (unlocked) results.push(unlocked);
+    }
+  }
+
+  // art-pipeline-shipper: the shipped diff includes art/ (falls back to touches[]).
+  if (!await alreadyUnlocked(client, builderId, 'art-pipeline-shipper')) {
+    const task = await client.query(
+      'SELECT touches FROM tasks WHERE id=$1',
+      [taskId]
+    );
+    if (task.rowCount > 0) {
+      const files = filesForBadges(changedFiles, task.rows[0].touches || []);
+      if (files.some((t) => t.startsWith('art/'))) {
+        const unlocked = await unlockAchievement(client, builderId, 'art-pipeline-shipper', taskId);
+        if (unlocked) results.push(unlocked);
+      }
+    }
+  }
+
+  // gds-shipper: the shipped diff includes src/bongos/ or scripts/gds/ (falls back to touches[]).
+  if (!await alreadyUnlocked(client, builderId, 'gds-shipper')) {
+    const task = await client.query(
+      'SELECT touches FROM tasks WHERE id=$1',
+      [taskId]
+    );
+    if (task.rowCount > 0) {
+      const files = filesForBadges(changedFiles, task.rows[0].touches || []);
+      if (files.some((t) => t.startsWith('src/bongos/') || t.startsWith('scripts/gds/'))) {
+        const unlocked = await unlockAchievement(client, builderId, 'gds-shipper', taskId);
+        if (unlocked) results.push(unlocked);
+      }
+    }
+  }
+
+  // first-parallel-claim (strict): two of this builder's claims overlapped on
+  // the wall clock AND both shipped successfully. Awarded on the LATER of the
+  // two ships. Called from inside resolveClaim's transaction after the current
+  // claim has been resolved with outcome='shipped' and released_at=now(), so
+  // both legs of the pair are visible to this query.
+  //
+  // Locked definition (PMS-V2 planning, limitations/pms-v2.md):
+  //   - outcome='shipped' required on BOTH claims (abandoned/partial don't count)
+  //   - claim intervals must overlap: tstzrange(A) && tstzrange(B)
+  //   - unlocked_by_task_id = the second-shipped claim's task_id
+  //   - unlocked_at = the later released_at (handled by unlockAchievement's now())
+  if (!await alreadyUnlocked(client, builderId, 'first-parallel-claim')) {
+    // Find any pair of shipped claims by this builder whose intervals overlap.
+    // Pick the pair with the latest second-ship; report the second-shipped
+    // claim's task_id so the achievement is attributed to it.
+    const pair = await client.query(
+      `WITH shipped AS (
+         SELECT id, task_id, claimed_at, released_at
+           FROM claims
+          WHERE builder_id = $1
+            AND outcome = 'shipped'
+            AND released_at IS NOT NULL
+       )
+       SELECT b.task_id AS later_task_id
+         FROM shipped a
+         JOIN shipped b ON b.id <> a.id
+        WHERE tstzrange(a.claimed_at, a.released_at) && tstzrange(b.claimed_at, b.released_at)
+          AND b.released_at >= a.released_at
+        ORDER BY b.released_at DESC, a.released_at DESC
+        LIMIT 1`,
+      [builderId]
+    );
+    if (pair.rowCount > 0) {
+      const laterTaskId = pair.rows[0].later_task_id;
+      const unlocked = await unlockAchievement(client, builderId, 'first-parallel-claim', laterTaskId);
+      if (unlocked) results.push(unlocked);
+    }
+  }
+
+  // streak-3 and streak-7: consecutive qualifying ship-days in builder's local
+  // timezone. computeStreak reads the just-resolved claim from the same
+  // transaction client (claim row already has outcome='shipped' + released_at
+  // by the time evaluateAfterShip is called from resolveClaim). The task is
+  // also at status='confirmed' by then (verification passed branch only).
+  //
+  // Anti-double-unlock is enforced both here (alreadyUnlocked check) and by
+  // the (builder_id, achievement_id) PK on builder_achievements.
+  //
+  // Once unlocked, these achievements stay unlocked — a streak-3 unlocked
+  // yesterday is NOT re-locked when today is a non-ship-day. The PK enforces
+  // this automatically (no re-insert possible).
+  const needStreak3 = !await alreadyUnlocked(client, builderId, 'streak-3');
+  const needStreak7 = !await alreadyUnlocked(client, builderId, 'streak-7');
+  if (needStreak3 || needStreak7) {
+    const s = await streak.computeStreak(builderId, client);
+    if (needStreak3 && s.current_streak >= 3) {
+      const unlocked = await unlockAchievement(client, builderId, 'streak-3', taskId);
+      if (unlocked) results.push(unlocked);
+    }
+    if (needStreak7 && s.current_streak >= 7) {
+      const unlocked = await unlockAchievement(client, builderId, 'streak-7', taskId);
+      if (unlocked) results.push(unlocked);
+    }
+  }
+
+  return results;
+}
+
+// Called after credits are awarded — pass total_credits before and after the delta.
+async function evaluateAfterCreditAward(client, builderId, totalBefore, totalAfter) {
+  const results = [];
+
+  // breaking-the-100c-bar: crossed 100 from below
+  if (!await alreadyUnlocked(client, builderId, 'breaking-the-100c-bar')) {
+    if (totalBefore < 100 && totalAfter >= 100) {
+      const unlocked = await unlockAchievement(client, builderId, 'breaking-the-100c-bar', null);
+      if (unlocked) results.push(unlocked);
+    }
+  }
+
+  return results;
+}
+
+// -------------------------------------------------------------------------
+// State-based reconcile (task 1679) — the durable replacement for the fragile
+// "evaluate exactly what just happened in this txn" hooks above.
+//
+// WHY this exists: the granular evaluators only ran on SOME ship paths.
+// db.applyGrade (the subagent-grader path) called evaluateAfterShip +
+// evaluateAfterCreditAward, but db.confirmTask (the --skip-grade / server
+// grader_bypass path — the DOMINANT one) called NEITHER. So a builder who ships
+// with grader_bypass on only ever unlocked first-claim (the claim path works).
+// And breaking-the-100c-bar was boundary-only (totalBefore<100 && totalAfter>=100)
+// on a credit branch the per-session cost-plus reward (ADR 0054) never hits, so
+// it fired for NOBODY — even lars589 at 22k credits. The whole board looked dead.
+//
+// reconcileBuilderAchievements evaluates every achievement against CURRENT DB
+// state and unlocks any the builder is eligible for but hasn't. It is:
+//   - idempotent: the alreadyUnlocked guard + the (builder_id, achievement_id)
+//     PK + ON CONFLICT DO NOTHING mean re-running never double-unlocks or
+//     double-awards a credit bonus.
+//   - path-independent: keyed off committed state (claims.outcome='shipped',
+//     tasks.touches — backfilled from the REAL diff at ship per #882 —
+//     builders.total_credits, credit_log), so it works no matter which ship
+//     path ran. Callers wrap it in a SAVEPOINT so it can never fail a ship.
+//   - the SINGLE SOURCE OF TRUTH for eligibility (STATE_EVALUATORS below).
+//     scripts/gds/diagnose-achievements.js and the backfill CLI import this same
+//     list, so the stale-prefix drift that silently broke gds-shipper
+//     (idea 44/idea 50: the diagnose/backfill copies still said src/pms/) cannot
+//     recur — there is now one definition, not three.
+//
+// Each predicate takes (client, builderId) → boolean. `client` may be a tx
+// client (reconcile-at-ship) or the shared pool (diagnose / backfill CLI).
+
+async function eligible_firstClaim(client, builderId) {
+  const r = await client.query('SELECT 1 FROM claims WHERE builder_id=$1 LIMIT 1', [builderId]);
+  return r.rowCount > 0;
+}
+
+async function eligible_firstShip(client, builderId) {
+  const r = await client.query(
+    `SELECT 1 FROM claims WHERE builder_id=$1 AND outcome='shipped' LIMIT 1`,
+    [builderId]
+  );
+  return r.rowCount > 0;
+}
+
+async function eligible_artPipelineShipper(client, builderId) {
+  const r = await client.query(
+    `SELECT 1
+       FROM claims c JOIN tasks t ON t.id = c.task_id
+      WHERE c.builder_id = $1 AND c.outcome = 'shipped'
+        AND EXISTS (SELECT 1 FROM unnest(t.touches) AS p WHERE p LIKE 'art/%')
+      LIMIT 1`,
+    [builderId]
+  );
+  return r.rowCount > 0;
+}
+
+async function eligible_gdsShipper(client, builderId) {
+  const r = await client.query(
+    `SELECT 1
+       FROM claims c JOIN tasks t ON t.id = c.task_id
+      WHERE c.builder_id = $1 AND c.outcome = 'shipped'
+        AND EXISTS (SELECT 1 FROM unnest(t.touches) AS p
+                     WHERE p LIKE 'src/bongos/%' OR p LIKE 'scripts/gds/%')
+      LIMIT 1`,
+    [builderId]
+  );
+  return r.rowCount > 0;
+}
+
+async function eligible_firstParallelClaim(client, builderId) {
+  const r = await client.query(
+    `WITH shipped AS (
+       SELECT id, claimed_at, released_at FROM claims
+        WHERE builder_id = $1 AND outcome = 'shipped' AND released_at IS NOT NULL
+     )
+     SELECT 1 FROM shipped a JOIN shipped b ON b.id <> a.id
+      WHERE tstzrange(a.claimed_at, a.released_at) && tstzrange(b.claimed_at, b.released_at)
+      LIMIT 1`,
+    [builderId]
+  );
+  return r.rowCount > 0;
+}
+
+async function eligible_breaking100c(client, builderId) {
+  const r = await client.query('SELECT total_credits FROM builders WHERE id = $1', [builderId]);
+  return r.rowCount > 0 && Number(r.rows[0].total_credits) >= 100;
+}
+
+async function eligible_subtractor(client, builderId) {
+  // Mirror credits.awardNetNegativeBonus: subtractor unlocks at SUBTRACTOR_THRESHOLD
+  // net-negative ship bonuses. Lazy-require the threshold (credits.js requires
+  // this module, so a top-level require would be circular — same lazy pattern
+  // renderProgressText uses for ./streak).
+  const { SUBTRACTOR_THRESHOLD } = require('./credits');
+  const r = await client.query(
+    `SELECT COUNT(*)::int AS n FROM credit_log
+      WHERE builder_id = $1 AND reason = 'ship.net_negative'`,
+    [builderId]
+  );
+  return Number(r.rows[0].n) >= SUBTRACTOR_THRESHOLD;
+}
+
+// Streaks use longest_streak (NOT current_streak): reconcile asks "did this
+// builder EVER reach an N-night streak", and per the achievement's own contract
+// an unlocked streak stays unlocked even after a gap. (The live evaluateAfterShip
+// checks current_streak because it only fires the instant a streak extends; the
+// retroactive view is longest_streak.)
+async function eligible_streak3(client, builderId) {
+  const s = await streak.computeStreak(builderId, client);
+  return s.longest_streak >= 3;
+}
+
+async function eligible_streak7(client, builderId) {
+  const s = await streak.computeStreak(builderId, client);
+  return s.longest_streak >= 7;
+}
+
+// Ordered by achievements.sort_order so banners/backfill output read naturally.
+const STATE_EVALUATORS = [
+  { id: 'first-ship',            fn: eligible_firstShip },
+  { id: 'first-claim',           fn: eligible_firstClaim },
+  { id: 'first-parallel-claim',  fn: eligible_firstParallelClaim },
+  { id: 'streak-3',              fn: eligible_streak3 },
+  { id: 'streak-7',              fn: eligible_streak7 },
+  { id: 'art-pipeline-shipper',  fn: eligible_artPipelineShipper },
+  { id: 'subtractor',            fn: eligible_subtractor },
+  { id: 'gds-shipper',           fn: eligible_gdsShipper },
+  { id: 'breaking-the-100c-bar', fn: eligible_breaking100c },
+];
+
+// Unlock every achievement the builder currently qualifies for but hasn't yet.
+// Returns the array of just-unlocked { id, name, credit_bonus }. Idempotent.
+// Callers inside a ship transaction MUST wrap this in a SAVEPOINT so a predicate
+// error rolls back only the reconcile, never the ship/confirm it runs within.
+async function reconcileBuilderAchievements(client, builderId, opts = {}) {
+  const { taskId = null } = opts;
+  const results = [];
+  for (const ev of STATE_EVALUATORS) {
+    if (await alreadyUnlocked(client, builderId, ev.id)) continue;
+    if (await ev.fn(client, builderId)) {
+      const unlocked = await unlockAchievement(client, builderId, ev.id, taskId);
+      if (unlocked) results.push(unlocked);
+    }
+  }
+  return results;
+}
+
+// -------------------------------------------------------------------------
+// Achievements — minimal getters added by migration 006_pms_v2.
+// Full evaluator + unlock writes live in src/bongos/achievements.js (task K1).
+// -------------------------------------------------------------------------
+
+async function listAchievements() {
+  const { rows } = await pool.query(
+    `SELECT id, name, description, icon, credit_bonus, sort_order
+       FROM achievements
+       ORDER BY sort_order, id`
+  );
+  return rows;
+}
+
+async function getBuilderAchievements(builderId) {
+  const { rows } = await pool.query(
+    `SELECT ba.builder_id, ba.achievement_id, ba.unlocked_at, ba.unlocked_by_task_id,
+            a.name, a.description, a.icon, a.credit_bonus, a.sort_order
+       FROM builder_achievements ba
+       JOIN achievements a ON a.id = ba.achievement_id
+      WHERE ba.builder_id = $1
+      ORDER BY a.sort_order`,
+    [builderId]
+  );
+  return rows;
+}
+
+// PMS-V2 #188: enriched leaderboard. Single query — for each builder in the
+// top N (by total_credits), includes an `achievements` string[] of up to
+// `perBuilderCap` achievement IDs the builder has unlocked, sorted by
+// achievements.sort_order. No N+1: one round trip total.
+async function getLeaderboardWithAchievements(limit = 10, perBuilderCap = 5) {
+  const { rows } = await pool.query(
+    `SELECT b.id,
+            b.github_login,
+            b.display_name,
+            b.avatar_url,
+            b.total_credits,
+            b.rank,
+            COALESCE((
+              SELECT array_agg(t.achievement_id ORDER BY t.sort_order)
+                FROM (
+                  SELECT ba.achievement_id, a.sort_order
+                    FROM builder_achievements ba
+                    JOIN achievements a ON a.id = ba.achievement_id
+                   WHERE ba.builder_id = b.id
+                   ORDER BY a.sort_order
+                   LIMIT $2
+                ) t
+            ), ARRAY[]::text[]) AS achievements
+       FROM builders b
+       ORDER BY b.total_credits DESC, b.created_at ASC
+       LIMIT $1`,
+    [limit, perBuilderCap]
+  );
+  return rows;
+}
+
+// PMS-V2 #188: compute human-readable progress for every achievement the
+// builder hasn't unlocked yet. Returns rows shaped like:
+//   { achievement_id, name, description, icon, progress_text }
+// Single round-trip — one aggregate query that joins achievements with the
+// per-builder counters (shipped tasks, claims, art ships, pms ships,
+// overlapping-pair count) and renders the progress sentence in JS.
+async function getLockedAchievementsProgress(builderId) {
+  // One query — pulls achievements + the counters this builder needs to
+  // produce progress text. The CROSS JOIN against the single-row counters
+  // CTE is cheap; the builder_achievements anti-join (NOT EXISTS) excludes
+  // achievements already unlocked.
+  const { rows } = await pool.query(
+    `WITH counters AS (
+       SELECT
+         (SELECT COUNT(*) FROM session_logs
+           WHERE builder_id = $1 AND outcome = 'shipped')                      AS ships,
+         (SELECT COUNT(*) FROM claims
+           WHERE builder_id = $1)                                              AS claims_total,
+         -- touches[] cleanup [3/8] (task 878): these retrospective counters key
+         -- off touches[] (the prediction). Unlike the one-time shipper badges
+         -- (re-pointed at the real diff via evaluateAfterShip), a per-load
+         -- aggregate over historical ships has no committed diff to read, so it
+         -- stays on touches[] — which becomes diff-accurate once #882 backfills
+         -- touches[] from the committed diff at ship time. No bespoke plumbing.
+         (SELECT COUNT(*) FROM tasks
+           WHERE shipped_by = $1 AND status = 'shipped'
+             AND EXISTS (SELECT 1 FROM unnest(COALESCE(touches, ARRAY[]::text[])) t
+                          WHERE t LIKE 'art/%'))                                AS art_ships,
+         (SELECT COUNT(*) FROM tasks
+           WHERE shipped_by = $1 AND status = 'shipped'
+             AND EXISTS (SELECT 1 FROM unnest(COALESCE(touches, ARRAY[]::text[])) t
+                          WHERE t LIKE 'src/bongos/%' OR t LIKE 'scripts/gds/%')) AS pms_ships,
+         (SELECT COALESCE(b.total_credits, 0) FROM builders b WHERE b.id = $1) AS total_credits,
+         (SELECT COUNT(*)
+            FROM claims a
+            JOIN claims b2 ON b2.id <> a.id
+                          AND b2.builder_id = a.builder_id
+           WHERE a.builder_id = $1
+             AND a.outcome = 'shipped' AND a.released_at IS NOT NULL
+             AND b2.outcome = 'shipped' AND b2.released_at IS NOT NULL
+             AND tstzrange(a.claimed_at, a.released_at)
+              && tstzrange(b2.claimed_at, b2.released_at))                     AS overlap_pairs
+     )
+     SELECT a.id            AS achievement_id,
+            a.name,
+            a.description,
+            a.icon,
+            a.credit_bonus,
+            c.ships,
+            c.claims_total,
+            c.art_ships,
+            c.pms_ships,
+            c.total_credits,
+            c.overlap_pairs
+       FROM achievements a
+       CROSS JOIN counters c
+      WHERE NOT EXISTS (
+        SELECT 1 FROM builder_achievements ba
+         WHERE ba.builder_id = $1 AND ba.achievement_id = a.id
+      )
+      ORDER BY a.sort_order`,
+    [builderId]
+  );
+
+  return rows.map((r) => ({
+    achievement_id: r.achievement_id,
+    name: r.name,
+    description: r.description,
+    icon: r.icon,
+    progress_text: renderProgressText(r),
+  }));
+}
+
+// Pure function — turns the counters row into a human-readable progress
+// sentence. Fallbacks gracefully when src/bongos/streak.js (task #52) hasn't
+// shipped yet: the streak achievements report a generic "track N consecutive
+// ship-days" hint instead of a real count.
+function renderProgressText(row) {
+  const id = row.achievement_id;
+  const ships = Number(row.ships || 0);
+  const claimsTotal = Number(row.claims_total || 0);
+  const artShips = Number(row.art_ships || 0);
+  const pmsShips = Number(row.pms_ships || 0);
+  const totalCredits = Number(row.total_credits || 0);
+  const overlapPairs = Number(row.overlap_pairs || 0);
+
+  // Optional dependency — task #52 may or may not have shipped yet.
+  let streak = null;
+  try {
+    // eslint-disable-next-line global-require
+    streak = require('./streak');
+  } catch (_) {
+    streak = null;
+  }
+
+  switch (id) {
+    case 'first-ship':
+      return ships === 0
+        ? 'needs first shipped task'
+        : 'keep building';
+    case 'first-claim':
+      return claimsTotal === 0
+        ? 'needs first claim'
+        : 'keep building';
+    case 'first-parallel-claim':
+      return overlapPairs === 0
+        ? 'needs two shipped tasks with overlapping claim windows'
+        : 'keep building';
+    case 'streak-3':
+    case 'streak-7': {
+      const threshold = id === 'streak-3' ? 3 : 7;
+      // Use streak.js if present (task #52). Render as e.g.
+      //   "1 of 3 ships toward streak-3"
+      if (streak && typeof streak.computeStreak === 'function') {
+        try {
+          // computeStreak may be async — handle both shapes by ignoring promise
+          // returns (we can't await inside this sync renderer). If async, fall
+          // through to the generic hint.
+          const res = streak.computeStreak();
+          if (res && typeof res.then !== 'function' && typeof res.current_streak === 'number') {
+            const cur = Math.max(0, Math.min(res.current_streak, threshold));
+            return `${cur} of ${threshold} ships toward ${id}`;
+          }
+        } catch (_) { /* fall through */ }
+      }
+      return `track ${threshold} consecutive ship-days`;
+    }
+    case 'art-pipeline-shipper':
+      return artShips === 0
+        ? 'needs one shipped task touching art/'
+        : 'keep building';
+    case 'gds-shipper':
+      return pmsShips === 0
+        ? 'needs one shipped task touching src/bongos/ or scripts/gds/'
+        : 'keep building';
+    case 'breaking-the-100c-bar': {
+      const have = Math.max(0, Math.min(totalCredits, 100));
+      return `${have} of 100c toward breaking-the-100c-bar`;
+    }
+    default:
+      return 'keep building';
+  }
+}
+
+module.exports = {
+  evaluateAfterClaim,
+  evaluateAfterShip,
+  evaluateAfterCreditAward,
+  reconcileBuilderAchievements,
+  STATE_EVALUATORS,
+  alreadyUnlocked,
+  unlockAchievement,
+  filesForBadges,
+  listAchievements,
+  getBuilderAchievements,
+  getLeaderboardWithAchievements,
+  getLockedAchievementsProgress,
+  renderProgressText,
+};