@bongos/core 1.17.0

package/modules/economy/credits.js

@@ -0,0 +1,430 @@
+'use strict';
+
+// Credit allocation — the cost-plus + kind-multiplier reward model, the
+// idea-promotion bonus, the flat session-token reward, and the net-negative
+// (simplification) ship bonus. Carved out of the GDS core src/bongos/db.js into
+// modules/economy/ (BV1.R77 / ADR 0093 §1-2) byte-for-byte — only the require()
+// paths changed (the shared pool + token pricing reach through the published
+// doorway; the achievements sibling is an intra-module require). The lifecycle
+// (db.applyGrade/confirmTask/upsertSessionRecordWithReward) resolves these
+// through the `reward` kernel PORT rather than importing this module.
+
+const { pool, branding } = require('../../src/module-api');
+const { priceModelUsage, PRICES } = require('../../src/module-api').llmPricing; // cost-plus session reward (task 1005)
+const achievements = require('./achievements');
+
+async function leaderboard(limit = 20) {
+  // `rank` is in the row so /builders can render the rank badge next to each
+  // citizen and offer a sort-by-rank column (V3.R16 #240).
+  // V3.R26 (#246): `karma` is included too so the leaderboard can offer a
+  // "sort by karma" toggle. Server still returns the row in drachmae order
+  // (the historical default); the client re-sorts when a non-default mode
+  // is picked.
+  // task 1531: each row also carries an `achievements` string[] (top 5 unlocked
+  // ids by sort_order) so the hall's /leaderboard renderAchievementRow() shows
+  // laurels inline. Without it b.achievements was undefined and the laurels
+  // never rendered — this mirrors the /public/leaderboard query
+  // (getLeaderboardWithAchievements) so both leaderboard surfaces match.
+  const { rows } = await pool.query(
+    `SELECT id, github_login, display_name, avatar_url, total_credits, karma, 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 = builders.id
+                   ORDER BY a.sort_order
+                   LIMIT 5
+                ) t
+            ), ARRAY[]::text[]) AS achievements
+       FROM builders
+       ORDER BY total_credits DESC, created_at ASC
+       LIMIT $1`,
+    [limit]
+  );
+  return rows;
+}
+
+// =========================================================================
+// Kind multipliers + idea-promotion bonus — V3.R27 (#247).
+// =========================================================================
+//
+// All credits_reward values on tasks are author-estimated in raw drachmae;
+// historically every kind paid 1:1. V3.R27 introduces a small per-kind
+// weighting so the system over-rewards the kinds we want more of (bugs caught,
+// learnings captured, blocker-resolutions landed, decisions documented) and
+// under-rewards routine maintenance (cleanup, refactor). The shape is
+// intentionally narrow — values are clamped between 0.8x and 1.5x — so
+// builders cannot game it by misclassifying a task to chase 3x reward.
+//
+// The multiplier is applied at credit-grant time inside the SAME transaction
+// that writes the credit_log row, so the audit trail is atomic. The
+// description column (added in migration 031) records the math inline:
+//   "40c × 1.0 = 40c (feature)"
+// Old credit_log rows have NULL description; they stay valid — this is a
+// forward-looking convention only.
+//
+// Staged idea-bonus: when an idea was captured in idea_inbox and later
+// promoted (idea_inbox.promoted_to_task_id = task.id), the original capturer
+// earns a slice when the resulting task ships. Slice is 25% of the
+// multiplier-adjusted reward, rounded to nearest integer drachma, paid to the
+// idea's captured_by builder. Idempotent on (task_id, reason='idea_promotion_bonus')
+// — a re-grade is a no-op. No self-bonus: if the same builder captured the
+// idea AND shipped the task, no bonus is paid (the task reward already paid
+// them in full).
+//
+// Configurable? Yes — by editing this constant table. We deliberately did NOT
+// build a kind_multipliers DB table for V3.R27 because:
+//   (a) values are policy decisions that deserve a code review + ADR + commit
+//       trail, not a hot-path UPDATE that bypasses peer review.
+//   (b) the surface is tiny (9 entries) and changes rarely.
+//   (c) the deterministic-constant form is what the grader, achievement
+//       evaluators, and analytics queries can read without an extra round-trip.
+// If this calculus changes (per-builder multipliers, per-version overrides),
+// a future migration can promote this to a table.
+const KIND_MULTIPLIERS = Object.freeze({
+  feature:             1.0,
+  bug:                 1.2,
+  'learning-capture':  1.5,
+  'blocker-resolution':1.5,
+  decision:            1.3,
+  infra:               1.0,
+  refactor:            0.9,
+  cleanup:             0.8,
+  spike:               1.1,
+  verify:              1.0, // task 1053 (F): verification tasks reward like infra
+  unclassified:        1.0,
+});
+const IDEA_BONUS_FRACTION = 0.25; // 25% slice to the idea's original capturer
+
+// =========================================================================
+// Session token reward (flat cost-plus) — task 1005 (ADR 0054).
+// =========================================================================
+//
+// A SHIPPED session earns drachmae proportional to its TRUE API token cost:
+//   drachmae = round(true_cost_usd * (1 + REWARD_MARGIN_PCT/100))
+// i.e. cost + 20%, with 1 DRACHMA = $1 (owner re-denomination 2026-06-15,
+// task 1138 — see the ADR 0054 amendment). This reward was originally minted in
+// integer CENTS (the formula carried a trailing ×100); that 100× factor was
+// dropped so a token-reward drachma reads as a whole DOLLAR of cost-plus value
+// — de-inflating balances ~100× and bringing this path onto the same scale as
+// the per-task credits_reward path above (still a unitless author estimate).
+// Both accrue to builders.total_credits (= equity drachmae); ADR 0054 (+ its
+// 2026-06-15 amendment) records the convention and why the cents form existed.
+//
+// REWARD_MARGIN_PCT (and the 1 drachma = $1 peg) are the code-default reward
+// POLICY. They stay a code-reviewed default — not a live UI knob — for the same
+// reasons KIND_MULTIPLIERS does: a policy decision deserves a commit trail and
+// the grader reads it deterministically. But the reward policy is also
+// PER-INSTANCE config (task 2009 / BONGOS-V1): an instance overrides the margin
+// + the drachmae:USD peg in `config/branding.json` `reward.{marginPct,usdPeg}`
+// (still a committed, code-reviewed change — just in the instance's config, not
+// the vendored core module). `rewardConfig()` resolves the instance value over
+// these defaults; the pure helper keeps its code defaults so tests stay
+// deterministic and the call site passes the resolved config. The currency LABEL
+// is `branding.currency.label`.
+const REWARD_MARGIN_PCT = 20; // cost-plus margin, percent — DEFAULT (task 1005)
+
+// Per-instance reward policy, resolved over the code defaults. Best-effort: a
+// branding hiccup falls back to the defaults so reward accrual never crashes.
+function rewardConfig() {
+  let r = {};
+  try { r = (branding().reward) || {}; } catch { r = {}; }
+  const marginPct = Number.isFinite(Number(r.marginPct)) ? Number(r.marginPct) : REWARD_MARGIN_PCT;
+  const usdPeg = Number.isFinite(Number(r.usdPeg)) && Number(r.usdPeg) > 0 ? Number(r.usdPeg) : 1;
+  return { marginPct, usdPeg };
+}
+
+// Pure helper — exported for tests. Returns { trueCostUsd, marginPct, drachmae,
+// description }. drachmae = round(cost × (1+margin) × usdPeg); at the 1:1 peg a
+// drachma is a whole dollar of cost-plus value (task 1138), e.g.
+//   "$15.00 true cost × 1.20 = 18 drachmae (token reward)"
+// NOTE a sub-$0.42 session (at the 1:1 peg) rounds to 0 drachmae — intended:
+// sub-dollar sessions earn nothing. Kept pure (code-default params); the call
+// site resolves per-instance policy via rewardConfig() and passes it in.
+function computeSessionTokenReward(trueCostUsd, marginPct = REWARD_MARGIN_PCT, usdPeg = 1) {
+  const cost = Number(trueCostUsd) || 0;
+  const pct = Number(marginPct) || 0;
+  const peg = Number.isFinite(Number(usdPeg)) && Number(usdPeg) > 0 ? Number(usdPeg) : 1;
+  const mult = 1 + pct / 100;
+  const drachmae = Math.round(cost * mult * peg);
+  const pegNote = peg !== 1 ? ` × ${peg} peg` : '';
+  const description =
+    `$${cost.toFixed(2)} true cost × ${mult.toFixed(2)}${pegNote} = ${drachmae} drachmae (token reward)`;
+  return { trueCostUsd: cost, marginPct: pct, drachmae, description };
+}
+
+// Pure helper — exported for tests. Returns { raw, multiplier, effective,
+// description } for a given task kind + raw credit value. Unknown kinds fall
+// back to 1.0× and a description that flags the fallback so an audit reader
+// can spot misclassification.
+function applyKindMultiplier(rawCredits, kind) {
+  const raw = Number(rawCredits) || 0;
+  const k = (kind == null || kind === '') ? 'unclassified' : String(kind);
+  const known = Object.prototype.hasOwnProperty.call(KIND_MULTIPLIERS, k);
+  const multiplier = known ? KIND_MULTIPLIERS[k] : 1.0;
+  const effective = Math.round(raw * multiplier);
+  // Format multiplier without trailing zero noise: 1.0 → "1.0", 1.25 → "1.25".
+  const multStr = multiplier.toFixed(2).replace(/0$/, '').replace(/\.$/, '.0');
+  const kindLabel = known ? k : `${k} (unknown — defaulted to 1.0×)`;
+  const description = `${raw}c × ${multStr} = ${effective}c (${kindLabel})`;
+  return { raw, multiplier, effective, description, kind: k };
+}
+
+// Write the primary task-ship credit_log row, applying the kind multiplier.
+// Caller must already have verified that no prior 'task.confirmed' row exists
+// for this task. Returns { creditsAwarded, multiplier, raw } where
+// creditsAwarded is the multiplier-adjusted integer that landed.
+async function insertMultipliedConfirmCredit(client, builderId, taskId, rawCredits, kind) {
+  const result = applyKindMultiplier(rawCredits, kind);
+  if (result.effective <= 0) {
+    return { creditsAwarded: 0, multiplier: result.multiplier, raw: result.raw };
+  }
+  await client.query(
+    `INSERT INTO credit_log (builder_id, task_id, delta, reason, description)
+     VALUES ($1, $2, $3, 'task.confirmed', $4)`,
+    [builderId, taskId, result.effective, result.description]
+  );
+  return {
+    creditsAwarded: result.effective,
+    multiplier: result.multiplier,
+    raw: result.raw,
+  };
+}
+
+// Idea-promotion bonus. Look up idea_inbox.promoted_to_task_id = task.id; if
+// found AND captured_by != shipper AND no prior bonus exists for this task,
+// grant the idea-capturer a slice of `multipliedCredits`. Returns
+// { ideaBonusAwarded, bonusBuilderId, ideaId } — all null if nothing was paid.
+//
+// Guard order matters: idempotency check runs FIRST so a re-grade is a true
+// no-op (no fresh idea lookup, no second log row). The self-bonus refusal
+// runs SECOND so the audit trail still records the lookup-then-skip in a
+// re-grade scenario.
+async function maybeAwardIdeaPromotionBonus(client, taskId, shipperBuilderId, multipliedCredits) {
+  if (!Number.isFinite(multipliedCredits) || multipliedCredits <= 0) {
+    return { ideaBonusAwarded: 0, bonusBuilderId: null, ideaId: null };
+  }
+  // Idempotency guard: already paid? bail.
+  const { rows: existing } = await client.query(
+    `SELECT 1 FROM credit_log
+      WHERE task_id = $1 AND reason = 'idea_promotion_bonus' LIMIT 1`,
+    [taskId]
+  );
+  if (existing.length > 0) {
+    return { ideaBonusAwarded: 0, bonusBuilderId: null, ideaId: null };
+  }
+  // Find the idea_inbox row this task was promoted from, if any. Prefer the
+  // most recent if the (degenerate) case of multiple ideas pointing at the
+  // same task ever arises.
+  const { rows: ideaRows } = await client.query(
+    `SELECT id, captured_by
+       FROM idea_inbox
+      WHERE promoted_to_task_id = $1 AND captured_by IS NOT NULL
+      ORDER BY captured_at DESC
+      LIMIT 1`,
+    [taskId]
+  );
+  if (ideaRows.length === 0) {
+    return { ideaBonusAwarded: 0, bonusBuilderId: null, ideaId: null };
+  }
+  const idea = ideaRows[0];
+  // No self-bonus: the shipper already collected the task reward in full.
+  if (Number(idea.captured_by) === Number(shipperBuilderId)) {
+    return { ideaBonusAwarded: 0, bonusBuilderId: null, ideaId: idea.id };
+  }
+  const bonus = Math.round(Number(multipliedCredits) * IDEA_BONUS_FRACTION);
+  if (bonus <= 0) {
+    return { ideaBonusAwarded: 0, bonusBuilderId: idea.captured_by, ideaId: idea.id };
+  }
+  const description = `idea-promotion bonus: ${Math.round(IDEA_BONUS_FRACTION * 100)}% of ${multipliedCredits}c = ${bonus}c (idea #${idea.id} → task #${taskId})`;
+  await client.query(
+    `INSERT INTO credit_log (builder_id, task_id, delta, reason, description)
+     VALUES ($1, $2, $3, 'idea_promotion_bonus', $4)`,
+    [idea.captured_by, taskId, bonus, description]
+  );
+  return {
+    ideaBonusAwarded: bonus,
+    bonusBuilderId: Number(idea.captured_by),
+    ideaId: Number(idea.id),
+  };
+}
+
+// Award the flat cost-plus session token reward, idempotent per session_id
+// (task 1005, ADR 0054). Called inside the same transaction as the session
+// upsert (see upsertSessionRecordWithReward).
+//   - client     : a connected pg client (transaction-aware), client-first like
+//                  insertMultipliedConfirmCredit so it's unit-testable with a fake.
+//   - builderId  : authoritative owner (verified at the route), never the body.
+//   - sessionId  : CLAUDE_CODE_SESSION_ID — the idempotency key.
+//   - modelUsage : { modelId: {input,output,cache_read,cache_creation} } from the
+//                  uploaded digest. Priced SERVER-SIDE; never a client dollar value.
+//   - totalTokens: (task 1676) the session's authoritative total token count (the
+//                  column the route's empty-session guard checks). Used ONLY as a
+//                  fallback: when modelUsage prices to $0 but the session carried
+//                  real tokens, the reward is priced from totalTokens at the opus
+//                  rate so the dev-box/CI agent path (which historically uploaded
+//                  empty/unpriceable model_usage → $0 reward; ADR 0097) still pays
+//                  the real cost-plus amount. This is NOT a fabricated dollar value
+//                  — it prices REAL token counts via the same locked PRICES table.
+// Returns { drachmae, trueCostUsd, awarded, unknownModels, pricedFromTotalTokens }.
+// awarded=false means a prior reward row for this session already existed
+// (re-upload / re-ship) — a true no-op, no second credit, no double payout.
+async function awardSessionTokenReward(client, builderId, sessionId, modelUsage, totalTokens = 0) {
+  const { true_cost_usd: pricedCostUsd, unknown_models: unknownModels } =
+    priceModelUsage(modelUsage);
+  // Cost-plus zero-out fallback (task 1676). priceModelUsage returns $0 when
+  // model_usage is empty or carries no token counts — the exact dev-box/CI symptom
+  // ADR 0097 records ("upload no priced model usage"). When that happens but the
+  // session DID carry real tokens, price the total at the opus rate so the reward
+  // reflects the real spend instead of silently rounding to 0. The blend assumes a
+  // marathon agent session is cache_read-dominated (the real cost driver — a large
+  // context re-read each turn), so this conservatively UNDER-estimates rather than
+  // over-pays vs. a true per-tier split.
+  let trueCostUsd = pricedCostUsd;
+  let pricedFromTotalTokens = false;
+  const tt = Math.max(0, Math.trunc(Number(totalTokens) || 0));
+  if (!(pricedCostUsd > 0) && tt > 0) {
+    trueCostUsd = Math.round(((tt * PRICES.opus.cache_read) / 1e6) * 10000) / 10000;
+    pricedFromTotalTokens = true;
+  }
+  const { marginPct, usdPeg } = rewardConfig();
+  const { drachmae, description } = computeSessionTokenReward(trueCostUsd, marginPct, usdPeg);
+
+  // Nothing priced (no real tokens) — record nothing, report cleanly.
+  if (!(drachmae > 0)) {
+    return { drachmae: 0, trueCostUsd, awarded: false, unknownModels, pricedFromTotalTokens };
+  }
+
+  // Fast-path idempotency guard (the partial-unique index is the hard backstop
+  // against a race). Keyed on the literal reason + session_id.
+  const { rows: existing } = await client.query(
+    `SELECT 1 FROM credit_log
+      WHERE reason = 'session.token_reward' AND session_id = $1 LIMIT 1`,
+    [sessionId]
+  );
+  if (existing.length > 0) {
+    return { drachmae: 0, trueCostUsd, awarded: false, unknownModels, pricedFromTotalTokens };
+  }
+
+  // Append-only ledger row. task_id = NULL (session-level, not task-level).
+  // ON CONFLICT DO NOTHING on the partial-unique index closes the race window:
+  // if a parallel upload inserted between our SELECT and here, we no-op cleanly.
+  const { rows } = await client.query(
+    `INSERT INTO credit_log (builder_id, task_id, delta, reason, description, session_id)
+     VALUES ($1, NULL, $2, 'session.token_reward', $3, $4)
+     ON CONFLICT (session_id) WHERE reason = 'session.token_reward' DO NOTHING
+     RETURNING id`,
+    [builderId, drachmae, description, sessionId]
+  );
+  const awarded = rows.length > 0;
+  return { drachmae: awarded ? drachmae : 0, trueCostUsd, awarded, unknownModels, pricedFromTotalTokens };
+}
+
+// net-negative ship bonus — V3.R93 (#354). Simplification reward.
+//
+// The v1 grader's scoreLocNetNegative concept (a ship that removes more lines
+// than it adds is a win) was only ever expressed as a rubric SCORE in the
+// deprecated deterministic grader — it never moved credits. Here we revive the
+// idea as a small, real credit bonus routed through the SAME credit_log path
+// applyGrade already uses for task.confirmed.
+//
+// The bonus is a flat +1 drachma when lines_removed > lines_added in the ship's
+// diff_stats (the same shortstat the grader already records in
+// signals.diff_stats — see scripts/gds/ship.js computeDiffShortstat). Net-zero
+// or net-positive ships get nothing. The credit_log description embeds the raw
+// removed/added values and the reason so the audit trail is self-explaining.
+//
+// Idempotent: keyed on (task_id, reason='ship.net_negative') so a re-grade
+// can't double-award. Returns { bonus, justUnlocked } — bonus is the integer
+// credit awarded (0 if not eligible / already awarded); justUnlocked is the
+// array of achievements unlocked by this award (the "Subtractor" achievement,
+// if the threshold was crossed on this ship).
+//
+// The "Subtractor" achievement (seeded in migration 031) is awarded here via
+// the EXISTING builder_achievements mechanism (achievements.unlockAchievement)
+// rather than in achievements.evaluateAfterShip, because the count it depends on
+// (this builder's net-negative ship bonuses) only becomes correct after THIS
+// ship's bonus row is inserted — and that insert lives here. Doing the unlock
+// inline keeps the read-then-unlock atomic with the insert in one transaction.
+const NET_NEGATIVE_BONUS = 1;
+const SUBTRACTOR_THRESHOLD = 3; // net-negative ships needed to unlock Subtractor
+function netNegativeBonusAmount(diffStats) {
+  if (!diffStats) return 0;
+  const added = Number(diffStats.lines_added) || 0;
+  const removed = Number(diffStats.lines_removed) || 0;
+  return removed > added ? NET_NEGATIVE_BONUS : 0;
+}
+
+async function awardNetNegativeBonus(client, builderId, taskId, diffStats) {
+  const bonus = netNegativeBonusAmount(diffStats);
+  if (bonus <= 0) return { bonus: 0, justUnlocked: [] };
+
+  const { rows: existing } = await client.query(
+    `SELECT 1 FROM credit_log WHERE task_id = $1 AND reason = 'ship.net_negative' LIMIT 1`,
+    [taskId]
+  );
+  if (existing.length > 0) return { bonus: 0, justUnlocked: [] };
+
+  const added = Number(diffStats.lines_added) || 0;
+  const removed = Number(diffStats.lines_removed) || 0;
+  const description = `net-negative ship bonus: +${bonus} (removed ${removed} > added ${added} lines — simplification reward)`;
+
+  await client.query(
+    `INSERT INTO credit_log (builder_id, task_id, delta, reason, description)
+     VALUES ($1, $2, $3, 'ship.net_negative', $4)`,
+    [builderId, taskId, bonus, description]
+  );
+
+  // Subtractor: >= 3 net-negative ships (this one now counted above).
+  const justUnlocked = [];
+  if (!(await achievements.alreadyUnlocked(client, builderId, 'subtractor'))) {
+    const { rows } = await client.query(
+      `SELECT COUNT(*)::int AS n FROM credit_log
+        WHERE builder_id = $1 AND reason = 'ship.net_negative'`,
+      [builderId]
+    );
+    if (Number(rows[0].n) >= SUBTRACTOR_THRESHOLD) {
+      const unlocked = await achievements.unlockAchievement(client, builderId, 'subtractor', taskId);
+      if (unlocked) justUnlocked.push(unlocked);
+    }
+  }
+
+  return { bonus, justUnlocked };
+}
+
+// sumCreditsForTasks — the drachmae (credit_log delta) a builder actually earned
+// for a set of tasks. POST /sessions uses this to populate drachmae_earned from
+// the authoritative ledger server-side, rather than trusting a client value or
+// the configured credits_reward (which diverges once kind multipliers / idea
+// bonuses apply — ADR 0023).
+async function sumCreditsForTasks(builderId, taskIds) {
+  const ids = Array.isArray(taskIds) ? taskIds.map(Number).filter(Number.isFinite) : [];
+  if (ids.length === 0) return 0;
+  const { rows } = await pool.query(
+    `SELECT COALESCE(SUM(delta), 0)::int AS total
+       FROM credit_log
+      WHERE builder_id = $1 AND task_id = ANY($2::bigint[])`,
+    [builderId, ids]
+  );
+  return rows[0] ? rows[0].total : 0;
+}
+
+module.exports = {
+  leaderboard,
+  KIND_MULTIPLIERS,
+  IDEA_BONUS_FRACTION,
+  REWARD_MARGIN_PCT,
+  rewardConfig,
+  computeSessionTokenReward,
+  applyKindMultiplier,
+  insertMultipliedConfirmCredit,
+  maybeAwardIdeaPromotionBonus,
+  awardSessionTokenReward,
+  NET_NEGATIVE_BONUS,
+  SUBTRACTOR_THRESHOLD,
+  netNegativeBonusAmount,
+  awardNetNegativeBonus,
+  sumCreditsForTasks,
+};

package/modules/economy/migrations/economy_001_fix_gds_shipper_description.sql

@@ -0,0 +1,91 @@
+-- economy_001_fix_gds_shipper_description.sql — task #1679.
+--
+-- Two data fixes for the broken-achievements bug, both idempotent and safe to
+-- re-run / no-op on a fresh instance.
+--
+-- 1) gds-shipper DESCRIPTION still pointed at src/pms/ / scripts/pms/, paths that
+--    ceased to exist in the PMS -> GDS rename (V3.R01, migration 019). The
+--    EVALUATOR was re-pointed at the time but the seeded description was missed
+--    (idea 50). Correct it so the hall, CLI banners, and locked-progress hints
+--    describe what actually unlocks the badge.
+--
+-- 2) BACKFILL the achievements that should already be unlocked. Until this task,
+--    the dominant ship path (confirmTask / --skip-grade / grader_bypass) never
+--    evaluated achievements, and breaking-the-100c-bar was a boundary check on a
+--    credit branch the session reward never hit — so the board was effectively
+--    dead (e.g. nobody held breaking-the-100c-bar despite multiple builders far
+--    past 100c). The forward fix (state-based reconcile on every ship path) heals
+--    builders on their next ship; this backfills everyone NOW, on deploy, so the
+--    hall is correct immediately.
+--
+--    The predicates here are a ONE-SHOT SQL mirror of modules/economy/
+--    achievements.js STATE_EVALUATORS. A migration is immutable and runs once, so
+--    this copy cannot drift the way the THREE long-lived copies did (idea 44/50);
+--    the JS list remains the single forward source of truth. Streak-3/streak-7
+--    are intentionally OMITTED here (their timezone-aware consecutive-day math is
+--    not worth duplicating in SQL) — they backfill via the JS reconcile on a
+--    builder's next ship, or immediately via `node scripts/gds/diagnose-achievements.js --apply`.
+--
+--    Idempotent: ON CONFLICT DO NOTHING means re-running unlocks nothing new, and
+--    the credit bonus is inserted ONLY for rows the INSERT actually created
+--    (RETURNING), so totals never double-count. The credit_log trigger rolls each
+--    bonus into builders.total_credits exactly as a live unlock would.
+
+UPDATE achievements
+   SET description = 'Ship a task whose touches[] include src/bongos/ or scripts/gds/.'
+ WHERE id = 'gds-shipper';
+
+WITH eligible AS (
+  -- first-claim: has ever claimed
+  SELECT b.id AS builder_id, 'first-claim'::text AS achievement_id
+    FROM builders b
+   WHERE EXISTS (SELECT 1 FROM claims c WHERE c.builder_id = b.id)
+  UNION
+  -- first-ship: has ever shipped a claim
+  SELECT DISTINCT c.builder_id, 'first-ship'
+    FROM claims c
+   WHERE c.outcome = 'shipped'
+  UNION
+  -- art-pipeline-shipper: a shipped task touching art/
+  SELECT DISTINCT c.builder_id, 'art-pipeline-shipper'
+    FROM claims c JOIN tasks t ON t.id = c.task_id
+   WHERE c.outcome = 'shipped'
+     AND EXISTS (SELECT 1 FROM unnest(t.touches) AS p WHERE p LIKE 'art/%')
+  UNION
+  -- gds-shipper: a shipped task touching src/bongos/ or scripts/gds/
+  SELECT DISTINCT c.builder_id, 'gds-shipper'
+    FROM claims c JOIN tasks t ON t.id = c.task_id
+   WHERE c.outcome = 'shipped'
+     AND EXISTS (SELECT 1 FROM unnest(t.touches) AS p
+                  WHERE p LIKE 'src/bongos/%' OR p LIKE 'scripts/gds/%')
+  UNION
+  -- first-parallel-claim: two shipped claims whose windows overlap
+  SELECT DISTINCT a.builder_id, 'first-parallel-claim'
+    FROM claims a JOIN claims b2
+      ON b2.builder_id = a.builder_id AND b2.id <> a.id
+   WHERE 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)
+  UNION
+  -- breaking-the-100c-bar: at or past 100 total credits
+  SELECT b.id, 'breaking-the-100c-bar'
+    FROM builders b
+   WHERE b.total_credits >= 100
+  UNION
+  -- subtractor: >= 3 net-negative ship bonuses
+  SELECT cl.builder_id, 'subtractor'
+    FROM credit_log cl
+   WHERE cl.reason = 'ship.net_negative'
+   GROUP BY cl.builder_id
+  HAVING COUNT(*) >= 3
+),
+ins AS (
+  INSERT INTO builder_achievements (builder_id, achievement_id, unlocked_at, unlocked_by_task_id)
+  SELECT builder_id, achievement_id, now(), NULL FROM eligible
+  ON CONFLICT (builder_id, achievement_id) DO NOTHING
+  RETURNING builder_id, achievement_id
+)
+INSERT INTO credit_log (builder_id, task_id, delta, reason, recorded_at)
+SELECT ins.builder_id, NULL, a.credit_bonus, 'achievement.' || ins.achievement_id, now()
+  FROM ins JOIN achievements a ON a.id = ins.achievement_id
+ WHERE a.credit_bonus > 0;

package/modules/economy/module.json

@@ -0,0 +1,10 @@
+{
+  "key": "economy",
+  "title": "Economy",
+  "description": "Credit allocation (the cost-plus + kind-multiplier reward model), the cost ledger + dashboard rollups, builder streaks, achievements/gamification, and the leaderboard. A core-domain module carved out of the GDS core in BV1.R77 (ADR 0093 §1-2); default-on because every instance rewards its own builders. Registers the `reward` kernel PORT the lifecycle resolves at confirm/ship/claim time.",
+  "coreVersion": "^1.7.0",
+  "default": true,
+  "contributes": { "routes": ["cost", "leaderboard", "reward"] },
+  "provides": ["reward"],
+  "consumes": []
+}

package/modules/economy/reward.js

@@ -0,0 +1,61 @@
+'use strict';
+
+// The `reward` kernel PORT provider surface (BV1.R77 / ADR 0093 §1-2).
+//
+// economy registers ONE port — `reward` — that the lifecycle + the core read
+// routes resolve. It is a TRANSACTION-PARTICIPANT port for the credit-allocation
+// half: the caller (db.applyGrade / confirmTask / upsertSessionRecordWithReward,
+// inside its own withTx) passes its tx `client` as the first arg, so the credit
+// write commits atomically with the state-machine SQL that stays in the core
+// lifecycle (ADR 0093 §2 — extract the capability, keep the state machine). The
+// gamification + read half is stateless.
+//
+// We DELEGATE (do NOT spread) every method so a test that stubs a method on the
+// live `achievements`/`credits` object (e.g. tests/grade_attribution.mjs sets
+// achievements.evaluateAfterShip = async () => []) still bites at call time —
+// a spread would capture the original reference at module-load and ignore the stub.
+
+const credits = require('./credits');
+const achievements = require('./achievements');
+const cost = require('./cost');
+const streak = require('./streak');
+
+module.exports = {
+  // credit allocation — transaction-participant: caller passes its tx `client`
+  insertMultipliedConfirmCredit: (...a) => credits.insertMultipliedConfirmCredit(...a),
+  maybeAwardIdeaPromotionBonus: (...a) => credits.maybeAwardIdeaPromotionBonus(...a),
+  awardNetNegativeBonus: (...a) => credits.awardNetNegativeBonus(...a),
+  awardSessionTokenReward: (...a) => credits.awardSessionTokenReward(...a),
+  // gamification hooks the lifecycle fires at claim/ship
+  evaluateAfterClaim: (...a) => achievements.evaluateAfterClaim(...a),
+  evaluateAfterShip: (...a) => achievements.evaluateAfterShip(...a),
+  evaluateAfterCreditAward: (...a) => achievements.evaluateAfterCreditAward(...a),
+  // task 1679: state-based, idempotent reconcile — the durable replacement that
+  // fires on EVERY ship path (incl. confirmTask / grader_bypass, which never
+  // evaluated achievements before, so most builders only ever got first-claim).
+  reconcileBuilderAchievements: (...a) => achievements.reconcileBuilderAchievements(...a),
+  // pure helpers + constants (display / tests)
+  applyKindMultiplier: (...a) => credits.applyKindMultiplier(...a),
+  computeSessionTokenReward: (...a) => credits.computeSessionTokenReward(...a),
+  get KIND_MULTIPLIERS() { return credits.KIND_MULTIPLIERS; },
+  get IDEA_BONUS_FRACTION() { return credits.IDEA_BONUS_FRACTION; },
+  get REWARD_MARGIN_PCT() { return credits.REWARD_MARGIN_PCT; },
+
+  // --- READ surface the core me/public/builders/sessions routes resolve through
+  //     this same port (one economy port; the grading precedent registers the
+  //     whole module surface on its single port too).
+  costSummary: (...a) => cost.costSummary(...a),
+  costCalibrationSummary: (...a) => cost.costCalibrationSummary(...a),
+  getBuilderCostStatus: (...a) => cost.getBuilderCostStatus(...a),
+  setBuilderMonthlyBudget: (...a) => cost.setBuilderMonthlyBudget(...a),
+  reconcileSessionCosts: (...a) => cost.reconcileSessionCosts(...a),
+  autonomousApiSpendMtd: (...a) => cost.autonomousApiSpendMtd(...a),
+  leaderboard: (...a) => credits.leaderboard(...a),
+  getLeaderboardWithAchievements: (...a) => achievements.getLeaderboardWithAchievements(...a),
+  listAchievements: (...a) => achievements.listAchievements(...a),
+  getBuilderAchievements: (...a) => achievements.getBuilderAchievements(...a),
+  getLockedAchievementsProgress: (...a) => achievements.getLockedAchievementsProgress(...a),
+  sumCreditsForTasks: (...a) => credits.sumCreditsForTasks(...a),
+  computeStreak: (...a) => streak.computeStreak(...a),
+  wouldExtendStreak: (...a) => streak.wouldExtendStreak(...a),
+};