@bongos/core 1.21.112 → 1.21.114

package/modules/government/routes/government.js

@@ -25,11 +25,21 @@ const db = require('../db');
 const sessionScopes = require('../session-scopes');
 const boardMembership = require('../board-membership');
 const board = require('../board');
+const laws = require('../laws');
+const presets = require('../presets');
 const boardWithdraw = require('../board-withdraw');
 const recommendations = require('../recommendations');
 const docket = require('../docket');
+const counts = require('../counts');
+const asks = require('../asks');
+const asksDb = require('../asks-db');
+const routing = require('../routing');
 const governmentConfig = require('../config');
 const membershipPredicate = require('../membership-predicate');
+const positions = require('../positions');
+const decisionBoard = require('../decision-board');
+const treasury = require('../treasury');
+const treasuryDb = require('../treasury-db');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('government');
 
@@ -130,8 +140,51 @@ const governmentPort = {
   // building's own direct route runs before letting one builder act alone.
   decisionRulesView: board.decisionRulesView,
   checkActAlone: board.checkActAlone,
+  // task 1004707 — the laws every AI session reads. GET /me carries this block
+  // and the Conductor relays its contract verbatim; builder-settings enforces
+  // each law's locks on the builder's personal settings. Read per request,
+  // uncached (a law passed a moment ago is in the next read). Read-only: a law
+  // is written only by a passed amendment (law-board.js), never through here.
+  lawsForSession: async () => laws.forSession(await db.listLaws()),
+  // task 1004713 — the POSITIONS a builder holds (positions.js): owner, Lead,
+  // a building's sitting, the board. GET /me carries it so the hall shows the
+  // governing surfaces only to a seat holder. Read per request, uncached; null
+  // when a read failed (unknown, never "none"). Grants nothing.
+  positionsFor: (builderId) => positions.readPositions(builderId, {
+    listLeads: () => db.listLeads(),
+    listActiveArchons: () => db.listActiveArchons(),
+    board: () => governmentConfig.loadGovernmentConfig().board || {},
+    decisions: (b) => decisionBoard.decisionRulesFor(b),
+    sits: (id, membership) => boardMembership.isBoardMember(id, { membership }),
+  }),
+  // task 1004703 — THE ASK. The one shape every request from an agent to a person
+  // takes (asks.js). A module that files such a request (ideas' POST /blockers)
+  // checks it here, refuses slop with refusalLine's words, stores it per docket
+  // matter, and reads it back for its own list. Authority stays with the filing
+  // route: these only check, store and read the shape.
+  checkAsk: asks.checkAsk,
+  refusalLine: asks.refusalLine,
+  // task 1004704: what a hand filing from an AI session must carry, in plain words.
+  askRequiredMessage: asks.ASK_REQUIRED_MESSAGE,
+  saveAsk: (...a) => asksDb.saveAsk(...a),
+  asksFor: (...a) => asksDb.asksFor(...a),
 };
 
+// An ask arrives bare, or wrapped as { ask } (the shape POST /blockers takes it in).
+function askBody(req) {
+  const b = req.body;
+  return b && typeof b === 'object' && b.ask !== undefined ? b.ask : b;
+}
+// The one refusal every ask route answers with: 400 `ask_refused`, the fixes in
+// plain words as the message, and every broken rule as details.
+function refuseAsk(res, verdict) {
+  return res.fail('ask_refused', {
+    status: 400,
+    message: asks.refusalLine(verdict.errors),
+    details: { errors: verdict.errors, rules: asks.ASK_RULES },
+  });
+}
+
 function registerSeams() {
   if (!api.hasProvider('government')) {
     api.registerProvider('government', governmentPort);
@@ -198,8 +251,37 @@ function contributeRankDesk() {
   });
 }
 
+// THE TREASURY'S SPENDING MATTERS (task 1004712, ADR 0379): every open borrow a
+// dry pot filed, as a docket matter at the Treasury, under the treasury read's own
+// atom. Its acts go only to a viewer who sits in the seat its stored ask waits on
+// (routing.resolveSeat over the real seats, read per request); the answer route
+// checks the same again, so the docket only hides what would be refused.
+function contributeTreasury() {
+  api.contribute('governor.docket', {
+    source: treasury.MATTER_SOURCE,
+    building: 'treasury',
+    gate: { permission: 'board.vote.cast' },
+    read: async (ctx) => {
+      const open = await treasuryDb.openBorrowRows();
+      if (!open.length) return [];
+      const seats = await docket.loadSeats({ holders: {} });
+      return open.map(({ row, ask }) => {
+        const r = seats ? routing.resolveSeat((ask && ask.waits_on) || treasury.SEAT, seats) : null;
+        return treasury.borrowMatter(row, { title: row.title, canAnswer: !!(r && r.builder_ids.includes(String(ctx.builderId))) });
+      });
+    },
+  });
+}
+
+// Who answers for the Treasury today: its Lead, or the owner seat while unseated.
+async function treasuryHolder() {
+  const seats = await docket.loadSeats({ holders: {} });
+  return seats ? routing.resolveSeat(treasury.SEAT, seats) : null;
+}
+
 module.exports = function buildGovernmentRouter() {
   contributeRankDesk();
+  contributeTreasury();
   registerSeams();
   const router = express.Router();
 
@@ -663,7 +745,9 @@ module.exports = function buildGovernmentRouter() {
   //     matters: [{ id: '<source>:<id>', source, building, rule, state,
   //                 title, short, where, opened_at, deadline,
   //                 proposer: { id, login, name } | null,
-  //                 tally: { for, against, open, needs } | null, href, ref }],
+  //                 tally: { for, against, open, needs } | null, href, ref,
+  //                 ask?: { question, options, recommend, waits_on,      // task 1004703:
+  //                         if_nobody_answers, detail, written_at } }],   // the stored ask
   //     buildings: [{ key, name, group, counts, matter_ids }],   // street order
   //     sources:  [{ source, building, label, status, count, reason }],
   //               // status: live | not_yours | coming | off | unavailable
@@ -682,6 +766,96 @@ module.exports = function buildGovernmentRouter() {
     }
   });
 
+  // rank: perm board.vote.cast — the government's COUNTS in one read (task 1004716):
+  // what is on the viewer ("to do"), what waits on others, what is to decide, how
+  // many agents are working and how much is moving. The docket's own atom and its
+  // own per-source gates (counts.countsFor reads the docket this viewer would), so
+  // a count never includes a matter the viewer could not see.
+  // Response: { viewer: { id }, generated_at, on_you, on_others, open,
+  //             agents_at_work, moving, routed, yours: [matter id], others: [matter id] }
+  // (a figure that could not be read is null, never 0).
+  router.get('/government/counts', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    try {
+      res.json(await counts.countsFor(req.builder));
+    } catch (err) {
+      log.error('[gds] GET /government/counts', err);
+      res.fail('counts_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: perm board.vote.cast — CHECK an ask without storing it (task 1004703):
+  // the agent's dry run before it files. Answers the same verdict a write would:
+  // { ok: true, ask } (the stored form), or 400 `ask_refused` whose message says
+  // in plain words what to fix and whose details list every broken rule. Writes
+  // nothing and reads nothing; the docket's own atom (xenos floor), like the write.
+  //
+  // Body: the ask — { question, options: [{ key, label, result, act? }],
+  //   recommend: { key, why }, waits_on, if_nobody_answers, detail? } — bare, or as { ask }.
+  router.post('/government/asks/check', api.requireBuilder, api.requirePermission('board.vote.cast'), (req, res) => {
+    const verdict = asks.checkAsk(askBody(req));
+    if (!verdict.ok) return refuseAsk(res, verdict);
+    res.json({ ok: true, ask: verdict.ask, question_words: verdict.question_words, rules: asks.ASK_RULES });
+  });
+
+  // rank: perm board.vote.cast — put an ASK on a docket matter (task 1004703):
+  // the one shape every request from an agent to a person takes. The matter is
+  // named by its docket id (`blockers:12`, `board:34`); the writer must hold the
+  // docket's atom AND see the matter, through the same per-source gate the
+  // docket applies (docket.findMatter), so an ask is never written onto a matter
+  // its writer cannot see. A slop ask is refused (400 `ask_refused`, every fix
+  // named) and nothing is stored. A second PUT replaces the ask whole.
+  //
+  // Body: the ask (as POST /government/asks/check). → 200 { ok, matter_id, ask }
+  router.put('/government/asks/:matterId', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    const matterId = String(req.params.matterId || '');
+    if (!asks.isMatterId(matterId)) return res.fail('bad_matter_id', { status: 400, message: 'Name the matter by its docket id, like blockers:12.' });
+    const verdict = asks.checkAsk(askBody(req));
+    if (!verdict.ok) return refuseAsk(res, verdict);
+    try {
+      const found = await docket.findMatterFor(req.builder, matterId);
+      if (!found.matter) {
+        if (found.reason === 'unavailable') return res.fail('matter_unavailable', { status: 503, message: 'That matter could not be read just now, so nothing was saved. Try again.' });
+        // a matter you cannot see answers exactly as one that does not exist
+        return res.fail('matter_not_found', { status: 404, message: 'No open matter by that id that you can see.' });
+      }
+      const ask = await asksDb.saveAsk({ matterId, ask: verdict.ask, builderId: req.builder.id });
+      res.json({ ok: true, matter_id: matterId, ask });
+    } catch (err) {
+      log.error('[gds] PUT /government/asks/:matterId', err);
+      res.fail('ask_save_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: perm board.vote.cast — PASS AN ASK ON to another seat (task 1004705,
+  // the direction desk). Only whoever the ask waits on today may hand it on
+  // (routing.passRefusal, from real seats: its Lead, the owner seat, a board's
+  // holders), and only an ask that is stored; a board sitting is its voters' and
+  // is never passed. The ask is kept word for word; only its seat changes, so it
+  // leaves the passer's "to do" and lands on the new seat's.
+  //
+  // Body: { seat }  → 200 { ok, matter_id, ask, route }
+  router.post('/government/asks/:matterId/pass', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    const matterId = String(req.params.matterId || '');
+    if (!asks.isMatterId(matterId)) return res.fail('bad_matter_id', { status: 400, message: 'Name the matter by its docket id, like blockers:12.' });
+    if (validateOrRespond(req, res, { seat: { required: true, type: 'string', minLength: 1, maxLength: 80 } })) return;
+    const seat = req.body.seat.trim();
+    try {
+      const found = await docket.matterWithSeats(req.builder, matterId, seat);
+      if (!found.matter) {
+        if (found.reason === 'unavailable') return res.fail('matter_unavailable', { status: 503, message: 'That matter could not be read just now, so nothing was passed on. Try again.' });
+        return res.fail('matter_not_found', { status: 404, message: 'No open matter by that id that you can see.' });
+      }
+      const refused = routing.passRefusal(found.matter, req.builder.id, seat, found.seats);
+      if (refused) return res.fail(refused.code, { status: refused.status, message: refused.message });
+      const ask = await asksDb.saveAsk({ matterId, ask: { ...found.matter.ask, waits_on: seat }, builderId: req.builder.id });
+      const route = routing.routeMatter({ ...found.matter, ask }, req.builder.id, found.seats);
+      res.json({ ok: true, matter_id: matterId, ask, route });
+    } catch (err) {
+      log.error('[gds] POST /government/asks/:matterId/pass', err);
+      res.fail('ask_pass_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // rank: perm board.item.open — put an AMENDMENT to the board (R14 of goal
   // 1000069, ADR 0175 §7). The board's other subject never comes through here:
   // a Full Idea's window opens AUTOMATICALLY on grade pass (R07), so requesting
@@ -841,6 +1015,125 @@ module.exports = function buildGovernmentRouter() {
     }
   });
 
+  // rank: perm board.item.open — propose a change to the project's LAWS (task
+  // 1004706): laws to enact, laws in force to repeal, or both, filed as an
+  // amendment of kind 'laws' and sat under the constitution IN FORCE, like every
+  // amendment. Nothing here writes a law — only the sitting passing does, inside
+  // its closing transaction. The same atom as proposing any amendment.
+  //
+  // Body: { enact?: [{ text, effect_on_ai?, locks? }], repeal?: [law id], rationale_md? }
+  //   text          one line, 3-100 characters: what every agent obeys
+  //   effect_on_ai  one line, at most 200: what it means for an agent
+  //   locks         at most 8 of { setting, value } (fixes it) or { setting, max } (caps it)
+  router.post('/government/board/laws', api.requireBuilder, api.requirePermission('board.item.open'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      enact: { type: 'array' },
+      repeal: { type: 'array' },
+      rationale_md: { type: 'string', maxLength: 5000 },
+    })) return;
+    try {
+      const out = await board.proposeLaws({
+        enact: req.body.enact,
+        repeal: req.body.repeal,
+        rationaleMd: req.body.rationale_md ?? null,
+        proposedBy: req.builder.id,
+      });
+      if (!out.ok) {
+        if (out.reason === 'already_in_force' || out.reason === 'setting_already_locked' || out.reason === 'not_in_force') {
+          return res.fail(out.reason, 409, {
+            ...(out.law_id ? { law_id: out.law_id } : {}),
+            ...(out.setting ? { setting: out.setting } : {}),
+            ...(out.field ? { field: out.field } : {}),
+          });
+        }
+        return res.fail('invalid_laws', 400, {
+          reason: out.reason,
+          ...(out.field ? { field: out.field } : {}),
+          ...(out.expected ? { expected: out.expected } : {}),
+          ...(out.setting ? { setting: out.setting } : {}),
+        });
+      }
+      res.status(201).json({ ok: true, amendment: out.amendment, item: out.item, proposal: out.proposal });
+    } catch (err) {
+      log.error('[gds] POST /government/board/laws', err);
+      res.fail('propose_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: perm board.vote.cast — the law book (task 1004706): every law in force,
+  // oldest first, each with who passed it (the government it was decided under,
+  // its proposer, who said yes, the sitting) and when. ?include=repealed adds the
+  // laws repealed since, with when and by which sitting. Every builder's agents
+  // obey these, so the read floors where the room's does. A read; nothing here
+  // writes a law.
+  router.get('/government/laws', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    try {
+      res.json(await board.lawsView({ includeRepealed: req.query.include === 'repealed' }));
+    } catch (err) {
+      log.error('[gds] GET /government/laws', err);
+      res.fail('laws_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: perm board.vote.cast — HOW STRICT the project runs its agents (task
+  // 1004715): the three strictness presets (Open workshop, Guild, Factory), which
+  // one the laws in force amount to (read, never stored: null when none), and for
+  // each its laws and the locks a switch to it would leave in force. A read.
+  router.get('/government/presets', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    try {
+      res.json(presets.presetsView(await db.listLaws()));
+    } catch (err) {
+      log.error('[gds] GET /government/presets', err);
+      res.fail('presets_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: perm board.item.open — SWITCH the project's strictness preset (task
+  // 1004715). A switch is a vote: ONE laws amendment (the same path as POST
+  // /government/board/laws) that enacts the preset's laws not in force and repeals
+  // the other presets' laws that are. Nothing here writes a law; only the sitting
+  // passing does. The same atom as proposing any law.
+  //
+  // Body: { preset: 'open' | 'guild' | 'factory' }
+  router.post('/government/board/presets', api.requireBuilder, api.requirePermission('board.item.open'), async (req, res) => {
+    if (validateOrRespond(req, res, { preset: { type: 'string', required: true, maxLength: 32 } })) return;
+    try {
+      const sw = presets.switchProposal(req.body.preset, await db.listLaws());
+      if (!sw.ok) {
+        if (sw.reason === 'preset_in_force') return res.fail('preset_in_force', 409, { preset: req.body.preset });
+        return res.fail('invalid_preset', 400, { reason: sw.reason, ...(sw.expected ? { expected: sw.expected } : {}) });
+      }
+      const out = await board.proposeLaws({ ...sw.proposal, rationaleMd: sw.rationale, proposedBy: req.builder.id });
+      if (!out.ok) {
+        if (out.reason === 'already_in_force' || out.reason === 'setting_already_locked' || out.reason === 'not_in_force') {
+          return res.fail(out.reason, 409, { ...(out.law_id ? { law_id: out.law_id } : {}), ...(out.setting ? { setting: out.setting } : {}) });
+        }
+        return res.fail('invalid_preset', 400, { reason: out.reason });
+      }
+      res.status(201).json({ ok: true, preset: req.body.preset, amendment: out.amendment, item: out.item, proposal: out.proposal });
+    } catch (err) {
+      log.error('[gds] POST /government/board/presets', err);
+      res.fail('propose_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: perm board.vote.cast — the Lead of each building (task 1004709): the
+  // nine buildings in street order, each with its Lead in office (who, their
+  // charter, since when, the sitting that appointed them) or null, and who answers
+  // for it — its Lead, or the owner (every active Archon, the founding one first)
+  // when it is unseated.
+  // ?include=past adds the appointments that have ended. A read; a Lead is
+  // appointed and removed only by a passed People matter (POST
+  // /government/board/matters, action appoint_lead or remove_lead).
+  router.get('/government/leads', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    try {
+      res.json(await board.leadsView({ includePast: req.query.include === 'past' }));
+    } catch (err) {
+      log.error('[gds] GET /government/leads', err);
+      res.fail('leads_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // rank: perm board.item.open — put a MATTER to a building's sitting (task
   // 1004529): the board's new subjects, one per building other than the
   // charter. Refused unless the building's row names a sitting — under the
@@ -849,7 +1142,12 @@ module.exports = function buildGovernmentRouter() {
   //
   // Body: { area, title, detail_md?, action? }
   //   action (People only): { type: 'assign_rank' | 'unassign_rank', builder_id, rank_key }
-  //   — carried out when the sitting passes, under the same walls as the direct route.
+  //   — carried out when the sitting passes, under the same walls as the direct route;
+  //   or { type: 'appoint_lead', building, builder_id, charter? } | { type: 'remove_lead', building }
+  //   (task 1004709) — the Lead of a building. Where People is decided as today
+  //   this one matter sits under the board in force instead of refusing.
+  //   Or, at any building, { type: 'build_out', building, capsule, name?, line? } (task
+  //   1004711) — a build-out put to a vote; POST /government/buildouts files it for the holder.
   router.post('/government/board/matters', api.requireBuilder, api.requirePermission('board.item.open'), async (req, res) => {
     if (validateOrRespond(req, res, {
       area: { required: true, type: 'string', maxLength: 32 },
@@ -869,11 +1167,17 @@ module.exports = function buildGovernmentRouter() {
         if (out.reason === 'decided_by_gate' || out.reason === 'no_one_holds_this' || out.reason === 'action_not_wired') {
           return res.fail(out.reason, 409, { area: out.area, ...(out.gate ? { gate: out.gate } : {}), what_this_means: out.what_this_means });
         }
+        if (out.reason === 'no_lead' || out.reason === 'already_lead') {
+          return res.fail(out.reason, 409, { area: out.area, building: out.building, what_this_means: out.what_this_means });
+        }
+        // task 1004711: a build-out is the building holder's to ask for, by this route too
+        if (out.reason === 'not_the_holder') return res.fail(out.reason, 403, { building: out.building, what_this_means: out.what_this_means });
         return res.fail('invalid_matter', 400, {
           reason: out.reason,
           ...(out.field ? { field: out.field } : {}),
           ...(out.expected ? { expected: out.expected } : {}),
           ...(out.rank_key ? { rank_key: out.rank_key } : {}),
+          ...(out.builder_id ? { builder_id: out.builder_id } : {}),
         });
       }
       res.status(201).json({ ok: true, matter: out.matter, item: out.item, decided: out.decided });
@@ -883,6 +1187,125 @@ module.exports = function buildGovernmentRouter() {
     }
   });
 
+  // rank: perm board.vote.cast — a Lead's BUILD-OUT (task 1004711, ADR 0378): a
+  // committee room, a new floor, an annex, or growing the building into a
+  // district. The coarse atom is the room's (every builder who reads the Leads);
+  // the wall is server-side and per request: only the building's HOLDER — its
+  // Lead in office, or the owner seat (every active Archon) when it is unseated
+  // — may ask (403 not_the_holder). build_rights (build-rights.js, the one rule)
+  // then decides: at once → 201 { path: 'at_once', buildout }, on the record now
+  // and drawn as a live site; otherwise → 201 { path: 'vote', matter, item },
+  // filed as a build_out matter through the same openMatter the matters route
+  // runs, drawn as a ghost with the sitting's tally until it closes.
+  //
+  // Body: { building, capsule: committee|floor|annex|district, name?, line? }
+  router.post('/government/buildouts', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      building: { required: true, type: 'string', maxLength: 32 },
+      capsule: { required: true, type: 'string', maxLength: 32 },
+      name: { type: 'string', maxLength: 80 },
+      line: { type: 'string', maxLength: 280 },
+    })) return;
+    try {
+      const out = await board.buildOut({
+        buildout: { building: req.body.building, capsule: req.body.capsule, name: req.body.name, line: req.body.line },
+        builderId: req.builder.id,
+      });
+      if (!out.ok) {
+        if (out.reason === 'not_the_holder') return res.fail(out.reason, 403, { building: out.building, what_this_means: out.what_this_means });
+        if (out.reason === 'decided_by_gate' || out.reason === 'no_one_holds_this') {
+          return res.fail(out.reason, 409, { area: out.area, what_this_means: out.what_this_means });
+        }
+        return res.fail('invalid_buildout', 400, { reason: out.reason, ...(out.field ? { field: out.field } : {}) });
+      }
+      if (out.path === 'at_once') return res.status(201).json({ ok: true, path: out.path, buildout: out.buildout, rights: out.rights });
+      res.status(201).json({ ok: true, path: out.path, matter: out.matter, item: out.item, decided: out.decided, rights: out.rights });
+    } catch (err) {
+      log.error('[gds] POST /government/buildouts', err);
+      res.fail('buildout_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: perm board.vote.cast — THE TREASURY (task 1004712, ADR 0379): this
+  // month's real spend and last month's, the spend cap (a project setting, off
+  // by default: no limit), the reserve, and every open goal's pot — its budget,
+  // what the reserve lent it this month, its real spend this month (cost_log
+  // through the goal's tasks) and its borrow, if it asked. Plus who answers for
+  // the Treasury today. A read; the room's atom, as GET /government/leads.
+  router.get('/government/treasury', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    try {
+      const [view, holder] = await Promise.all([treasuryDb.readTreasury(), treasuryHolder()]);
+      res.json({ ...view, answers: holder ? { seat: holder.seat, label: holder.label, fell_to_owner: holder.fell_to_owner, yours: holder.builder_ids.includes(String(req.builder.id)) } : null });
+    } catch (err) {
+      log.error('[gds] GET /government/treasury', err);
+      res.fail('treasury_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: perm board.vote.cast — GIVE A GOAL A POT, change its budget, or take it
+  // away (budget_usd: null). The room's atom; the wall is server-side and per
+  // request: only whoever answers for the Treasury today — its Lead, or the owner
+  // seat while it is unseated — may (403 not_the_holder). Only an open goal.
+  //
+  // Body: { budget_usd: number | null }  → 200 { ok, pot | removed }
+  router.put('/government/treasury/pots/:goalId', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    const goalId = parseId(req, res, { param: 'goalId', code: 'bad_goal_id', positiveInt: true });
+    if (goalId === null) return;
+    if (validateOrRespond(req, res, { budget_usd: {} })) return; // a number of dollars, or null to take the pot away; parsed below
+    const parsed = treasury.parseBudget(req.body ? req.body.budget_usd : undefined);
+    if (parsed.reason) return res.fail('bad_budget', { status: 400, message: parsed.reason });
+    try {
+      const holder = await treasuryHolder();
+      if (!holder) return res.fail('seats_unavailable', { status: 503, message: 'Who answers for the Treasury could not be read just now, so nothing was set. Try again.' });
+      if (!holder.builder_ids.includes(String(req.builder.id))) {
+        return res.fail('not_the_holder', 403, { building: 'treasury', what_this_means: `Only ${holder.label} sets a goal's pot.` });
+      }
+      const goal = await treasuryDb.goalById(goalId);
+      if (!goal) return res.fail('goal_not_found', { status: 404, message: 'No goal by that id.' });
+      if (goal.status !== 'open' && parsed.budget != null) return res.fail('goal_not_open', { status: 409, message: 'Only an open goal has a pot.' });
+      const out = await treasuryDb.setPot({ goalId, budget: parsed.budget, builderId: req.builder.id });
+      res.json({ ok: true, goal_id: String(goalId), ...(out.pot ? { pot: { goal_id: String(out.pot.goal_id), budget_usd: Number(out.pot.budget_usd), set_at: out.pot.set_at } } : { removed: out.removed }) });
+    } catch (err) {
+      log.error('[gds] PUT /government/treasury/pots/:goalId', err);
+      res.fail('pot_set_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: perm board.vote.cast — ANSWER A BORROW: lend it all, lend half, or say
+  // no. The room's atom; the wall is the direction desk's: only whoever the
+  // borrow's ask waits on today may answer it (routing.routeMatter over real
+  // seats: the Treasury's Lead, or the owner seat while it is unseated, or the
+  // seat it was passed to). Answered once; a second answer is 409. Saying no
+  // stops nothing: with no spend limit, work runs on and the overspend is debt.
+  //
+  // Body: { key: 'lend' | 'half' | 'no' }  → 200 { ok, borrow }
+  router.post('/government/treasury/borrows/:borrowId/answer', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    const borrowId = parseId(req, res, { param: 'borrowId', code: 'bad_borrow_id', positiveInt: true });
+    if (borrowId === null) return;
+    if (validateOrRespond(req, res, { key: { required: true, type: 'string', maxLength: 16 } })) return;
+    const key = req.body && typeof req.body.key === 'string' ? req.body.key.trim() : '';
+    if (!treasury.ANSWERS.includes(key)) return res.fail('bad_answer', { status: 400, message: 'Answer lend, half or no.' });
+    try {
+      const borrow = await treasuryDb.getBorrow(borrowId);
+      if (!borrow) return res.fail('borrow_not_found', { status: 404, message: 'No borrow by that id.' });
+      if (borrow.state !== 'open') return res.fail('already_answered', { status: 409, message: 'This borrow was already answered.' });
+      const found = await docket.matterWithSeats(req.builder, treasury.matterId(borrowId));
+      if (!found.matter) {
+        if (found.reason === 'unavailable') return res.fail('matter_unavailable', { status: 503, message: 'That borrow could not be read just now, so nothing was answered. Try again.' });
+        return res.fail('borrow_not_found', { status: 404, message: 'No open borrow by that id that you can see.' });
+      }
+      const route = routing.routeMatter(found.matter, req.builder.id, found.seats);
+      if (!route.yours) return res.fail('not_yours', { status: 403, message: `Only ${route.label} answers this borrow.` });
+      const written = await treasuryDb.answerBorrow({ id: borrowId, answer: treasury.answerOf(borrow, key), builderId: req.builder.id });
+      if (!written) return res.fail('already_answered', { status: 409, message: 'This borrow was already answered.' });
+      log.info(`[gds] treasury borrow ${borrowId} (goal ${borrow.goal_id}) answered ${key} by builder ${req.builder.id}`);
+      res.json({ ok: true, borrow: treasury.borrowView(written) });
+    } catch (err) {
+      log.error('[gds] POST /government/treasury/borrows/:borrowId/answer', err);
+      res.fail('borrow_answer_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // rank: perm board.item.open — withdraw your own open sitting (task 1004564).
   // The same atom as putting one up: taking it back is the proposer's half of
   // the same act. The atom is only the coarse gate; the walls are in

package/modules/government/routing.js

@@ -0,0 +1,154 @@
+'use strict';
+
+// modules/government/routing.js — THE DIRECTION DESK: every ask routed to a
+// real seat (task 1004705, goal 1000111 "government is how a project steers its
+// AI"; ADR 0376).
+//
+// WHAT IT DECIDES. Which seat an open docket matter waits on, who sits in that
+// seat today, and so whether it is THIS viewer's to answer ("to do") or someone
+// else's ("waits on others"). The hall used to answer that from the prototype
+// overlay; the server answers it now, from real seats, and the docket carries the
+// answer on every matter as `route`.
+//
+// THE SEAT A MATTER WAITS ON.
+//   1. Its stored ask's `waits_on` (asks.js): the seat its agent named, or the
+//      one somebody it waited on passed it to (POST /government/asks/:matter/pass).
+//   2. With no stored ask, the seat that answers for its building: a sitting of
+//      the board (source 'board') waits on `board:<building>`, its voters;
+//      anything else on `lead:<building>`.
+//
+// WHO SITS IN IT (the seat as resolved; never a guess):
+//   owner                  every active Archon (leads.js ownerOf)
+//   lead:<b>               its Lead in office; an UNSEATED building falls to the
+//                          owner (owner ruling) — leads.answerFor, written once
+//   board:<b>              the members its decision-rules row seats today
+//                          (docket.loadGovernment holders); nobody seated →
+//                          falls to the owner. A board sitting with no ask of
+//                          its own is its voters': the docket's per-voter
+//                          `needs` (board.awaitsVoter) already says whose it is.
+//   committee:<b>.<name>   no committee is held in a table yet, so it falls to
+//                          the building's Lead (and so, unseated, to the owner).
+//
+// IF NOBODY ANSWERS. An ask past its matter's deadline, or one whose seat nobody
+// holds (no Archon, nobody seated), is on nobody's "to do": it does what its own
+// `if_nobody_answers` line says, and the route carries that line as
+// `nobody.outcome`, so every surface prints the same words.
+//
+// PURE: no db. docket.js reads the seats (leads, Archons, holders) once per
+// request, uncached (ADR 0016), and routes every matter with routeAll.
+
+const { answerFor } = require('./leads');
+const asks = require('./asks');
+
+const BUILDING_NAMES = Object.freeze({
+  charter: 'Charter', rules: 'Rules', disputes: 'Disputes', people: 'People', planning: 'Planning',
+  automation: 'Automation', review: 'Review', release: 'Release', treasury: 'Treasury',
+});
+const isBuilding = (b) => Object.prototype.hasOwnProperty.call(BUILDING_NAMES, b);
+
+// The seat a matter waits on before anything falls: its stored ask's, else its building's.
+function seatOf(matter) {
+  const m = matter || {};
+  const stored = m.ask && typeof m.ask.waits_on === 'string' && asks.SEAT.test(m.ask.waits_on) ? m.ask.waits_on : null;
+  if (stored) return stored;
+  const b = isBuilding(m.building) ? m.building : 'planning';
+  return m.source === 'board' ? `board:${b}` : `lead:${b}`;
+}
+
+// How a seat reads, after "waits on".
+function seatLabel(seat) {
+  const s = String(seat || '');
+  if (s === 'owner') return 'the owner';
+  const m = /^(lead|board):([a-z]+)$/.exec(s);
+  if (m) return `the ${BUILDING_NAMES[m[2]] || m[2]} ${m[1] === 'lead' ? 'Lead' : 'board'}`;
+  return asks.seatWords(s);
+}
+
+const idsOf = (list) => (Array.isArray(list) ? list : [])
+  .map((p) => (p && typeof p === 'object' ? (p.builder_id ?? p.id) : p))
+  .filter((id) => id != null)
+  .map(String);
+
+// resolveSeat(asked, ctx) → { asked, seat, label, builder_ids, fell_to_owner }
+//   asked        the seat the matter names
+//   seat         the seat that answers it, after any fall
+//   builder_ids  who sits there now ([] when nobody does)
+// ctx { leads: Lead rows in office, owner: leads ownerOf(archons) shape
+//       { builders: [{ id }] }, holders: { building: [people] | null } }
+function resolveSeat(asked, ctx) {
+  const c = ctx || {};
+  const owner = c.owner || { builders: [] };
+  const ownerIds = idsOf(owner.builders);
+  const seated = (seat, ids) => ({ asked, seat, label: seatLabel(seat), builder_ids: ids, fell_to_owner: false });
+  const toOwner = () => ({ asked, seat: 'owner', label: seatLabel('owner'), builder_ids: ownerIds, fell_to_owner: true });
+  if (asked === 'owner') return seated('owner', ownerIds);
+  let m = /^lead:([a-z]+)$/.exec(String(asked || ''));
+  if (m) {
+    const a = answerFor(m[1], c.leads || [], owner);
+    return !a || a.fell_to_owner ? toOwner() : seated(a.seat, a.builder_ids.map(String));
+  }
+  if ((m = /^board:([a-z]+)$/.exec(String(asked || '')))) {
+    const held = idsOf((c.holders || {})[m[1]]);
+    return held.length ? seated(asked, held) : toOwner();
+  }
+  if ((m = /^committee:([a-z]+)\.[a-z0-9_]+$/.exec(String(asked || '')))) {
+    return { ...resolveSeat(`lead:${m[1]}`, c), asked };
+  }
+  return toOwner();
+}
+
+// routeMatter(matter, viewerId, ctx, now) → the route the docket carries:
+//   { seat, label, asked, fell_to_owner, yours, nobody: null | { why, outcome } }
+// `yours` is the one answer to "is this on me": an open matter that needs a
+// person, on a seat the viewer sits in, that somebody can still answer.
+function routeMatter(matter, viewerId, ctx, now = Date.now()) {
+  const m = matter || {};
+  const needs = m.state === 'needs';
+  // a sitting's voters are the item's own (its snapshot), never a fall to the owner
+  const ownVote = m.source === 'board' && !m.ask;
+  const asked = seatOf(m);
+  const r = ownVote ? { asked, seat: asked, label: seatLabel(asked), builder_ids: [], fell_to_owner: false } : resolveSeat(asked, ctx);
+  const deadline = m.deadline ? Date.parse(m.deadline) : NaN;
+  const outcome = m.ask && m.ask.if_nobody_answers ? String(m.ask.if_nobody_answers) : null;
+  let nobody = null;
+  if (needs && Number.isFinite(deadline) && deadline <= now) nobody = { why: 'lapsed', outcome };
+  else if (needs && !ownVote && !r.builder_ids.length) nobody = { why: 'empty_seat', outcome };
+  const viewer = viewerId == null ? null : String(viewerId);
+  const sits = ownVote ? needs : r.builder_ids.includes(viewer);
+  return {
+    seat: r.seat,
+    label: r.label,
+    asked: r.asked,
+    fell_to_owner: r.fell_to_owner,
+    yours: needs && !nobody && !!viewer && sits,
+    nobody,
+  };
+}
+
+// Route every matter in place; → how many are the viewer's.
+function routeAll(matters, viewerId, ctx, now = Date.now()) {
+  let yours = 0;
+  for (const m of matters || []) {
+    m.route = routeMatter(m, viewerId, ctx, now);
+    if (m.route.yours) yours += 1;
+  }
+  return yours;
+}
+
+// May this viewer pass this matter's ask on to `toSeat`? → null (yes) or a
+// refusal { code, status, message }. Only whoever the ask waits on may hand it
+// to another seat; a board sitting is its voters' and is never passed; the new
+// seat must be a seat, and a different one.
+function passRefusal(matter, viewerId, toSeat, ctx, now = Date.now()) {
+  const m = matter || {};
+  if (!m.ask) return { code: 'no_ask', status: 409, message: 'This matter has no ask to pass on yet.' };
+  if (m.source === 'board') return { code: 'vote_not_passable', status: 409, message: 'A vote is its voters\' to answer; it cannot be passed on.' };
+  const to = String(toSeat || '').trim();
+  if (!asks.SEAT.test(to)) return { code: 'unknown_seat', status: 400, message: 'Name a seat: owner, lead:<building>, committee:<building>.<name> or board:<building>.' };
+  const route = routeMatter(m, viewerId, ctx, now);
+  if (!route.yours) return { code: 'not_yours', status: 403, message: 'Only whoever this waits on can pass it on.' };
+  if (to === m.ask.waits_on || resolveSeat(to, ctx).seat === route.seat) return { code: 'same_seat', status: 409, message: 'It already waits on that seat.' };
+  return null;
+}
+
+module.exports = { seatOf, seatLabel, resolveSeat, routeMatter, routeAll, passRefusal, BUILDING_NAMES };