@bongos/core 1.19.224 → 1.19.225

package/modules/government/db.js

@@ -281,6 +281,123 @@ async function builderHoldsRankActive(builderId, rankKey) {
   return rows.length > 0;
 }
 
+// --- the board WRITES (BV1.R07 of goal 1000069) ------------------------------
+
+// Open a window for a subject. The idempotency is STRUCTURAL: the INSERT
+// targets government_003's partial unique index (one OPEN item per subject),
+// so a concurrent double-open inserts exactly one row — the loser gets null and
+// the caller reads the winner back with getOpenBoardItem. closes_at is computed
+// by the DATABASE clock (now() + the window), absolute rather than a duration,
+// so changing the project's window length never moves an already-open deadline;
+// NULL windowMinutes means NO CLOCK (the monarchy configuration — the item
+// closes on the first vote, not on time).
+async function openBoardItem({ subjectType, subjectId, openedBy = null, constitution, windowMinutes = null }) {
+  const { rows } = await pool.query(
+    `INSERT INTO government_board_items (subject_type, subject_id, opened_by, closes_at, constitution)
+     VALUES ($1, $2, $3,
+             CASE WHEN $4::int IS NULL THEN NULL ELSE now() + make_interval(mins => $4::int) END,
+             $5::jsonb)
+     ON CONFLICT (subject_type, subject_id) WHERE closed_at IS NULL DO NOTHING
+     RETURNING *`,
+    [subjectType, subjectId, openedBy, windowMinutes, JSON.stringify(constitution || {})],
+  );
+  return rows[0] || null;
+}
+
+async function getOpenBoardItem(subjectType, subjectId) {
+  const { rows } = await pool.query(
+    `SELECT * FROM government_board_items
+      WHERE subject_type = $1 AND subject_id = $2 AND closed_at IS NULL
+      LIMIT 1`,
+    [subjectType, subjectId],
+  );
+  return rows[0] || null;
+}
+
+// --- the vote READS + WRITES (BV1.R08 of goal 1000069) -----------------------
+
+// One item, with the expiry computed on the DATABASE clock so the route never
+// compares a Postgres timestamptz against a process clock. NULL closes_at is
+// the no-clock configuration and never expires.
+async function getBoardItemForVote(itemId) {
+  const { rows } = await pool.query(
+    `SELECT *, (closes_at IS NOT NULL AND closes_at < now()) AS expired
+       FROM government_board_items
+      WHERE id = $1`,
+    [itemId],
+  );
+  return rows[0] || null;
+}
+
+// The anti-self rule's subject: who put this item up. A full_idea's author is
+// the idea's captor (idea_inbox is a shared core table — reading it directly is
+// the sanctioned pattern; the boundary is code imports, not table access). An
+// amendment's author is its proposer, already on the row as opened_by. NULL —
+// an auto-opened item whose idea row is somehow gone — means no self to refuse.
+async function getBoardItemAuthor(item) {
+  if (!item) return null;
+  if (item.subject_type === 'full_idea') {
+    const { rows } = await pool.query(
+      `SELECT captured_by FROM idea_inbox WHERE id = $1`,
+      [item.subject_id],
+    );
+    return rows[0] ? rows[0].captured_by : null;
+  }
+  return item.opened_by ?? null;
+}
+
+// The open ballot's one write. Idempotency is STRUCTURAL — UNIQUE(item_id,
+// voter_id); the loser of a double-cast gets null and the caller reads the
+// standing vote back.
+async function insertBoardVote({ itemId, voterId, direction, reasonMd = null, sectionKey = null }) {
+  const { rows } = await pool.query(
+    `INSERT INTO government_board_votes (item_id, voter_id, direction, reason_md, section_key)
+     VALUES ($1, $2, $3, $4, $5)
+     ON CONFLICT (item_id, voter_id) DO NOTHING
+     RETURNING *`,
+    [itemId, voterId, direction, reasonMd, sectionKey],
+  );
+  return rows[0] || null;
+}
+
+async function getBoardVote(itemId, voterId) {
+  const { rows } = await pool.query(
+    `SELECT * FROM government_board_votes WHERE item_id = $1 AND voter_id = $2`,
+    [itemId, voterId],
+  );
+  return rows[0] || null;
+}
+
+// Voter karma (+1 in-window, owner decision 8) — rides the FRESH insert only,
+// so the idempotent re-cast can never double-pay. granted_by NULL: earned from
+// the system by the act, not granted by a person (the governance_002 backfill
+// convention). karma_log is a shared core table; same access rule as above.
+// Author-ratification karma (+3, board.js AUTHOR_RATIFY_KARMA_DELTA) — fired by
+// the R10 close on a passed item. IDEMPOTENT: the reason key is unique per item
+// and the INSERT is one atomic WHERE-NOT-EXISTS statement (the economy
+// credit-lane idiom — karma_log carries no unique constraint, so the predicate
+// IS the guard). Returns whether a row was actually written.
+async function insertAuthorRatifyKarma({ authorId, itemId, delta }) {
+  const reason = `board.item.ratified:${itemId}`;
+  const { rowCount } = await pool.query(
+    `INSERT INTO karma_log (builder_id, delta, reason, granted_by)
+     SELECT $1, $2, $3, NULL
+      WHERE NOT EXISTS (
+        SELECT 1 FROM karma_log WHERE builder_id = $1 AND reason = $3
+      )`,
+    [authorId, delta, reason],
+  );
+  return rowCount > 0;
+}
+
+async function insertVoteKarma({ voterId, itemId, delta }) {
+  await pool.query(
+    `INSERT INTO karma_log (builder_id, delta, reason, granted_by)
+     VALUES ($1, $2, $3, NULL)`,
+    [voterId, delta, `board.vote.cast:${itemId}`],
+  );
+}
+
 module.exports = {
   getPermissionKeysForBuilder,
   getRankKeysForBuilder,
@@ -298,4 +415,12 @@ module.exports = {
   unassignRank,
   getActiveBuildersWithRank,
   builderHoldsRankActive,
+  openBoardItem,
+  getOpenBoardItem,
+  getBoardItemForVote,
+  getBoardItemAuthor,
+  insertBoardVote,
+  getBoardVote,
+  insertVoteKarma,
+  insertAuthorRatifyKarma,
 };

package/modules/government/routes/government.js

@@ -24,6 +24,7 @@ const catalog = require('../catalog');
 const db = require('../db');
 const sessionScopes = require('../session-scopes');
 const boardMembership = require('../board-membership');
+const board = require('../board');
 
 // The port surface. Deliberately narrow: resolution + the catalog reads a gate or
 // the Archon tab needs. It grows with R98-R101 (principals, session-scopes,
@@ -86,6 +87,10 @@ const governmentPort = {
   parseMembershipPredicate: boardMembership.parseMembershipPredicate,
   resolveBoardMembers: boardMembership.resolveBoardMembers,
   isBoardMember: boardMembership.isBoardMember,
+  // R07: the ideas capture path fires this when a Full Idea's grade lands — the
+  // bar gate lives INSIDE board.js (a sub-bar idea never reaches the board, and
+  // no caller is trusted to pre-filter). Returns, never throws into capture.
+  openBoardWindowForIdea: board.openWindowForFullIdea,
 };
 
 function registerSeams() {
@@ -405,6 +410,55 @@ module.exports = function buildGovernmentRouter() {
     }
   });
 
+  // rank: perm board.vote.cast — cast a vote on an open board item (R08 of goal
+  // 1000069, ADR 0175). The atom FLOORS AT XENOS deliberately (the R04 carry-
+  // note): the permission is only the coarse gate, and the real wall is the
+  // in-handler membership re-check against the constitution SNAPSHOTTED on the
+  // item — do not "tighten" the floor to archon; that would fork authority
+  // truth and make widening the franchise a migration instead of a config
+  // change. Open ballot, anti-self, idempotent (UNIQUE(item_id, voter_id)),
+  // voter karma +1 on a fresh in-window cast. The policy lives in board.js
+  // castVote; this handler is the HTTP mapping.
+  router.post('/government/board/items/:itemId/votes', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    const itemId = parseId(req, res, { param: 'itemId', code: 'bad_item_id', positiveInt: true });
+    if (itemId === null) return;
+    if (validateOrRespond(req, res, {
+      direction: { required: true, type: 'string', maxLength: 3 },
+      reason_md: { type: 'string', maxLength: 5000 },
+      section_key: { type: 'string', maxLength: 32 },
+    })) return;
+    try {
+      const out = await board.castVote({
+        itemId,
+        voterId: req.builder.id,
+        direction: req.body.direction,
+        reasonMd: req.body.reason_md ?? null,
+        sectionKey: req.body.section_key ?? null,
+      });
+      if (!out.ok) {
+        const status =
+          out.reason === 'item_not_found' ? 404 :
+          out.reason === 'not_board_member' ? 403 :
+          out.reason === 'anti_self_vote' ? 403 :
+          out.reason === 'item_closed' ? 409 :
+          out.reason === 'vote_window_expired' ? 409 :
+          400; // bad_direction / yes_carries_nothing / objection_needs_reason / objection_needs_section
+        return res.fail(out.reason, status, { item_id: itemId });
+      }
+      // Idempotent re-cast reads back the standing vote — 200, not 201, and no
+      // karma line: nothing new was recorded.
+      res.status(out.fresh ? 201 : 200).json({
+        ok: true,
+        vote: out.vote,
+        already_voted: !out.fresh,
+        ...(out.fresh ? { karma_delta: out.karma_delta } : {}),
+      });
+    } catch (err) {
+      console.error('[gds] POST /government/board/items/:itemId/votes', err);
+      res.fail('vote_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   return router;
 };
 

package/modules/ideas/module.json

@@ -17,6 +17,7 @@
     "ideas.capture"
   ],
   "consumes": [
-    "reward"
+    "reward",
+    "government"
   ]
 }

package/modules/ideas/routes/inbox.js

@@ -146,6 +146,33 @@ module.exports = function buildInboxRouter() {
             // no warning surfaced — the idea and its grade are intact; the credit
             // is the only thing missed, and a reconcile/re-grade path can pay it.
           }
+
+          // R07 (goal 1000069, ADR 0175 §5): a Full Idea crossing the
+          // completeness bar automatically opens its ratification window in the
+          // Board Room. Resolved through the `government` port (declared in
+          // consumes), never a direct import — and the BAR GATE lives on the
+          // government side (board.js refuses a sub-bar score), so this hook
+          // fires unconditionally with the stored score and the board decides.
+          // FAIL-OPEN like the credit above: the idea and its grade are already
+          // stored, and a board hiccup must never lose a capture. The open is
+          // idempotent (one open window per subject, structural in the schema),
+          // so a retry or re-capture can never open two.
+          try {
+            const government = api.resolveOptional && api.resolveOptional('government');
+            if (government && government.openBoardWindowForIdea) {
+              const w = await government.openBoardWindowForIdea({
+                ideaId: idea.id,
+                completenessScore: row.completeness_score,
+              });
+              if (w && w.opened && w.item) {
+                idea.board_window = { item_id: w.item.id, closes_at: w.item.closes_at };
+              }
+            }
+          } catch (boardErr) {
+            console.error('[gds] POST /inbox board-window open failed (idea captured + graded, window skipped):', boardErr);
+            // R11's expiry poller sweeps open items, not missed opens; a missed
+            // open is recoverable by resubmission (R13) — capture stays intact.
+          }
         } catch (gradeErr) {
           console.error('[gds] POST /inbox full-grade write failed (idea captured, landing as quick):', gradeErr);
           grade_warning = 'captured_but_ungraded';

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.224",
+  "version": "1.19.225",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.224",
+      "version": "1.19.225",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.224",
+  "version": "1.19.225",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/bongos/route-rank-check.js

@@ -247,6 +247,10 @@ const GOVERNMENT_PINS = {
   'POST /government/ranks/:rankKey/reset': 'perm:government.manage',
   'POST /government/assignments': 'perm:government.manage',
   'DELETE /government/assignments/:builderId/:rankKey': 'perm:government.manage',
+  // The Board Room's first route (R08 of goal 1000069 — the R04-carried pin).
+  // The XENOS-floored atom is the COARSE gate by design; the real wall is the
+  // in-handler membership re-check against the item's snapshotted constitution.
+  'POST /government/board/items/:itemId/votes': 'perm:board.vote.cast',
 };
 
 // Module-scoped privileged-rank pins: a privileged route that lives in a FEATURE

package/src/module-api.js

@@ -875,8 +875,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.222 with no explicit bump. run 32097491676. (task 1002620)
 //   1.19.224 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.223 with no explicit bump. run 32098083321. (task 1002620)
+//   1.19.225 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.224 with no explicit bump. run 32099793591. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.224'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.225'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/government_board_vote.mjs

@@ -0,0 +1,247 @@
+// tests/government_board_vote.mjs — cast a vote: open ballot, anti-self, live
+// re-check, karma (BV1.R08 of goal 1000069, ADR 0175 §§4/6/9).
+//
+// DB-free (db monkeypatched, the sibling board tests' idiom) — and deliberately
+// NOT membership-stubbed: castVote runs the REAL board-membership parse against
+// the item's snapshotted constitution, with only the db row lookups stubbed, so
+// the "who may vote is the SNAPSHOT's rule" property is exercised rather than
+// assumed. The invariants:
+//
+//   1. THE SECTION KEYS ARE ONE LIST IN THREE PLACES — board.js's validation,
+//      government_003's CHECK, and the ideas template declaration. A module may
+//      not require a sibling (ADR 0083), so they are held equal HERE.
+//   2. ANTI-SELF IS SERVER-SIDE AND UNCONDITIONAL — the bright line that keeps
+//      ratification from being ceremonial.
+//   3. MEMBERSHIP IS RE-CHECKED LIVE, AGAINST THE SNAPSHOT — a demotion between
+//      open and vote refuses the vote; an amendment mid-sitting cannot change
+//      who votes on an already-open item.
+//   4. IDEMPOTENT, AND KARMA RIDES ONLY THE FRESH INSERT — a double-cast is one
+//      vote and one +1, never two.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GOV = path.join(ROOT, 'modules', 'government');
+const board = require(path.join(GOV, 'board.js'));
+const db = require(path.join(GOV, 'db.js'));
+const { fieldOrder, templateFor } = require(path.join(ROOT, 'modules', 'ideas', 'templates.js'));
+
+const { FULL_IDEA_SECTION_KEYS, VOTE_KARMA_DELTA, AUTHOR_RATIFY_KARMA_DELTA, awardAuthorRatifyKarma, validateVote, castVote } = board;
+
+// ── invariant 1: one list, three places ─────────────────────────────────────
+
+test('the objection section keys ARE the Full Idea template fields (no second list that drifts)', () => {
+  assert.deepEqual([...FULL_IDEA_SECTION_KEYS], fieldOrder(templateFor('base-v1')),
+    'board.js must flag against the same five sections the template declares');
+  const migration = fs.readFileSync(
+    path.join(GOV, 'migrations', 'government_003_board_tables.sql'), 'utf8');
+  for (const key of FULL_IDEA_SECTION_KEYS) {
+    assert.ok(migration.includes(`'${key}'`), `the government_003 CHECK must carry '${key}'`);
+  }
+});
+
+// ── the pure payload validation ──────────────────────────────────────────────
+
+test('a yes carries nothing; a no carries a reason AND exactly one section', () => {
+  assert.deepEqual(validateVote({ direction: 'yes' }),
+    { ok: true, direction: 'yes', reasonMd: null, sectionKey: null });
+  assert.equal(validateVote({ direction: 'yes', reasonMd: 'but…' }).reason, 'yes_carries_nothing');
+  assert.equal(validateVote({ direction: 'yes', sectionKey: 'fit' }).reason, 'yes_carries_nothing');
+
+  const no = validateVote({ direction: 'no', reasonMd: '  needs a real fit story  ', sectionKey: 'fit' });
+  assert.deepEqual(no, { ok: true, direction: 'no', reasonMd: 'needs a real fit story', sectionKey: 'fit' });
+  assert.equal(validateVote({ direction: 'no', sectionKey: 'fit' }).reason, 'objection_needs_reason');
+  assert.equal(validateVote({ direction: 'no', reasonMd: '   ', sectionKey: 'fit' }).reason, 'objection_needs_reason');
+  assert.equal(validateVote({ direction: 'no', reasonMd: 'x' }).reason, 'objection_needs_section');
+  assert.equal(validateVote({ direction: 'no', reasonMd: 'x', sectionKey: 'vibes' }).reason, 'objection_needs_section');
+  for (const bad of [undefined, null, 'YES', 'abstain', 1]) {
+    assert.equal(validateVote({ direction: bad }).reason, 'bad_direction', `${String(bad)} is not a ballot`);
+  }
+});
+
+// ── castVote against a stubbed db (membership logic REAL) ───────────────────
+
+const MONARCHY = { membership: 'rank:archon', pass_rule: 'first_ratifier', window_minutes: null, close_early_on_full_turnout: true };
+const openItem = (over = {}) => ({
+  id: '11', subject_type: 'full_idea', subject_id: '7', opened_by: null,
+  closed_at: null, expired: false, constitution: MONARCHY, ...over,
+});
+
+async function withDb(stubs, fn) {
+  const originals = {};
+  for (const [k, v] of Object.entries(stubs)) { originals[k] = db[k]; db[k] = v; }
+  try { return await fn(); }
+  finally { for (const [k, v] of Object.entries(originals)) db[k] = v; }
+}
+
+test('the happy path: a member yes is recorded fresh, with its +1 karma', async () => {
+  const karma = [];
+  let insertArgs = null;
+  await withDb({
+    getBoardItemForVote: async () => openItem(),
+    builderHoldsRankActive: async (builderId, rankKey) =>
+      builderId === '42' && rankKey === 'archon', // the REAL membership parse chose 'archon' from the snapshot
+    getBoardItemAuthor: async () => '7',          // someone else authored the idea
+    insertBoardVote: async (args) => { insertArgs = args; return { id: '1', ...args }; },
+    insertVoteKarma: async (args) => { karma.push(args); },
+  }, async () => {
+    const out = await castVote({ itemId: 11, voterId: '42', direction: 'yes' });
+    assert.equal(out.ok, true);
+    assert.equal(out.fresh, true);
+    assert.equal(out.karma_delta, VOTE_KARMA_DELTA);
+  });
+  assert.deepEqual(insertArgs, { itemId: 11, voterId: '42', direction: 'yes', reasonMd: null, sectionKey: null });
+  assert.deepEqual(karma, [{ voterId: '42', itemId: 11, delta: VOTE_KARMA_DELTA }]);
+});
+
+test('membership is the SNAPSHOT\'s rule: a rank the snapshot does not name is refused', async () => {
+  // The live config could say anything; the item was opened under monarchy, so
+  // only an archon-holder votes on it. A metic-holder is refused even though
+  // they hold A rank — just not the snapshotted one.
+  await withDb({
+    getBoardItemForVote: async () => openItem(),
+    builderHoldsRankActive: async (builderId, rankKey) => rankKey === 'metic', // holds metic, not archon
+    getBoardItemAuthor: async () => { throw new Error('must not be reached'); },
+    insertBoardVote: async () => { throw new Error('must not be reached'); },
+  }, async () => {
+    const out = await castVote({ itemId: 11, voterId: '42', direction: 'yes' });
+    assert.deepEqual(out, { ok: false, reason: 'not_board_member' });
+  });
+});
+
+test('the demotion between open and vote refuses the vote — live re-check, uncached', async () => {
+  let demoted = false;
+  await withDb({
+    getBoardItemForVote: async () => openItem(),
+    builderHoldsRankActive: async () => !demoted,
+    getBoardItemAuthor: async () => '7',
+    insertBoardVote: async (args) => ({ id: '1', ...args }),
+    insertVoteKarma: async () => {},
+  }, async () => {
+    assert.equal((await castVote({ itemId: 11, voterId: '42', direction: 'yes' })).ok, true);
+    demoted = true;
+    assert.deepEqual(await castVote({ itemId: 11, voterId: '42', direction: 'yes' }),
+      { ok: false, reason: 'not_board_member' }, 'off the board on the very next request');
+  });
+});
+
+test('anti-self: the author cannot vote on their own item — number/string ids compare equal', async () => {
+  await withDb({
+    getBoardItemForVote: async () => openItem(),
+    builderHoldsRankActive: async () => true,
+    getBoardItemAuthor: async () => 42, // Postgres hands back a number; the voter carries a string
+    insertBoardVote: async () => { throw new Error('must not be reached'); },
+  }, async () => {
+    const out = await castVote({ itemId: 11, voterId: '42', direction: 'yes' });
+    assert.deepEqual(out, { ok: false, reason: 'anti_self_vote' });
+  });
+});
+
+test('closed and expired items refuse a vote, each with its own name', async () => {
+  await withDb({
+    getBoardItemForVote: async () => openItem({ closed_at: 't', outcome: 'passed' }),
+  }, async () => {
+    assert.deepEqual(await castVote({ itemId: 11, voterId: '42', direction: 'yes' }),
+      { ok: false, reason: 'item_closed' });
+  });
+  await withDb({
+    getBoardItemForVote: async () => openItem({ expired: true }),
+  }, async () => {
+    // The gap between expiry and the R11 sweep: a vote after time never lands.
+    assert.deepEqual(await castVote({ itemId: 11, voterId: '42', direction: 'yes' }),
+      { ok: false, reason: 'vote_window_expired' });
+  });
+  await withDb({ getBoardItemForVote: async () => null }, async () => {
+    assert.deepEqual(await castVote({ itemId: 999, voterId: '42', direction: 'yes' }),
+      { ok: false, reason: 'item_not_found' });
+  });
+});
+
+test('idempotent: a double-cast is ONE vote and ONE karma line', async () => {
+  const karma = [];
+  const standing = { id: '1', item_id: '11', voter_id: '42', direction: 'yes' };
+  let hasVote = false;
+  await withDb({
+    getBoardItemForVote: async () => openItem(),
+    builderHoldsRankActive: async () => true,
+    getBoardItemAuthor: async () => '7',
+    insertBoardVote: async (args) => (hasVote ? null : (hasVote = true, { ...standing, ...args })),
+    getBoardVote: async () => standing,
+    insertVoteKarma: async (args) => { karma.push(args); },
+  }, async () => {
+    const first = await castVote({ itemId: 11, voterId: '42', direction: 'yes' });
+    const second = await castVote({ itemId: 11, voterId: '42', direction: 'yes' });
+    assert.equal(first.fresh, true);
+    assert.equal(second.fresh, false);
+    assert.deepEqual(second.vote, standing, 'the re-cast returns the standing vote');
+    assert.equal(karma.length, 1, 'karma rode the fresh insert only');
+  });
+});
+
+test('an invalid payload is refused before ANY db read', async () => {
+  await withDb({
+    getBoardItemForVote: async () => { throw new Error('must not be reached'); },
+  }, async () => {
+    assert.equal((await castVote({ itemId: 11, voterId: '42', direction: 'no', reasonMd: 'x' })).reason,
+      'objection_needs_section');
+    assert.equal((await castVote({ itemId: 'nope', voterId: '42', direction: 'yes' })).reason,
+      'item_not_found');
+  });
+});
+
+// ── the structural pins ──────────────────────────────────────────────────────
+
+test('the vote INSERT targets UNIQUE(item_id, voter_id) — idempotency is the schema', () => {
+  const src = fs.readFileSync(path.join(GOV, 'db.js'), 'utf8');
+  const block = src.slice(src.indexOf('async function insertBoardVote'));
+  assert.match(block, /ON CONFLICT \(item_id, voter_id\) DO NOTHING/);
+});
+
+test('the route pin exists and names the XENOS-floored atom (the R04-carried pin)', () => {
+  const rrc = require(path.join(ROOT, 'src', 'bongos', 'route-rank-check.js'));
+  assert.equal(rrc.MODULE_EXPECTED_RANKS.government['POST /government/board/items/:itemId/votes'],
+    `${rrc.PERM_PIN_PREFIX}board.vote.cast`,
+    'the coarse gate is board.vote.cast; membership is the in-handler wall');
+});
+
+// ── author karma on ratification (declared here, fired by R10's close) ───────
+
+test('the author-ratification karma mirrors KARMA_RATIFY_DELTA (+3, not the stale +5)', () => {
+  const { KARMA_RATIFY_DELTA } = require(path.join(ROOT, 'modules', 'ideas', 'inbox.js'));
+  assert.equal(AUTHOR_RATIFY_KARMA_DELTA, KARMA_RATIFY_DELTA,
+    'board ratification pays what criterion-proposal ratification pays — one number, held equal here');
+  assert.equal(AUTHOR_RATIFY_KARMA_DELTA, 3, 'V3.R28 tuned this down from +5; do not copy the stale docs');
+});
+
+test('awardAuthorRatifyKarma pays once per item, and nobody when there is no author', async () => {
+  const paid = [];
+  await withDb({
+    getBoardItemAuthor: async () => '7',
+    insertAuthorRatifyKarma: async (args) => { paid.push(args); return paid.length === 1; }, // second call: reason exists
+  }, async () => {
+    const first = await awardAuthorRatifyKarma({ id: '11', subject_type: 'full_idea', subject_id: '7' });
+    const second = await awardAuthorRatifyKarma({ id: '11', subject_type: 'full_idea', subject_id: '7' });
+    assert.deepEqual(first, { paid: true, karma_delta: AUTHOR_RATIFY_KARMA_DELTA });
+    assert.deepEqual(second, { paid: false, reason: 'already_paid' }, 'a re-driven close never double-pays');
+  });
+  assert.deepEqual(paid[0], { authorId: '7', itemId: '11', delta: AUTHOR_RATIFY_KARMA_DELTA });
+
+  await withDb({
+    getBoardItemAuthor: async () => null,
+    insertAuthorRatifyKarma: async () => { throw new Error('must not be reached'); },
+  }, async () => {
+    assert.deepEqual(await awardAuthorRatifyKarma({ id: '12' }), { paid: false, reason: 'no_author' });
+  });
+});
+
+test('the ratify-karma INSERT is one atomic WHERE-NOT-EXISTS statement (idempotency in the SQL)', () => {
+  const src = fs.readFileSync(path.join(GOV, 'db.js'), 'utf8');
+  const block = src.slice(src.indexOf('async function insertAuthorRatifyKarma'), src.indexOf('async function insertVoteKarma'));
+  assert.match(block, /WHERE NOT EXISTS/, 'the predicate is the guard — karma_log has no unique constraint');
+  assert.match(block, /board\.item\.ratified:/, 'the per-item reason key is the idempotency key');
+});