@bongos/core 1.21.4 → 1.21.5

package/modules/autonomy/governor-docket.js

@@ -0,0 +1,101 @@
+'use strict';
+
+// modules/autonomy/governor-docket.js — the autonomy module's part of the
+// governor's docket (task 1004523, goal 1000125; collector:
+// modules/government/docket.js, decision: ADR 0362).
+//
+// WHY. Two things the Governor City shows live here. The Autobongos FENCE stands
+// at Automation, and it is a state rather than a queue, so it becomes a matter
+// only when it needs a governor: the switch is off, or it is on with no goal
+// allowed (nothing can build either way). And the "money" reading: the one
+// budget this project actually records is the unattended-spend ceiling the
+// autonomy gate brakes on (scripts/gds/autonomy-gate.js `ceilingUsd`), against
+// the month's unattended spend (economy's `autonomousApiSpendMtd`, through the
+// `reward` port). So "money left" is honestly "what unattended building may still
+// spend this month" — the project has no wider budget to count down from, and the
+// line says so rather than inventing one.
+//
+// Contributed to the `governor.docket` point from the autonomy route factory (a
+// module never requires a sibling, ADR 0083). Pure mappers exported for tests.
+
+const api = require('../../src/module-api');
+const db = require('./db');
+const autonomyGate = require('../../scripts/gds/autonomy-gate');
+
+const POINT = 'governor.docket';
+
+// The fence as matters for one viewer. Pure. Only a holder of
+// `autonomy.fence.manage` (the switch's own atom) is told it needs them.
+function fenceDocketMatters(project, mayManage) {
+  const goals = Array.isArray(project.goals) ? project.goals : [];
+  let title = null;
+  let where = null;
+  if (project.enabled === false) {
+    title = 'Unattended building is switched off';
+    where = project.paused_reason ? `automation · the switch · ${project.paused_reason}` : 'automation · the switch';
+  } else if (!goals.length) {
+    title = 'Unattended building is on, but no goal is allowed';
+    where = 'automation · allowed goals';
+  }
+  if (!title) return [];
+  return [{
+    id: 'fence',
+    rule: 'decide',
+    state: mayManage ? 'needs' : 'settled',
+    title,
+    short: 'the switch',
+    where,
+    opened_at: project.updated_at || null,
+    deadline: null,
+    proposer: project.updated_by == null ? null : { id: project.updated_by },
+    tally: null,
+    href: '/watch',
+    ref: { type: 'autonomy_fence', id: 'project' },
+  }];
+}
+
+// Money left under the unattended-spend ceiling. Pure. Hot when under a fifth left.
+function moneyReading({ ceilingUsd, spentUsd }) {
+  const ceiling = Number(ceilingUsd) || 0;
+  const spent = Math.max(0, Number(spentUsd) || 0);
+  const left = Math.max(0, ceiling - spent);
+  const usd = (n) => `$${n.toFixed(2).replace(/\.00$/, '')}`;
+  return {
+    value: { left_usd: left, spent_usd: spent, ceiling_usd: ceiling, scope: 'unattended building, this month' },
+    figure: `${usd(left)} left`,
+    line: `unattended building this month · ${usd(spent)} of ${usd(ceiling)} spent`,
+    hot: ceiling > 0 && left / ceiling < 0.2,
+  };
+}
+
+function contributeAutonomyToDocket() {
+  // GET /autonomy/fence is any builder's read; the read itself fails on a missing
+  // fence row rather than fabricating "off" (that route's rule).
+  api.contribute(POINT, {
+    source: 'autobongos_fence',
+    building: 'automation',
+    gate: { anyBuilder: true },
+    read: async (ctx) => {
+      const project = await db.readFence();
+      if (!project) throw new Error('fence_uninitialised');
+      return fenceDocketMatters(project, ctx.has('autonomy.fence.manage'));
+    },
+  });
+  // The ceiling and the month's unattended spend are what GET /autonomy/precheck
+  // answers, so the reading carries that route's atom.
+  api.contribute(POINT, {
+    reading: 'money',
+    gate: { permission: 'autonomy.precheck' },
+    read: async () => {
+      const reward = api.resolveOptional('reward');
+      if (!reward || typeof reward.autonomousApiSpendMtd !== 'function') throw new Error('economy_off');
+      return moneyReading({ ceilingUsd: autonomyGate.ceilingUsd(), spentUsd: await reward.autonomousApiSpendMtd() });
+    },
+  });
+}
+
+module.exports = {
+  contributeAutonomyToDocket,
+  fenceDocketMatters,
+  moneyReading,
+};

package/modules/autonomy/routes/autonomy.js

@@ -101,7 +101,12 @@ function commitOrNull(v) {
   return typeof v === 'string' && /^[0-9a-f]{40}$/.test(v) ? v : null;
 }
 
+// The governor's docket (task 1004523): the fence + the money reading,
+// contributed from this factory (see ../governor-docket.js).
+const governorDocket = require('../governor-docket');
+
 module.exports = function buildAutonomyRouter() {
+  governorDocket.contributeAutonomyToDocket();
   const router = express.Router();
 
   router.get('/autonomy/precheck', auth.requireBuilder, auth.requirePermission('autonomy.precheck'), async (req, res) => {

package/modules/discord/board-broadcast.js

@@ -244,4 +244,6 @@ async function postBoardOutcome(payload, deps = {}) {
   return result;
 }
 
-module.exports = { postBoardAnnouncement, postBoardOutcome, composeOutcomeLine };
+// plainName is shared with craft-broadcast.js (task 1004439): one sanitizer for
+// every builder name this module puts on a channel.
+module.exports = { postBoardAnnouncement, postBoardOutcome, composeOutcomeLine, plainName };

package/modules/discord/craft-broadcast.js

@@ -0,0 +1,107 @@
+// modules/discord/craft-broadcast.js — the feed hears an artist's and an
+// ideator's moments, not only shipped tasks (task 1004439 / WA6.RP09, goal
+// 1000095, criterion wa6-roles-read-true-in-public).
+//
+// WHY. #ship-feed posts one line per shipped task, and nothing when the board
+// ratifies an idea or a Full Idea passes its completeness bar. An ideator's best
+// moments happened in silence while an engineer's every ship was announced. (A
+// page approved in Tweak Mode DOES ship as a task; ship-broadcast.js names its
+// artist on that line, task 1004432's author of record.)
+//
+// THE LINES, owner audience, no jargon:
+//   board.item.passed (a full_idea)   🏛️ The board ratified an idea by <name>. <link>
+//   idea.graded.full (at the bar)     📜 <name>'s Full Idea passed its completeness check. <link>
+//
+// PRIVACY, the existing feed's rules: #ship-feed is the BUILDERS' channel (not
+// #ship-news), so naming a builder by their display name is what it already does
+// for the Board Room's members. The idea's TITLE is never posted — an idea may sit
+// in a private goal, and the hall link is gated where the idea is; the line says
+// THAT it happened and who, and the link carries the rest to whoever may see it.
+// A line never starts with `#<id>`, so the applause bot does not read it as a ship.
+//
+// BEST-EFFORT, like every broadcast in this module: it never throws, so a Discord
+// hiccup can never fail a ratification or a grade — both are durable rows already
+// written when their events fire.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const webhook = require('./webhook');
+const { plainName } = require('./board-broadcast');
+
+const CHANNEL = 'ship_feed';
+
+function ideaLink(ideaId) {
+  const origin = ((api.branding && api.branding().domains) || {}).buildersOrigin || '';
+  return `${origin ? origin.replace(/\/$/, '') : ''}/#/idea/${encodeURIComponent(ideaId)}`;
+}
+
+// PURE. The two lines, from what the caller already resolved.
+function composeRatifiedLine({ ideaId, author }) {
+  const by = author ? ` by ${plainName(author)}` : '';
+  return `\u{1F3DB}\u{FE0F} The board ratified an idea${by}. ${ideaLink(ideaId)}`;
+}
+function composeFullIdeaLine({ ideaId, author }) {
+  const who = author ? `${plainName(author)}'s Full Idea` : 'A Full Idea';
+  return `\u{1F4DC} ${who} passed its completeness check. ${ideaLink(ideaId)}`;
+}
+
+// The display name for a builder id, or null: a missing or unreadable builder
+// leaves the line unnamed rather than failing it.
+async function nameOf(builderId, deps) {
+  if (builderId == null) return null;
+  try {
+    const getBuilder = deps.getBuilder || ((id) => api.getBuilderById(id));
+    const b = await getBuilder(builderId);
+    return b ? (b.display_name || b.github_login || null) : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+async function post(line, deps, result, what) {
+  const log = deps.log || console.log;
+  const hasChannel = deps.hasChannel || webhook.hasWebhook;
+  try {
+    if (!hasChannel(CHANNEL)) { result.skipped = 'channel_not_configured'; return result; }
+    const send = deps.post || webhook.postWebhook;
+    await send(CHANNEL, line);
+    result.posted = true;
+  } catch (e) {
+    result.skipped = 'post_failed';
+    log(`[discord] ${what}: #ship-feed post failed (non-blocking): ${e && e.message ? e.message : e}`);
+  }
+  return result;
+}
+
+// board.item.passed — the pass contract's seven fields. Only a Full Idea is an
+// ideator's moment: an amendment or a genesis stage is the project's decision,
+// and posts nothing here (the Board Room's own channel already carries it).
+async function postIdeaRatified(payload, deps = {}) {
+  const result = { posted: false, skipped: null };
+  if (!payload || payload.subject_type !== 'full_idea' || payload.idea_id == null) {
+    result.skipped = 'not_an_idea';
+    return result;
+  }
+  const author = await nameOf(payload.author_id, deps);
+  return post(composeRatifiedLine({ ideaId: payload.idea_id, author }), deps, result, 'idea ratified');
+}
+
+// idea.graded.full — fired once per real spark→full transition. It is a pass
+// only at or above economy's bar (the same bar the full-pass credit pays at,
+// read through the reward port; without economy there is no bar to pass, so
+// nothing is announced). The author is the developer when someone else developed
+// the spark, as the credit split names them.
+async function postFullIdeaPassed(graded, deps = {}) {
+  const result = { posted: false, skipped: null };
+  const ideaId = graded && (graded.idea_id != null ? graded.idea_id : graded.id);
+  if (ideaId == null) { result.skipped = 'no_idea'; return result; }
+  const reward = deps.reward || api.resolveOptional('reward');
+  const bar = reward && Number(reward.IDEA_FULL_PASS_BAR);
+  const score = graded.completeness_score == null ? NaN : Number(graded.completeness_score);
+  if (!Number.isFinite(bar) || !Number.isFinite(score) || score < bar) { result.skipped = 'below_bar'; return result; }
+  const author = await nameOf(graded.developed_by != null ? graded.developed_by : graded.captured_by, deps);
+  return post(composeFullIdeaLine({ ideaId, author }), deps, result, 'full idea passed');
+}
+
+module.exports = { postIdeaRatified, postFullIdeaPassed, composeRatifiedLine, composeFullIdeaLine };

package/modules/discord/routes/discord.js

@@ -21,6 +21,7 @@ const auth = require('../auth');
 const db = require('../db');
 const shipBroadcast = require('../ship-broadcast');
 const boardBroadcast = require('../board-broadcast');
+const craftBroadcast = require('../craft-broadcast');
 const roleSync = require('../discord-role-sync');
 const webhook = require('../webhook');
 
@@ -50,6 +51,8 @@ let _strandListenerOff = null;
 let _roleSyncListenerOff = null;
 let _boardListenerOff = null;
 let _boardCloseListenerOff = null;
+let _ideaRatifiedListenerOff = null;
+let _fullIdeaListenerOff = null;
 function registerSeams() {
   if (!api.hasProvider('discord.isLinked')) {
     api.registerProvider('discord.isLinked', async (builderId) => !!(await db.getDiscordLink(builderId)));
@@ -98,6 +101,13 @@ function registerSeams() {
   // well as a pass; still outbound only, still nothing cast from Discord.
   if (_boardCloseListenerOff) _boardCloseListenerOff();
   _boardCloseListenerOff = api.on('board.item.closed', (payload) => boardBroadcast.postBoardOutcome(payload));
+  // task 1004439: the ideator's moments reach #ship-feed beside the ships — a
+  // ratified idea (the pass contract's event; a mirror reads it, nothing here
+  // pays) and a Full Idea at the bar. Outbound only, best-effort.
+  if (_ideaRatifiedListenerOff) _ideaRatifiedListenerOff();
+  _ideaRatifiedListenerOff = api.on('board.item.passed', (payload) => craftBroadcast.postIdeaRatified(payload));
+  if (_fullIdeaListenerOff) _fullIdeaListenerOff();
+  _fullIdeaListenerOff = api.on('idea.graded.full', (graded) => craftBroadcast.postFullIdeaPassed(graded));
   if (_roleSyncListenerOff) _roleSyncListenerOff();
   _roleSyncListenerOff = api.on('builder.role-sync-needed', ({ builderId }) =>
     roleSync.syncBuilderRole(builderId).catch((e) =>

package/modules/discord/ship-broadcast.js

@@ -30,17 +30,43 @@
 // For now #ship-news gets nothing so exactly one #ship-feed message fires per
 // ship. The broader "make the two channels genuinely different + filter by task
 // type" work is idea 458 — un-pause by restoring the ship_news entry below.
-function chooseBroadcastTargets({ securitySensitive, taskId, summary }) {
+//
+// A PAGE TWEAK (task 1004439): an approved Tweak Mode round ships as a task, and
+// its line says what it is — a page approved, rewritten by its ARTIST (the round's
+// author of record, task 1004432's shipped_by), never the session that applied it.
+// `pageArtist` is the artist's name already resolved, or null when it could not be
+// read; the line then says "page approved" and names nobody rather than the
+// applier. Still `#<id>`-prefixed, so applause on it reaches the round.
+function chooseBroadcastTargets({ securitySensitive, taskId, summary, pageTweak = false, pageArtist = null }) {
   if (!summary) return [];
   if (securitySensitive) {
     return [{ channel: 'security_ship_feed', line: `#${taskId} shipped (security) — ${summary}` }];
   }
+  if (pageTweak) {
+    const by = pageArtist ? ` — rewritten by ${plainName(pageArtist)}` : '';
+    return [{ channel: 'ship_feed', line: `#${taskId} page approved${by}: ${summary}` }];
+  }
   return [
     // { channel: 'ship_news', line: summary },  // PAUSED — task 1749 / idea 458
     { channel: 'ship_feed', line: `#${taskId} shipped — ${summary}` },
   ];
 }
 
+// The page-tweak source string, and the artist's display name for a shipped
+// round, or null — an unreadable builder leaves the line unnamed, never fails it.
+const PAGE_TWEAK_SOURCE = 'page-tweak';
+async function pageArtistName(task, deps) {
+  if (task.shipped_by == null) return null;
+  try {
+    const getBuilder = deps.getBuilder || ((id) => require('../../src/module-api').getBuilderById(id));
+    const b = await getBuilder(task.shipped_by);
+    return b ? (b.display_name || b.github_login || null) : null;
+  } catch (_) {
+    return null;
+  }
+}
+function plainName(name) { return require('./board-broadcast').plainName(name); }
+
 // Best-effort server-side broadcast for a task that just landed via server-
 // mediated publish. `task` is the shipTask() row: { id, value_summary,
 // security_sensitive, ... }. deps.postWebhook (the scripts/discord/lib poster) and
@@ -61,7 +87,9 @@ async function postShipBroadcast(task, deps = {}) {
 
   const postWebhook = deps.postWebhook || require('./webhook').postWebhook;
   const log = deps.log || console.log;
-  const targets = chooseBroadcastTargets({ securitySensitive: sec, taskId: task.id, summary });
+  const pageTweak = task.source === PAGE_TWEAK_SOURCE;
+  const pageArtist = pageTweak && sec === false ? await pageArtistName(task, deps) : null;
+  const targets = chooseBroadcastTargets({ securitySensitive: sec, taskId: task.id, summary, pageTweak, pageArtist });
   for (const { channel, line } of targets) {
     try {
       await postWebhook(channel, line);

package/modules/economy/reward.js

@@ -72,6 +72,9 @@ module.exports = {
   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; },
+  // task 1004439: the completeness a Full Idea must reach to pass, so the Discord
+  // feed announces a pass at exactly the bar the full-pass credit pays at.
+  get IDEA_FULL_PASS_BAR() { return credits.IDEA_FULL_PASS_BAR; },
 
   // --- READ surface the core me/public/builders/sessions routes resolve through
   //     this same port (one economy port; the grading precedent registers the

package/modules/government/board.js

@@ -1349,6 +1349,21 @@ async function boardPassForIdea(ideaId) {
 //   - this builder is not the subject's author (the anti-self-vote line, §3)
 // Fail-closed on an unreadable constitution: parseMembershipPredicate yields
 // nobody, so a malformed snapshot summons no one rather than everyone.
+//
+// THE RULE ITSELF is `awaitsVoter` below, and it is the ONE definition: the
+// governor's docket (docket.js, task 1004523) asks it too, so the city's
+// "needs you" and this summons cannot disagree about who must act.
+// tests/governor_docket.mjs drives both over the same matrix.
+
+// Pure: does this sitting wait on this builder's vote? Open and not past its
+// deadline, a member under the item's OWN snapshot, not already cast, and not
+// the subject's author (null author = nobody to hold back: a genesis stage).
+function awaitsVoter({ builderId, authorId = null, alreadyVoted = false, isMember = false, closed = false, expired = false } = {}) {
+  if (builderId === null || builderId === undefined || builderId === '') return false;
+  if (closed || expired || alreadyVoted || !isMember) return false;
+  return !(authorId != null && String(authorId) === String(builderId));
+}
+
 async function pendingVotesFor(builderId) {
   const empty = Object.freeze({ count: 0, first_item_id: null });
   if (builderId === null || builderId === undefined || builderId === '') return empty;
@@ -1367,16 +1382,15 @@ async function pendingVotesFor(builderId) {
   const membershipCache = new Map();
   const votable = [];
   for (const row of rows) {
-    if (row.already_voted) continue;
-    // The author does not vote on their own item (§3). Null author = nobody to
-    // disqualify, so the item stays votable.
-    if (row.author_id != null && String(row.author_id) === String(builderId)) continue;
+    // Cheap refusals first, so membership is resolved only for a row that could
+    // still be votable (the SQL already dropped closed and past-deadline items).
+    if (!awaitsVoter({ builderId, authorId: row.author_id, alreadyVoted: !!row.already_voted, isMember: true })) continue;
     const constitution = row.constitution || {};
     const key = String(constitution.membership || '');
     if (!membershipCache.has(key)) {
       membershipCache.set(key, await isBoardMember(builderId, constitution).catch(() => false));
     }
-    if (!membershipCache.get(key)) continue;
+    if (!awaitsVoter({ builderId, authorId: row.author_id, alreadyVoted: !!row.already_voted, isMember: membershipCache.get(key) })) continue;
     votable.push(row);
   }
   if (!votable.length) return empty;
@@ -1392,6 +1406,7 @@ module.exports = {
   openGenesisStageClose,
   genesisStageStatus,
   pendingVotesFor,
+  awaitsVoter,
   hasMajority,
   majorityDecided,
   decidingVotes,

package/modules/government/docket-vocab.js

@@ -0,0 +1,82 @@
+'use strict';
+
+// modules/government/docket-vocab.js — the Governor City's fixed words: the nine
+// civic buildings in street order, the seven ways a matter is decided, the three
+// states a matter can be in for one viewer, and the six readings (task 1004523,
+// goal 1000125).
+//
+// WHY. The docket (docket.js) is the one server read every Governor City screen
+// draws from — the home city's pins, the street, the building interiors, the
+// floors and the matter cards (tasks 1004524-1004528). Those screens must agree
+// on what a building key, a rule key or a state key MEANS, so the vocabulary is
+// declared once, here, and shipped on the response (`vocabulary`) so a page builds
+// its legend from the server instead of retyping it. The words and their order are
+// the reference design's (docs/design/mocks/governor-city/README.md, "The street"
+// and "Decision glyphs"); a change here is a change to the design of record.
+//
+// Pure data, no requires: browser-side copies are held equal by test, never by
+// hand.
+
+// The nine civic buildings, in the order work moves along the street, each under
+// its street group label.
+const BUILDINGS = Object.freeze([
+  Object.freeze({ key: 'charter', name: 'Charter', group: 'how we decide' }),
+  Object.freeze({ key: 'rules', name: 'Rules', group: 'how we decide' }),
+  Object.freeze({ key: 'disputes', name: 'Disputes', group: 'how we decide' }),
+  Object.freeze({ key: 'people', name: 'People', group: 'who and what' }),
+  Object.freeze({ key: 'planning', name: 'Planning', group: 'who and what' }),
+  Object.freeze({ key: 'automation', name: 'Automation', group: 'the work' }),
+  Object.freeze({ key: 'review', name: 'Review', group: 'checks and going live' }),
+  Object.freeze({ key: 'release', name: 'Release', group: 'checks and going live' }),
+  Object.freeze({ key: 'treasury', name: 'Treasury', group: 'money' }),
+]);
+const BUILDING_KEYS = Object.freeze(BUILDINGS.map((b) => b.key));
+
+// How a matter is decided — the seven decision glyphs.
+const RULES = Object.freeze([
+  Object.freeze({ key: 'decide', words: 'one person decides' }),
+  Object.freeze({ key: 'first', words: 'first yes wins' }),
+  Object.freeze({ key: 'consent', words: 'passes unless someone objects' }),
+  Object.freeze({ key: 'majority', words: 'more than half must say yes' }),
+  Object.freeze({ key: 'unanimous', words: 'everyone has to agree' }),
+  Object.freeze({ key: 'signoff', words: 'signed off by someone who did not build it' }),
+  Object.freeze({ key: 'rule', words: 'settled by a rule' }),
+]);
+const RULE_KEYS = Object.freeze(RULES.map((r) => r.key));
+
+// The board's pass rules (config.js PASS_RULES) in the city's words. An unknown
+// pass rule maps to null — the card then says the rule is not one it knows,
+// rather than drawing the nearest glyph.
+const PASS_RULE_TO_RULE = Object.freeze({
+  first_ratifier: 'first',
+  consent: 'consent',
+  majority: 'majority',
+  unanimous: 'unanimous',
+});
+
+// A matter's state for ONE viewer. Exactly one applies (README "Pins").
+//   needs   — waits on the viewer's own act
+//   moving  — open, and moving without the viewer (they acted, or it is a call
+//             they share that is not theirs to make right now)
+//   settled — decided, or not the viewer's to act on
+const STATES = Object.freeze(['needs', 'moving', 'settled']);
+
+// The six readings on the street's footer, each a door to the building it reads.
+const READINGS = Object.freeze([
+  Object.freeze({ key: 'flow', label: 'flow', building: 'review' }),
+  Object.freeze({ key: 'promises', label: 'promises', building: 'planning' }),
+  Object.freeze({ key: 'money', label: 'money', building: 'treasury' }),
+  Object.freeze({ key: 'people', label: 'people', building: 'people' }),
+  Object.freeze({ key: 'fairness', label: 'fairness', building: 'disputes' }),
+  Object.freeze({ key: 'rules', label: 'rules at work', building: 'rules' }),
+]);
+
+module.exports = {
+  BUILDINGS,
+  BUILDING_KEYS,
+  RULES,
+  RULE_KEYS,
+  PASS_RULE_TO_RULE,
+  STATES,
+  READINGS,
+};