@bongos/core 1.19.237 → 1.19.239

package/tests/discord_board_broadcast.mjs

@@ -119,3 +119,171 @@ test('an unlinked member\'s crafted display name is stripped of markdown and lin
   assert.ok(!text.includes('@everyone'), 'no lookalike mention survives (the ping was already dead; now the text is too)');
   assert.ok(text.includes('click me'), 'the words themselves remain — visible, honest, inert');
 });
+
+// ── R22 (task 1003035): the state mirror — closed, and the outcome ───────────
+//
+// The invariants R22 adds:
+//   6. THE SAME MESSAGE CARRIES THE OUTCOME — the summons is EDITED, never
+//      appended to, so the channel can never show a stale open window beside a
+//      closed one. The id comes from the POST (`wait=true`) and is remembered.
+//   7. BOTH OUTCOMES MIRROR — a return is mirrored exactly like a pass; only the
+//      pass CONTRACT event stays pass-only (the credit lane's payload).
+//   8. STILL BEST-EFFORT, STILL OUTBOUND-ONLY — every failure is a named skip,
+//      an unannounced item posts fresh rather than going silent, and an edit
+//      never re-rings the board.
+const { postBoardOutcome, composeOutcomeLine } = require(path.join(ROOT, 'modules', 'discord', 'board-broadcast.js'));
+const closedPayload = (over = {}) => ({
+  item_id: '11', subject_type: 'full_idea', subject_id: '7',
+  outcome: 'passed', cause: 'vote', closed_at: '2026-08-18T12:00:00.000Z',
+  tally: { yes: 1, no: 0, total: 1 }, ...over,
+});
+
+test('the announcement is remembered at post time, so the close has something to edit', async () => {
+  let recorded = null;
+  const out = await postBoardAnnouncement(payload(), {
+    resolveMembers: async () => [member(1, 'a')],
+    getLinks: async () => new Map([['1', { discord_user_id: '9' }]]),
+    post: async () => ({ ok: true, status: 200, message_id: '555000111' }),
+    recordMessage: async (row) => { recorded = row; },
+    log: () => {},
+  });
+  assert.equal(out.posted, true);
+  assert.deepEqual(recorded, { itemId: '11', channel: 'board_room', messageId: '555000111' });
+  assert.equal(out.recorded, '555000111');
+});
+
+test('a poster that returns no id, or a failed remember, still counts as announced', async () => {
+  const quiet = {
+    resolveMembers: async () => [member(1, 'a')],
+    getLinks: async () => new Map([['1', { discord_user_id: '9' }]]),
+    log: () => {},
+  };
+  // The pre-R22 shape (no return value at all) must not become a failure.
+  assert.equal((await postBoardAnnouncement(payload(), { ...quiet, post: async () => {} })).posted, true);
+  const out = await postBoardAnnouncement(payload(), {
+    ...quiet,
+    post: async () => ({ message: { id: '7' } }),
+    recordMessage: async () => { throw new Error('db down'); },
+  });
+  assert.equal(out.posted, true, 'the nudge is already in the channel — a lost id is not a failed announcement');
+  assert.equal(out.recorded, undefined);
+});
+
+test('the close is EDITED onto the same message, and the edit is stamped', async () => {
+  let edited = null; let stamped = null;
+  const out = await postBoardOutcome(closedPayload({ tally: { yes: 2, no: 0, total: 2 } }), {
+    getMessage: async (itemId) => { assert.equal(itemId, '11'); return { item_id: '11', channel: 'board_room', message_id: '555000111' }; },
+    edit: async (channel, messageId, text) => { edited = { channel, messageId, text }; },
+    markEdited: async (itemId) => { stamped = itemId; },
+    log: () => {},
+  });
+  assert.deepEqual({ edited: out.edited, posted: out.posted, skipped: out.skipped }, { edited: true, posted: false, skipped: null });
+  assert.equal(edited.channel, 'board_room');
+  assert.equal(edited.messageId, '555000111');
+  assert.ok(edited.text.includes('RATIFIED'), 'the summons now reads as the outcome');
+  assert.ok(!edited.text.includes('your vote is wanted'), 'nothing stale survives the edit');
+  assert.ok(edited.text.includes('/government?item=11#board-room'), 'the record is still one click away');
+  assert.equal(stamped, '11', 'edited_at answers "is this window still shown as open?" without asking Discord');
+});
+
+test('a RETURN mirrors exactly like a pass — and names neither voter nor reason', async () => {
+  let text = null;
+  const out = await postBoardOutcome(closedPayload({ outcome: 'returned', cause: 'expiry', tally: { yes: 0, no: 1, total: 1 } }), {
+    getMessage: async () => ({ channel: 'board_room', message_id: '9' }),
+    edit: async (_c, _m, t) => { text = t; },
+    markEdited: async () => {},
+    log: () => {},
+  });
+  assert.equal(out.edited, true);
+  assert.ok(text.includes('RETURNED to its author'));
+  assert.ok(text.includes('1 objection'), 'singular reads right at one');
+  assert.ok(text.includes('the window ran out'), 'an expiry close says so');
+  assert.ok(text.includes('in the hall'), 'the reason + flagged section live where the idea is');
+});
+
+test('a zero-vote pass states what happened instead of reading like a bug', () => {
+  const line = composeOutcomeLine(closedPayload({ cause: 'expiry', tally: { yes: 0, no: 0, total: 0 } }));
+  assert.ok(line.includes('nobody objected before the window closed'), 'an absence is nulled, never a block (ADR 0175 §3)');
+  assert.ok(line.includes('RATIFIED'));
+  const amendment = composeOutcomeLine(closedPayload({ subject_type: 'constitutional_amendment', tally: { yes: 3, no: 0 } }));
+  assert.ok(amendment.includes('constitutional amendment'), 'the second subject is named honestly here too');
+  assert.ok(amendment.includes('3 in favour, 0 objections'));
+});
+
+test('an unannounced item posts its outcome fresh rather than going silent', async () => {
+  let posted = null;
+  const out = await postBoardOutcome(closedPayload(), {
+    getMessage: async () => null,
+    post: async (channel, text) => { posted = { channel, text }; },
+    log: () => {},
+  });
+  assert.deepEqual({ edited: out.edited, posted: out.posted }, { edited: false, posted: true });
+  assert.equal(posted.channel, 'board_room');
+  assert.ok(posted.text.includes('RATIFIED'));
+});
+
+test('every mirror failure is a NAMED skip — a close can never be failed by Discord', async () => {
+  assert.equal((await postBoardOutcome(null, { log: () => {} })).skipped, 'no_item');
+  assert.equal((await postBoardOutcome(closedPayload({ outcome: null }), { log: () => {} })).skipped, 'no_outcome');
+  const failed = await postBoardOutcome(closedPayload(), {
+    getMessage: async () => ({ channel: 'board_room', message_id: '9' }),
+    edit: async () => { throw new Error('discord down'); },
+    log: () => {},
+  });
+  assert.deepEqual({ edited: failed.edited, posted: failed.posted, skipped: failed.skipped },
+    { edited: false, posted: false, skipped: 'mirror_failed' },
+    'a failed EDIT never falls back to a second message — the room must not get two notices');
+  // An unreadable bookkeeping read degrades to "unannounced", not to a throw.
+  const unread = await postBoardOutcome(closedPayload(), {
+    getMessage: async () => { throw new Error('db down'); },
+    post: async () => {},
+    log: () => {},
+  });
+  assert.equal(unread.posted, true);
+  // A stamp that fails leaves the mirrored close reported as mirrored.
+  const unstamped = await postBoardOutcome(closedPayload(), {
+    getMessage: async () => ({ channel: 'board_room', message_id: '9' }),
+    edit: async () => {},
+    markEdited: async () => { throw new Error('db down'); },
+    log: () => {},
+  });
+  assert.equal(unstamped.edited, true);
+});
+
+test('government emits the close for BOTH outcomes, after commit, and keeps the pass contract pass-only (source pins)', () => {
+  const board = fs.readFileSync(path.join(ROOT, 'modules', 'government', 'board.js'), 'utf8');
+  const close = board.slice(board.indexOf('async function closeItem'));
+  assert.ok(close.indexOf('closeBoardItem') < close.indexOf('emitItemClosed(closed'),
+    'the mirror event fires AFTER the close commits — the row is the durable fact');
+  const passEmit = close.indexOf("emitAsync('board.item.passed'");
+  assert.ok(passEmit < close.indexOf('emitItemClosed(closed'),
+    "the credit lane's contract event still goes first");
+  const closedEmit = board.slice(board.indexOf('async function emitItemClosed'));
+  assert.match(closedEmit, /emitAsync\('board\.item\.closed'/, 'the event exists');
+  assert.match(closedEmit, /outcome: closed\.outcome/, 'it carries the outcome — a return mirrors too');
+  assert.match(closedEmit, /tally: \{/, 'it carries the tally so no consumer re-reads votes');
+  const passBlock = board.slice(board.indexOf('function passPayload'), board.indexOf('// Close an item'));
+  assert.ok(!/tally/.test(passBlock), 'the pass CONTRACT payload stays the seven fields — no tally (ADR 0175 / the pass-event spec)');
+  const routes = fs.readFileSync(path.join(ROOT, 'modules', 'discord', 'routes', 'discord.js'), 'utf8');
+  assert.match(routes, /api\.on\('board\.item\.closed', \(payload\) => boardBroadcast\.postBoardOutcome\(payload\)\)/,
+    'the discord module subscribes to the close as well');
+});
+
+test('the poster asks for the message back, the edit rings NOBODY, and the mirror table is discord-owned', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules', 'discord', 'webhook.js'), 'utf8');
+  const core = src.slice(src.indexOf('async function postCore'), src.indexOf('// SECURITY (#871)'));
+  assert.match(core, /wait=true/, 'the POST asks Discord for the created message — that id is what R22 edits');
+  assert.match(core, /message_id: message && message\.id/, 'the id is surfaced to the caller');
+  const edit = src.slice(src.indexOf('async function editWebhook'));
+  assert.match(edit, /method: 'PATCH'/);
+  assert.match(edit, /\/messages\/\$\{encodeURIComponent\(String\(messageId\)\)\}/, 'a webhook may only edit its OWN message');
+  assert.match(edit, /allowed_mentions: \{ parse: \[\] \}/, 'an edit is an outcome notice, not a summons — it must never re-ring the board');
+  assert.ok(!/users/.test(edit), 'the mention exception stays scoped to the one post that means "your vote is wanted"');
+  const sql = fs.readFileSync(path.join(ROOT, 'modules', 'discord', 'migrations', 'discord_001_board_messages.sql'), 'utf8');
+  assert.match(sql, /CREATE TABLE IF NOT EXISTS discord_board_messages/);
+  assert.ok(!/REFERENCES government_board_items/.test(sql),
+    'no FK across the module boundary — the mirror never constrains government\'s schema');
+  assert.match(sql, /item_id\s+bigint\s+PRIMARY KEY/, 'one announcement per sitting, edited in place');
+  const manifest = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules', 'discord', 'module.json'), 'utf8'));
+  assert.equal(manifest.contributes.migrations, true, 'the module now owns a migration and says so');
+});

package/tests/goal_conflicts.mjs

@@ -162,8 +162,8 @@ await test('detector: no inputs → no conflicts (and never throws)', () => {
 // =========================================================================
 
 const OPEN_GOAL = { id: 7, status: 'open', created_by: '1' };
-const manager = (builderId) => ({ goal_id: 7, builder_id: builderId, role: 'lead' });
-const member = (builderId) => ({ goal_id: 7, builder_id: builderId, role: 'member' });
+const manager = (builderId) => ({ goal_id: 7, builder_id: builderId, membership_kind: 'lead' });
+const member = (builderId) => ({ goal_id: 7, builder_id: builderId, membership_kind: 'member' });
 
 await test('gate: owner / manager / archon pass; ordering goal_not_found → goal_not_open → not_owner_or_manager', () => {
   for (const actor of [
@@ -182,7 +182,7 @@ await test('gate: owner / manager / archon pass; ordering goal_not_found → goa
   assert.equal(denied.body.error, 'not_owner_or_manager', 'a plain member cannot manage');
 });
 
-await test('gate: owner authority is created_by, not the role row', () => {
+await test('gate: owner authority is created_by, not the membership row', () => {
   const d = authorizeGoalManagement({ goal: OPEN_GOAL, actorId: 1, actorRank: 'metic', actorMembership: member(1) });
   assert.deepEqual(d, { ok: true });
 });

package/tests/{goal_member_roles.mjs → goal_member_kinds.mjs}

@@ -1,18 +1,18 @@
-// tests/goal_member_roles.mjs — the goal owner/manager authority model (task 1735).
+// tests/goal_member_kinds.mjs — the goal owner/manager authority model (task 1735).
 //
 // The model: the OWNER is goals.created_by — the fixed authority, set at create
-// and moved only via POST /goals/:id/transfer. MANAGER is the goal_members.role
+// and moved only via POST /goals/:id/transfer. MANAGER is the goal_members.membership_kind
 // 'lead' value (the hall renders it "manager"), owner-equivalent EXCEPT that a
 // manager cannot demote a fellow manager (owner-only) and cannot transfer
 // ownership. The owner's own row is never demotable. This file pins, in the
 // goal_routes pattern:
 //
-//   1. the PURE ordered gates (authorizeMemberRoleChange +
+//   1. the PURE ordered gates (authorizeMembershipKindChange +
 //      authorizeOwnershipTransfer) — every rejection, DB-free, ordering
 //      included (the authorizeGoalTaskCreate precedent);
 //   2. the request-validation schema of the PATCH route;
 //   3. the db helpers' SQL contracts via the SQL-aware fake pool —
-//      getGoalMember / setGoalMemberRole (the atomic owner-demotion guard) /
+//      getGoalMember / setGoalMembershipKind (the atomic owner-demotion guard) /
 //      transferGoalOwnership (atomic created_by move + lead upsert);
 //      createGoal's creator-becomes-owner CTE lives in tests/goal_tier.mjs;
 //   4. the route-rank PINS: both routes stay 'any-builder' (the wall is
@@ -26,14 +26,14 @@
 //   B   manager promotes a member → manager                 → ALLOW (owner-equivalent)
 //   C   owner demotes a manager → member                    → ALLOW
 //   D   manager demotes a fellow manager                    → 403 owner_only_demotion
-//   E   owner/Archon demotes the OWNER's row                → 409 owner_role_fixed
-//   F   plain member tries any role change                  → 403 not_owner_or_manager
-//   G   non-member Metic tries any role change              → 403 not_owner_or_manager
+//   E   owner/Archon demotes the OWNER's row                → 409 owner_membership_fixed
+//   F   plain member tries any membership change                  → 403 not_owner_or_manager
+//   G   non-member Metic tries any membership change              → 403 not_owner_or_manager
 //   H   Archon (not a member) promotes and demotes          → ALLOW (the Archon arm)
 //   I   target isn't a member                               → 404 not_a_member
 //   J   goal doesn't exist                                  → 404 goal_not_found
 //   K   goal not open (achieved/archived)                   → 409 goal_not_open
-//   L   role already as requested                           → no-op (ok, changed:false)
+//   L   membership already as requested                           → no-op (ok, changed:false)
 //   O1  ordering: unauthorized actor + non-member target    → not_owner_or_manager (no membership leak)
 //   O2  ordering: closed goal short-circuits everything     → goal_not_open
 //
@@ -47,7 +47,7 @@
 //   T6  transfer to the current owner                       → no-op
 //   T7  closed goal / unknown goal                          → 409 / 404
 //
-// Run:  node tests/goal_member_roles.mjs
+// Run:  node tests/goal_member_kinds.mjs
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
@@ -57,8 +57,8 @@ process.env.NODE_ENV = 'test';
 
 const require = createRequire(import.meta.url);
 const { validate } = require('../src/bongos/routes/_helpers.js');
-const { authorizeMemberRoleChange, authorizeOwnershipTransfer } = require('../modules/lifecycle/routes/goals.js');
-const { getGoalMember, setGoalMemberRole, transferGoalOwnership } = require('../modules/lifecycle/db.js');
+const { authorizeMembershipKindChange, authorizeOwnershipTransfer } = require('../modules/lifecycle/routes/goals.js');
+const { getGoalMember, setGoalMembershipKind, transferGoalOwnership } = require('../modules/lifecycle/db.js');
 const { MODULE_EXPECTED_RANKS } = require('../src/bongos/route-rank-check.js');
 
 const { test, summary } = makeRunner();
@@ -74,49 +74,49 @@ const find = (queries, re) => queries.find((q) => re.test(String(q.sql).replace(
 // must compare loosely (String-normalized), exactly as the route receives it.
 const OPEN_GOAL = { id: 7, status: 'open', created_by: '1' };
 const ORPHAN_GOAL = { id: 8, status: 'open', created_by: null }; // migration-160 default
-const manager = (builderId) => ({ goal_id: 7, builder_id: builderId, role: 'lead', joined_at: 'T0' });
-const member = (builderId) => ({ goal_id: 7, builder_id: builderId, role: 'member', joined_at: 'T1' });
+const manager = (builderId) => ({ goal_id: 7, builder_id: builderId, membership_kind: 'lead', joined_at: 'T0' });
+const member = (builderId) => ({ goal_id: 7, builder_id: builderId, membership_kind: 'member', joined_at: 'T1' });
 
 // =========================================================================
-// 1a. authorizeMemberRoleChange — the role-change matrix
+// 1a. authorizeMembershipKindChange — the membership-change matrix
 // =========================================================================
 
 await test('A: the owner promotes a member → manager — ALLOW', () => {
-  const d = authorizeMemberRoleChange({
+  const d = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 1, actorRank: 'metic', actorMembership: manager(1),
-    targetMembership: member(2), targetId: 2, role: 'lead',
+    targetMembership: member(2), targetId: 2, membershipKind: 'lead',
   });
   assert.deepEqual(d, { ok: true });
 });
 
-await test('A2: owner authority is created_by, not the role row — owner with a plain member row still promotes', () => {
-  const d = authorizeMemberRoleChange({
+await test('A2: owner authority is created_by, not the membership row — owner with a plain member row still promotes', () => {
+  const d = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 1, actorRank: 'metic', actorMembership: member(1),
-    targetMembership: member(2), targetId: 2, role: 'lead',
+    targetMembership: member(2), targetId: 2, membershipKind: 'lead',
   });
   assert.deepEqual(d, { ok: true });
 });
 
 await test('B: a manager promotes a member → manager — ALLOW (owner-equivalent)', () => {
-  const d = authorizeMemberRoleChange({
+  const d = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 3, actorRank: 'metic', actorMembership: manager(3),
-    targetMembership: member(2), targetId: 2, role: 'lead',
+    targetMembership: member(2), targetId: 2, membershipKind: 'lead',
   });
   assert.deepEqual(d, { ok: true });
 });
 
 await test('C: the owner demotes a manager → member — ALLOW', () => {
-  const d = authorizeMemberRoleChange({
+  const d = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 1, actorRank: 'metic', actorMembership: manager(1),
-    targetMembership: manager(3), targetId: 3, role: 'member',
+    targetMembership: manager(3), targetId: 3, membershipKind: 'member',
   });
   assert.deepEqual(d, { ok: true });
 });
 
 await test('D: a manager cannot demote a fellow manager — 403 owner_only_demotion', () => {
-  const d = authorizeMemberRoleChange({
+  const d = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 3, actorRank: 'metic', actorMembership: manager(3),
-    targetMembership: manager(4), targetId: 4, role: 'member',
+    targetMembership: manager(4), targetId: 4, membershipKind: 'member',
   });
   assert.equal(d.ok, false);
   assert.equal(d.status, 403);
@@ -124,32 +124,32 @@ await test('D: a manager cannot demote a fellow manager — 403 owner_only_demot
 });
 
 await test('D2: a manager cannot demote themselves either — same owner-only rule', () => {
-  const d = authorizeMemberRoleChange({
+  const d = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 3, actorRank: 'metic', actorMembership: manager(3),
-    targetMembership: manager(3), targetId: 3, role: 'member',
+    targetMembership: manager(3), targetId: 3, membershipKind: 'member',
   });
   assert.equal(d.body.error, 'owner_only_demotion');
 });
 
-await test('E: the OWNER row is never demotable — 409 owner_role_fixed (even self / Archon)', () => {
+await test('E: the OWNER row is never demotable — 409 owner_membership_fixed (even self / Archon)', () => {
   for (const actor of [
     { actorId: 1, actorRank: 'metic', actorMembership: manager(1) }, // owner themselves
     { actorId: 99, actorRank: 'archon', actorMembership: null },     // an Archon
   ]) {
-    const d = authorizeMemberRoleChange({
+    const d = authorizeMembershipKindChange({
       goal: OPEN_GOAL, ...actor,
-      targetMembership: manager(1), targetId: 1, role: 'member',
+      targetMembership: manager(1), targetId: 1, membershipKind: 'member',
     });
     assert.equal(d.ok, false, `${actor.actorRank} demoting the owner must refuse`);
     assert.equal(d.status, 409);
-    assert.equal(d.body.error, 'owner_role_fixed');
+    assert.equal(d.body.error, 'owner_membership_fixed');
   }
 });
 
-await test('F: a plain member cannot change roles — 403 not_owner_or_manager', () => {
-  const d = authorizeMemberRoleChange({
+await test('F: a plain member cannot change memberships — 403 not_owner_or_manager', () => {
+  const d = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 2, actorRank: 'metic', actorMembership: member(2),
-    targetMembership: member(5), targetId: 5, role: 'lead',
+    targetMembership: member(5), targetId: 5, membershipKind: 'lead',
   });
   assert.equal(d.ok, false);
   assert.equal(d.status, 403);
@@ -157,38 +157,38 @@ await test('F: a plain member cannot change roles — 403 not_owner_or_manager',
 });
 
 await test('G: a non-member (whatever their rank below archon) — 403 not_owner_or_manager', () => {
-  const d = authorizeMemberRoleChange({
+  const d = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 9, actorRank: 'metic', actorMembership: null,
-    targetMembership: member(2), targetId: 2, role: 'lead',
+    targetMembership: member(2), targetId: 2, membershipKind: 'lead',
   });
   assert.equal(d.body.error, 'not_owner_or_manager');
 });
 
 await test('H: an Archon who is not a member may promote AND demote — the Archon arm', () => {
-  const promote = authorizeMemberRoleChange({
+  const promote = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 99, actorRank: 'archon', actorMembership: null,
-    targetMembership: member(2), targetId: 2, role: 'lead',
+    targetMembership: member(2), targetId: 2, membershipKind: 'lead',
   });
   assert.deepEqual(promote, { ok: true });
-  const demote = authorizeMemberRoleChange({
+  const demote = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 99, actorRank: 'archon', actorMembership: null,
-    targetMembership: manager(3), targetId: 3, role: 'member',
+    targetMembership: manager(3), targetId: 3, membershipKind: 'member',
   });
   assert.deepEqual(demote, { ok: true });
 });
 
 await test('H2: an ownerless goal (created_by NULL) is Archon-run — a manager there still cannot demote', () => {
-  const d = authorizeMemberRoleChange({
+  const d = authorizeMembershipKindChange({
     goal: ORPHAN_GOAL, actorId: 3, actorRank: 'metic', actorMembership: manager(3),
-    targetMembership: manager(4), targetId: 4, role: 'member',
+    targetMembership: manager(4), targetId: 4, membershipKind: 'member',
   });
   assert.equal(d.body.error, 'owner_only_demotion', 'no owner exists, so only an Archon demotes');
 });
 
 await test('I: target is not a member — 404 not_a_member', () => {
-  const d = authorizeMemberRoleChange({
+  const d = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 1, actorRank: 'metic', actorMembership: manager(1),
-    targetMembership: null, targetId: 5, role: 'lead',
+    targetMembership: null, targetId: 5, membershipKind: 'lead',
   });
   assert.equal(d.ok, false);
   assert.equal(d.status, 404);
@@ -196,19 +196,19 @@ await test('I: target is not a member — 404 not_a_member', () => {
 });
 
 await test('J: unknown goal — 404 goal_not_found (fail-closed on missing input)', () => {
-  const d = authorizeMemberRoleChange({
+  const d = authorizeMembershipKindChange({
     goal: null, actorId: 99, actorRank: 'archon', actorMembership: null,
-    targetMembership: null, targetId: 2, role: 'lead',
+    targetMembership: null, targetId: 2, membershipKind: 'lead',
   });
   assert.equal(d.status, 404);
   assert.equal(d.body.error, 'goal_not_found');
 });
 
-await test('K: a non-open goal refuses role changes — 409 goal_not_open', () => {
+await test('K: a non-open goal refuses membership changes — 409 goal_not_open', () => {
   for (const status of ['achieved', 'archived']) {
-    const d = authorizeMemberRoleChange({
+    const d = authorizeMembershipKindChange({
       goal: { id: 7, status, created_by: '1' }, actorId: 1, actorRank: 'metic',
-      actorMembership: manager(1), targetMembership: member(2), targetId: 2, role: 'lead',
+      actorMembership: manager(1), targetMembership: member(2), targetId: 2, membershipKind: 'lead',
     });
     assert.equal(d.ok, false, `status=${status} must refuse`);
     assert.equal(d.status, 409);
@@ -216,34 +216,34 @@ await test('K: a non-open goal refuses role changes — 409 goal_not_open', () =
   }
 });
 
-await test('L: role already as requested — no-op, not an error (idempotent PATCH)', () => {
-  const d = authorizeMemberRoleChange({
+await test('L: membership already as requested — no-op, not an error (idempotent PATCH)', () => {
+  const d = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 1, actorRank: 'metic', actorMembership: manager(1),
-    targetMembership: manager(3), targetId: 3, role: 'lead',
+    targetMembership: manager(3), targetId: 3, membershipKind: 'lead',
   });
   assert.deepEqual(d, { ok: true, noop: true });
 });
 
 await test('L2: the no-op wins over the demotion rules — re-demoting an already-member target', () => {
-  const d = authorizeMemberRoleChange({
+  const d = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 3, actorRank: 'metic', actorMembership: manager(3),
-    targetMembership: member(2), targetId: 2, role: 'member',
+    targetMembership: member(2), targetId: 2, membershipKind: 'member',
   });
   assert.deepEqual(d, { ok: true, noop: true }, 'a manager "demoting" a member to member is a no-op, not owner_only_demotion');
 });
 
 await test('O1: ordering — an unauthorized actor learns nothing about the target', () => {
-  const d = authorizeMemberRoleChange({
+  const d = authorizeMembershipKindChange({
     goal: OPEN_GOAL, actorId: 2, actorRank: 'metic', actorMembership: member(2),
-    targetMembership: null, targetId: 5, role: 'lead',
+    targetMembership: null, targetId: 5, membershipKind: 'lead',
   });
   assert.equal(d.body.error, 'not_owner_or_manager', 'authority is checked BEFORE the target lookup');
 });
 
 await test('O2: ordering — a closed goal short-circuits before authority', () => {
-  const d = authorizeMemberRoleChange({
+  const d = authorizeMembershipKindChange({
     goal: { id: 7, status: 'archived', created_by: '1' }, actorId: 2, actorRank: 'metic',
-    actorMembership: member(2), targetMembership: null, targetId: 5, role: 'lead',
+    actorMembership: member(2), targetMembership: null, targetId: 5, membershipKind: 'lead',
   });
   assert.equal(d.body.error, 'goal_not_open');
 });
@@ -316,27 +316,36 @@ await test('T7: unknown goal → 404; closed goal → 409 (fail-closed ordering)
 // =========================================================================
 // 2. request-validation schema — the EXACT schema declared in goals.js's
 //    PATCH /goals/:id/members/:builderId; keep in sync if the route changes.
-//    (role's lead|member vocabulary is an in-handler check → 400 bad_role, and
+//    (the lead|member vocabulary is an in-handler check → 400 bad_membership_kind, and
 //    the transfer route coerces builder_id in-handler — the /members precedent.)
 // =========================================================================
 
-const PATCH_MEMBER_ROLE_SCHEMA = {
-  role: { required: true, type: 'string' },
+const PATCH_MEMBER_SCHEMA = {
+  membership_kind: { required: true, type: 'string' },
 };
 
-await test('PATCH schema: role required', () => {
-  const r = validate({}, PATCH_MEMBER_ROLE_SCHEMA);
-  assert.ok(r && r.details.some((d) => d.field === 'role' && d.reason === 'missing'));
+await test('PATCH schema: membership_kind required', () => {
+  const r = validate({}, PATCH_MEMBER_SCHEMA);
+  assert.ok(r && r.details.some((d) => d.field === 'membership_kind' && d.reason === 'missing'));
 });
 
-await test('PATCH schema: non-string role → wrong_type', () => {
-  const r = validate({ role: 42 }, PATCH_MEMBER_ROLE_SCHEMA);
-  assert.ok(r && r.details.some((d) => d.field === 'role' && d.reason === 'wrong_type'));
+await test('PATCH schema: non-string membership_kind → wrong_type', () => {
+  const r = validate({ membership_kind: 42 }, PATCH_MEMBER_SCHEMA);
+  assert.ok(r && r.details.some((d) => d.field === 'membership_kind' && d.reason === 'wrong_type'));
 });
 
-await test('PATCH schema: role=lead / role=member pass', () => {
-  assert.equal(validate({ role: 'lead' }, PATCH_MEMBER_ROLE_SCHEMA), null);
-  assert.equal(validate({ role: 'member' }, PATCH_MEMBER_ROLE_SCHEMA), null);
+await test('PATCH schema: membership_kind=lead / =member pass', () => {
+  assert.equal(validate({ membership_kind: 'lead' }, PATCH_MEMBER_SCHEMA), null);
+  assert.equal(validate({ membership_kind: 'member' }, PATCH_MEMBER_SCHEMA), null);
+});
+
+await test('the RESERVED WORD is gone from the goal-membership surface (task 1003013, ADR 0174)', () => {
+  // A body that still says `role` no longer satisfies the schema — the rename is
+  // a contract change, not an alias, so this pins the ABSENCE of the old field
+  // (the ADR 0174 lesson: a shim that outlives its release is a lie).
+  const r = validate({ role: 'lead' }, PATCH_MEMBER_SCHEMA);
+  assert.ok(r && r.details.some((d) => d.field === 'membership_kind' && d.reason === 'missing'),
+    'the old field name buys nothing — membership_kind is required');
 });
 
 await test('transfer builder_id coercion contract: int + numeric string pass, junk rejected', () => {
@@ -350,7 +359,7 @@ await test('transfer builder_id coercion contract: int + numeric string pass, ju
 // 3. db helpers — SQL contracts via the SQL-aware fake pool
 // =========================================================================
 
-const MEMBER_ROW = { goal_id: 7, builder_id: 42, role: 'lead', joined_at: 'T0' };
+const MEMBER_ROW = { goal_id: 7, builder_id: 42, membership_kind: 'lead', joined_at: 'T0' };
 const GOAL_ROW = {
   id: 7, version_id: 'BONGOS-V1', title: 'g', description: null, scope_modules: [],
   status: 'open', created_by: 5, succeeded_by_goal_id: null, created_at: 'T0', updated_at: 'T1',
@@ -360,16 +369,16 @@ await test('getGoalMember: SELECT by (goal_id, builder_id), returns the row or n
   const pool = fakePool((s) => (/FROM goal_members WHERE goal_id = \$1 AND builder_id = \$2/.test(s) ? { rows: [MEMBER_ROW] } : null));
   const out = await getGoalMember({ goalId: 7, builderId: 42 }, { pool });
   assert.deepEqual(out, MEMBER_ROW);
-  const sel = find(pool.queries, /SELECT goal_id, builder_id, role, joined_at FROM goal_members/);
+  const sel = find(pool.queries, /SELECT goal_id, builder_id, membership_kind, joined_at FROM goal_members/);
   assert.deepEqual(sel.params, [7, 42]);
 
   const empty = fakePool(() => ({ rows: [] }));
   assert.equal(await getGoalMember({ goalId: 7, builderId: 99 }, { pool: empty }), null);
 });
 
-await test('setGoalMemberRole: the UPDATE carries the atomic owner-demotion guard', async () => {
+await test('setGoalMembershipKind: the UPDATE carries the atomic owner-demotion guard', async () => {
   const pool = fakePool((s) => (/UPDATE goal_members/.test(s) ? { rows: [MEMBER_ROW] } : null));
-  const out = await setGoalMemberRole({ goalId: 7, builderId: 42, role: 'lead' }, { pool });
+  const out = await setGoalMembershipKind({ goalId: 7, builderId: 42, membershipKind: 'lead' }, { pool });
   assert.deepEqual(out, MEMBER_ROW);
   const upd = find(pool.queries, /UPDATE goal_members/);
   assert.deepEqual(upd.params, [7, 42, 'lead']);
@@ -378,12 +387,12 @@ await test('setGoalMemberRole: the UPDATE carries the atomic owner-demotion guar
   const sql = String(upd.sql).replace(/\s+/g, ' ');
   assert.match(sql, /\$3 = 'lead' OR gm\.builder_id IS DISTINCT FROM \(SELECT g\.created_by FROM goals g WHERE g\.id = \$1\)/,
     'the owner-demotion guard is IN the statement, not only in the route gate');
-  assert.match(sql, /RETURNING goal_id, builder_id, role, joined_at/);
+  assert.match(sql, /RETURNING goal_id, builder_id, membership_kind, joined_at/);
 });
 
-await test('setGoalMemberRole: guard blocked / no such member → null (route answers 409)', async () => {
+await test('setGoalMembershipKind: guard blocked / no such member → null (route answers 409)', async () => {
   const pool = fakePool(() => ({ rows: [] }));
-  assert.equal(await setGoalMemberRole({ goalId: 7, builderId: 42, role: 'member' }, { pool }), null);
+  assert.equal(await setGoalMembershipKind({ goalId: 7, builderId: 42, membershipKind: 'member' }, { pool }), null);
 });
 
 await test('transferGoalOwnership: created_by moves and the new owner upserts to lead, one statement', async () => {
@@ -393,9 +402,9 @@ await test('transferGoalOwnership: created_by moves and the new owner upserts to
   const upd = find(pool.queries, /UPDATE goals SET created_by = \$2/);
   assert.deepEqual(upd.params, [7, 5]);
   const sql = String(upd.sql).replace(/\s+/g, ' ');
-  assert.match(sql, /INSERT INTO goal_members \(goal_id, builder_id, role\)/,
+  assert.match(sql, /INSERT INTO goal_members \(goal_id, builder_id, membership_kind\)/,
     'the new owner\'s membership rides in the same statement');
-  assert.match(sql, /ON CONFLICT \(goal_id, builder_id\) DO UPDATE SET role = 'lead'/,
+  assert.match(sql, /ON CONFLICT \(goal_id, builder_id\) DO UPDATE SET membership_kind = 'lead'/,
     'an existing membership upgrades to lead rather than erroring');
   assert.match(sql, /updated_at = now\(\)/);
 });
@@ -409,7 +418,7 @@ await test('transferGoalOwnership: unknown goal → null', async () => {
 // 4. the route-rank pins — the wall is in-handler, the pins keep it that way
 // =========================================================================
 
-await test('route-rank pins: role change + transfer stay any-builder (in-handler walls)', () => {
+await test('route-rank pins: membership change + transfer stay any-builder (in-handler walls)', () => {
   const pins = MODULE_EXPECTED_RANKS.lifecycle;
   assert.equal(pins['PATCH /goals/:id/members/:builderId'], 'any-builder',
     'the owner/manager wall is in-handler — a requireRank re-gate must be a red build');