@bongos/core 1.20.57 → 1.20.59

package/modules/copy-desk/artist-stats.js

@@ -0,0 +1,56 @@
+// modules/copy-desk/artist-stats.js — the artist's LEDGER READS: the studio
+// corner's credit rows, and the profile's artist numbers (task 1004433 /
+// WA6.RP03). Apart from routes/copy-desk.js because that file is at the
+// 1,500-line ratchet (the page-decisions.js precedent); the route requires
+// `tallyCreditRows` from here for GET /copy-desk/tally, so the studio and the
+// profile read the same rows through the same call.
+//
+// Reads only. Nothing here writes, and nothing here returns a word of copy:
+// counts, sums and surface labels. That is what lets `copy-desk.artistStats` be
+// the one port this module provides without opening a copy write path
+// (tests/copy_no_cms.mjs pins exactly this one).
+
+'use strict';
+
+const api = require('../../src/module-api');
+const pageData = require('./page-data');
+const pageStatus = require('./page-status');
+
+// Every `tweak.page_approved:` credit row the builder has, through the reward
+// port (credit_log is economy's table). No reward port, or no approved page
+// landed yet (economy books one row per landed round, task 1004324), reads as
+// none: a tally of 0 is the truth then.
+//
+// ONE bounded query. An approved page books one row, so the cap is thousands of
+// pages for one artist; past it the tally says `truncated` (creditLedger's
+// `total` is the unpaginated count) rather than paging in a loop.
+const TALLY_ROW_CAP = 5000;
+async function tallyCreditRows(builderId) {
+  const reward = api.resolveOptional && api.resolveOptional('reward');
+  if (!reward || typeof reward.creditLedger !== 'function') return { rows: [], truncated: false };
+  const { rows, total } = await reward.creditLedger(builderId, { reasonPrefix: pageStatus.TALLY_REASON_PREFIX, limit: TALLY_ROW_CAP });
+  const list = rows || [];
+  return { rows: list, truncated: Number(total) > list.length };
+}
+
+// The profile's artist numbers, for core's profile route through the
+// `copy-desk.artistStats` port: the SAME reads the studio's tally and page list
+// make, composed by page-status.js composeArtistStats. No lifecycle port reads
+// as null (could not ask), never as zero. A missing page inventory leaves the
+// per-surface lines empty and keeps the tally, which comes from the ledger.
+async function readArtistStats(builderId, { now = new Date() } = {}) {
+  const lifecycle = api.resolveOptional && api.resolveOptional('lifecycle');
+  if (!lifecycle || typeof lifecycle.listPageTweakTasks !== 'function') return null;
+  const inv = pageData.loadInventory();
+  // Only this artist's rounds, read from their own web claims: a public page
+  // must not cost a scan of every round the project has ever had.
+  const [tasks, credit] = await Promise.all([lifecycle.listPageTweakTasks({ artistId: builderId }), tallyCreditRows(builderId)]);
+  const out = pageStatus.composeArtistStats({
+    builderId, inventory: inv.ok ? inv.data : null, tasks, creditRows: credit.rows, now,
+  });
+  out.inventory_known = !!inv.ok;
+  out.truncated = credit.truncated;
+  return out;
+}
+
+module.exports = { tallyCreditRows, readArtistStats, TALLY_ROW_CAP };

package/modules/copy-desk/module.json

@@ -7,6 +7,6 @@
   "default": true,
   "maintenance": { "status": "core-maintained" },
   "contributes": { "routes": ["copy-desk"], "migrations": true, "skills": ["tweak"] },
-  "provides": [],
+  "provides": ["copy-desk.artistStats"],
   "consumes": ["lifecycle"]
 }

package/modules/copy-desk/page-status.js

@@ -347,6 +347,44 @@ function composeTally({ builderId, tasks, creditRows, now }) {
   };
 }
 
+// The profile's ARTIST numbers (task 1004433 / WA6.RP03; the mock is
+// docs/design/mocks/profile-roles/): the corner tally above, unchanged, plus
+// "N of M tweaked" per surface for THIS artist. The studio's per-surface line
+// (composePages) counts every artist's rounds; a profile is one person's record,
+// so a page counts here when it has a shipped round whose artist is them. M is
+// the surface's whole page count, the same denominator the studio shows.
+//
+// `pages_approved` is the tally's own count of approved ROUNDS (each one paid);
+// `pages` is how many DISTINCT pages those rounds touched, the sum of the
+// per-surface N. The two differ once an artist tweaks the same page twice.
+//
+// Counts and sums only: no wording, no page title beyond the surface's label,
+// because the owner's decision (a) keeps these numbers public and the pages
+// themselves behind a sign-in.
+function composeArtistStats({ builderId, inventory, tasks, creditRows, now }) {
+  const tally = composeTally({ builderId, tasks, creditRows, now });
+  const byPage = indexRounds(tasks);
+  const mine = new Set();
+  for (const [pageId, rounds] of byPage) {
+    if (rounds.some((r) => r.status === 'shipped' && String(r.artist_id) === String(builderId))) mine.add(pageId);
+  }
+  const all = (inventory && inventory.pages) || [];
+  const surfaces = orderedSurfaces(inventory).map((id) => {
+    const on = all.filter((p) => p && p.surface === id);
+    const tweaked = on.filter((p) => mine.has(p.id)).length;
+    return { id, label: SURFACE_LABELS[id] || id, tweaked, total: on.length, line: `${tweaked} of ${on.length} tweaked` };
+  });
+  return {
+    pages_approved: tally.pages_tweaked,
+    pages: surfaces.reduce((n, s) => n + s.tweaked, 0),
+    surfaces_touched: surfaces.filter((s) => s.tweaked > 0).length,
+    credits: tally.credits,
+    this_week: tally.this_week,
+    week_since: tally.week_since,
+    surfaces,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // The recommendation, "what should I tweak next" (task 1004318 / BV2.TW07,
 // ADR 0341 D8). The fourth read, over the same ledger rows as the other three
@@ -689,4 +727,5 @@ module.exports = {
   composePage,
   lastRoundShippedAt,
   composeTally,
+  composeArtistStats,
 };

package/modules/copy-desk/routes/copy-desk.js

@@ -62,6 +62,7 @@ const pageStatus = require('../page-status');
 const pages = require('../pages');
 const docx = require('../docx');
 const { waitingRoundOrFail, refuseDecision, nextWaiting } = require('../page-decisions');
+const { tallyCreditRows, readArtistStats } = require('../artist-stats');
 
 const { validateOrRespond } = api;
 
@@ -360,26 +361,16 @@ function pageReadsOrFail(res) {
   return lifecycle;
 }
 
-// Every `tweak.page_approved:` credit row the caller has, through the reward
-// port (credit_log is economy's table). No reward port, or no approved page
-// landed yet (economy books one row per landed round, task 1004324), reads as
-// none: a tally of 0 is the truth then.
-//
-// ONE bounded query. An approved page books one row, so the cap is thousands of
-// pages for one artist; past it the tally says `truncated` (creditLedger's
-// `total` is the unpaginated count) rather than paging in a loop.
-const TALLY_ROW_CAP = 5000;
-async function tallyCreditRows(builderId) {
-  const reward = api.resolveOptional && api.resolveOptional('reward');
-  if (!reward || typeof reward.creditLedger !== 'function') return { rows: [], truncated: false };
-  const { rows, total } = await reward.creditLedger(builderId, { reasonPrefix: pageStatus.TALLY_REASON_PREFIX, limit: TALLY_ROW_CAP });
-  const list = rows || [];
-  return { rows: list, truncated: Number(total) > list.length };
-}
+// The tally's credit rows and the profile's artist numbers live in
+// ../artist-stats.js (task 1004433); this file is at the 1,500-line ratchet.
 
 module.exports = function buildCopyDeskRouter() {
   const router = express.Router();
 
+  if (!api.hasProvider('copy-desk.artistStats')) {
+    api.registerProvider('copy-desk.artistStats', readArtistStats);
+  }
+
   // Page asks resolve when the page's tweak ships (ADR 0341 D6). Re-registered
   // on every router build (tests rebuild it), never stacked.
   if (_askListenerOff) _askListenerOff();

package/modules/copy-desk/tests/copy_no_cms.mjs

@@ -287,7 +287,16 @@ await test('the Approval queue decides only through the port, and a send-back wr
 
 await test('the module manifest declares no seam another module could write copy through', () => {
   const manifest = JSON.parse(read('module.json'));
-  assert.deepEqual(manifest.provides, [], 'a provided port here would be a copy write path for every other module');
+  // ONE port, and it is a read of counts (task 1004433 / WA6.RP03): the
+  // profile's artist numbers. Anything more provided here would be a seam
+  // another module could reach copy through, so the list is pinned exactly and
+  // the provider is held to returning no wording below.
+  assert.deepEqual(manifest.provides, ['copy-desk.artistStats'], 'a provided port here would be a copy write path for every other module');
+  const stats = read('artist-stats.js');
+  assert.equal(/\b(pool|query|writeFile|appendFile|INSERT|UPDATE|DELETE)\b/.test(stats.replace(/\/\/.*$/gm, '')), false,
+    'the artist-stats port reads through other ports and writes nothing');
+  assert.equal(/\b(lines|before|after|reading|description|title)\s*:/.test(stats.replace(/\/\/.*$/gm, '')), false,
+    'the artist-stats port returns counts and sums, never wording');
   // R03 consumes `lifecycle` to create the proposal task. That direction is the
   // safe one and the point: this module can put a work request INTO the ledger,
   // and nothing can pull copy OUT of this module.

package/modules/economy/credits-by-craft.js

@@ -0,0 +1,208 @@
+'use strict';
+
+// modules/economy/credits-by-craft.js — WHICH CRAFT EARNED A BUILDER'S CREDITS
+// (task 1004433 / WA6.RP03, goal 1000095, criterion wa6-roles-read-true-in-public).
+//
+// WHY. builders.total_credits is one number, and every public surface read it as
+// "payout from shipped work". That is true for an engineer and false for the
+// other two crafts: an artist is paid per approved page (`tweak.page_approved:`),
+// an ideator per idea stream (`idea.credit.*`), and neither has to ship a task to
+// earn. The owner's 2026-09-30 rules need the split: a role other than the main
+// one shows (chip, Activity tab, leaderboard entry) only once it has EARNED
+// credits, and a leaderboard filtered to one role ranks by the credits earned in
+// that craft. So the split is a ledger fact, read here, once.
+//
+// THE RULE, per credit_log row:
+//
+//   tweak.page_approved:<task>          artist   (ADR 0341 D10, the artist lane)
+//   idea.credit.* · idea_promotion_bonus ideator  (ADR 0172, every idea stream,
+//                                                 the spark/developer split too)
+//   task.shipped · task.confirmed ·      the craft of the TASK's discipline
+//   ship.net_negative
+//   session.token_reward                 the craft of the tasks that session
+//                                        shipped, split evenly across them; a
+//                                        session that names none is engineering
+//                                        (an AI build session is, by default)
+//   anything else (achievement.*,        `other` — credited, but to no craft
+//   rank_change, a hand grant)
+//
+// A task's discipline maps to a craft through DISCIPLINE_CRAFT. `ui` is the
+// module-contributed design discipline (ADR 0079, 0272) and counts as ARTIST:
+// the artist's craft is how the project looks and reads (docs/packs/artist.md),
+// and UI design is that. A discipline this table does not know (a module may
+// contribute one later) counts as engineering, the default craft, rather than
+// vanishing from every total.
+//
+// THE SUM IS EXACT. A session's reward split across three tasks is a third each,
+// so the per-craft figures arrive as fractions. They are rounded by LARGEST
+// REMAINDER against the builder's true ledger total, so the crafts and `other`
+// always add up to exactly what the ledger holds. Rounding each craft on its own
+// would let the parts disagree with the whole by a credit, on a page that shows
+// both.
+//
+// ONLY READS. Nothing here writes, and nothing is reachable from a ship path.
+
+const api = require('../../src/module-api');
+const { pool } = api;
+const { ARTIST_PAGE_REASON_PREFIX } = require('./credits');
+
+const CRAFTS = Object.freeze(['engineer', 'artist', 'ideator']);
+const DEFAULT_CRAFT = 'engineer';
+const OTHER = 'other';
+
+const DISCIPLINE_CRAFT = Object.freeze({
+  engineer: 'engineer',
+  artist: 'artist',
+  ui: 'artist',
+  ideator: 'ideator',
+});
+
+// The per-task reasons whose craft is the task's own. The same three the
+// lifecycle's CREDITS_AWARDED_SUBQUERY sums as a task's payout.
+const TASK_REASONS = Object.freeze(['task.shipped', 'task.confirmed', 'ship.net_negative']);
+
+// The craft a builder's PREFERRED discipline names, or null for one that is not
+// a craft at all. The same table, read the other way round: an unknown
+// discipline is engineering money (above) but is no role chip. core's
+// src/bongos/role-stats.js asks this through the reward port, so the ui-is-artist
+// rule has exactly one home.
+function craftForPreference(discipline) {
+  return DISCIPLINE_CRAFT[discipline] || null;
+}
+
+function craftOfDiscipline(discipline) {
+  if (discipline === OTHER) return OTHER;
+  return DISCIPLINE_CRAFT[discipline] || DEFAULT_CRAFT;
+}
+
+// The artist prefix goes into the SQL as a LIKE pattern, so its underscore (a
+// LIKE wildcard) is escaped, the idea-size.js rule. Checked at load: the prefix
+// is economy's own constant, never a request value.
+if (!/^[a-z0-9_.]+:$/i.test(ARTIST_PAGE_REASON_PREFIX)) {
+  throw new Error('economy/credits-by-craft: the artist reason prefix is not a plain literal');
+}
+const ARTIST_LIKE = ARTIST_PAGE_REASON_PREFIX.replace(/([\\%_])/g, '\\$1') + '%';
+
+// One statement for the whole set of builders. Each ledger row becomes one or
+// more (builder, discipline, amount) parts, then they are grouped. The session
+// branch is the only one that fans out: one row per task its session shipped.
+//
+// THE INDEXES IT RIDES, all pre-existing, so this needs no migration: both
+// branches filter `cl.builder_id = ANY($1)`, served by idx_credit_log_builder
+// (builder_id, recorded_at) from migrations/003_pms.sql, so the read is that
+// person's rows, never the whole ledger; the task join is the tasks primary
+// key, and the session join is session_records' UNIQUE (session_id) from
+// migrations/062_session_records.sql. tests/profile_role_stats.mjs pins both
+// index definitions, so dropping either reds a test rather than going quiet.
+const CREDITS_BY_CRAFT_SQL = `
+  WITH parts AS (
+    SELECT cl.builder_id,
+           cl.delta::numeric AS amount,
+           CASE
+             WHEN cl.reason LIKE $2 THEN 'artist'
+             WHEN cl.reason LIKE 'idea.credit.%' OR cl.reason = 'idea_promotion_bonus' THEN 'ideator'
+             WHEN cl.reason = ANY($3::text[]) THEN COALESCE(t.discipline, '${DEFAULT_CRAFT}')
+             ELSE '${OTHER}'
+           END AS discipline
+      FROM credit_log cl
+      LEFT JOIN tasks t ON t.id = cl.task_id
+     WHERE cl.builder_id = ANY($1::bigint[])
+       AND cl.reason <> 'session.token_reward'
+    UNION ALL
+    SELECT cl.builder_id,
+           cl.delta::numeric / GREATEST(COALESCE(cardinality(sr.task_ids), 0), 1) AS amount,
+           COALESCE(st.discipline, '${DEFAULT_CRAFT}') AS discipline
+      FROM credit_log cl
+      LEFT JOIN session_records sr ON sr.session_id = cl.session_id
+      LEFT JOIN LATERAL unnest(COALESCE(sr.task_ids, '{}'::bigint[])) AS u(task_id) ON true
+      LEFT JOIN tasks st ON st.id = u.task_id
+     WHERE cl.builder_id = ANY($1::bigint[])
+       AND cl.reason = 'session.token_reward'
+  )
+  SELECT builder_id, discipline, SUM(amount)::float8 AS amount
+    FROM parts
+   GROUP BY builder_id, discipline`;
+
+// apportion — round fractional parts to integers that sum to `total` exactly
+// (largest remainder; ties go to the earlier key, so the answer is stable).
+// Pure. `parts` is { key: number }, in the order keys should win ties.
+function apportion(parts, total) {
+  const keys = Object.keys(parts);
+  const out = {};
+  let floorSum = 0;
+  const rema = [];
+  keys.forEach((k, i) => {
+    const v = Number(parts[k]) || 0;
+    const f = Math.floor(v);
+    out[k] = f;
+    floorSum += f;
+    rema.push({ k, r: v - f, i });
+  });
+  // When `total` is the rounded sum of the parts (the only way this file calls
+  // it), `left` is round(sum of remainders), so 0 <= left <= keys.length and one
+  // pass hands out every unit.
+  const left = Math.round(Number(total) || 0) - floorSum;
+  rema.sort((a, b) => b.r - a.r || a.i - b.i);
+  for (let j = 0; j < left && j < rema.length; j++) out[rema[j].k] += 1;
+  return out;
+}
+
+// foldCraftRows — the grouped SQL rows into one exact row per builder. Pure,
+// so the rounding and the discipline mapping are testable without a database.
+// Returns Map<builderIdString, { engineer, artist, ideator, other, total }>,
+// with every builder asked for present (at zero when they have earned nothing:
+// "no credits" is an answer, not a gap).
+function foldCraftRows(ids, rows) {
+  const raw = new Map();
+  for (const id of ids) {
+    const parts = {};
+    for (const c of CRAFTS) parts[c] = 0;
+    parts[OTHER] = 0;
+    raw.set(id, parts);
+  }
+  for (const r of rows || []) {
+    const parts = raw.get(String(r.builder_id));
+    if (!parts) continue;
+    parts[craftOfDiscipline(r.discipline)] += Number(r.amount) || 0;
+  }
+  const out = new Map();
+  for (const [id, parts] of raw) {
+    const total = Math.round(Object.values(parts).reduce((a, b) => a + b, 0));
+    out.set(id, { ...apportion(parts, total), total });
+  }
+  return out;
+}
+
+function idOf(v) {
+  return /^[1-9]\d*$/.test(String(v)) ? String(v) : null;
+}
+
+// creditsByCraft — the split for MANY builders in ONE query. The leaderboard's
+// role toggle (RP07) asks for a page of builders at once, the profile for one.
+async function creditsByCraft(builderIds, { client = null } = {}) {
+  const ids = [...new Set((Array.isArray(builderIds) ? builderIds : [builderIds]).map(idOf).filter(Boolean))];
+  if (ids.length === 0) return new Map();
+  const q = client || pool;
+  const { rows } = await q.query(CREDITS_BY_CRAFT_SQL, [ids, ARTIST_LIKE, TASK_REASONS]);
+  return foldCraftRows(ids, rows);
+}
+
+// The crafts a builder has EARNED in, in CRAFTS order. The owner's rule is that
+// a role other than the main one shows only once it has earned credits; this is
+// the "has earned" half, and the only place it is decided.
+function earnedCrafts(row) {
+  if (!row) return [];
+  return CRAFTS.filter((c) => Number(row[c]) > 0);
+}
+
+module.exports = {
+  creditsByCraft,
+  foldCraftRows,
+  apportion,
+  craftOfDiscipline,
+  craftForPreference,
+  earnedCrafts,
+  CRAFTS,
+  DISCIPLINE_CRAFT,
+  CREDITS_BY_CRAFT_SQL,
+};

package/modules/economy/reward.js

@@ -22,6 +22,7 @@ const streak = require('./streak');
 const ideaSizeLib = require('./idea-size');
 const ideaSizeHistorical = require('./idea-size-historical');
 const ideaBrightnessLib = require('./idea-brightness');
+const creditsByCraftLib = require('./credits-by-craft');
 
 module.exports = {
   // credit allocation — transaction-participant: caller passes its tx `client`
@@ -125,6 +126,13 @@ module.exports = {
   // still alive.
   ideaBrightness: (...a) => ideaBrightnessLib.ideaBrightness(...a),
   ideaBrightnesses: (...a) => ideaBrightnessLib.ideaBrightnesses(...a),
+  // WHICH CRAFT EARNED IT (task 1004433 / WA6.RP03). total_credits split into
+  // engineer / artist / ideator / other, exact to the ledger. The profile reads
+  // it to decide which roles show; the leaderboard's role toggle ranks by it.
+  creditsByCraft: (...a) => creditsByCraftLib.creditsByCraft(...a),
+  earnedCrafts: (...a) => creditsByCraftLib.earnedCrafts(...a),
+  craftForPreference: (...a) => creditsByCraftLib.craftForPreference(...a),
+  get CRAFTS() { return creditsByCraftLib.CRAFTS; },
   computeStreak: (...a) => streak.computeStreak(...a),
   wouldExtendStreak: (...a) => streak.wouldExtendStreak(...a),
 };