@bongos/core 1.19.517 → 1.19.518

package/docs/module-api-changelog.md

@@ -1471,5 +1471,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.515 with no explicit bump. run 33798954769. (task 1002620)
   1.19.517 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.516 with no explicit bump. run 33799755382. (task 1002620)
+  1.19.518 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.517 with no explicit bump. run 33801792364. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/builder-settings/builder-needs.js

@@ -191,7 +191,33 @@ function boardVotesNeed(ctx) {
   };
 }
 
-const NEEDS = [artKeyNeed, helpRequestsNeed, taskRecommendationsNeed, boardVotesNeed];
+// task 1003178 (C08, goal 1000075): an open mingle INTRODUCTION waiting on you.
+// Third sibling of the two collab needs above, here for the same reason and with
+// the same posture — an introduction nobody surfaces is merely stored, and the
+// needs roster is how a collab feature reaches the whole hall instead of sitting
+// on a page of its own (which is the thing C08's criterion refuses).
+//
+// 'info' and NEVER a demand, and the wording carries that: mingle is declinable
+// without penalty (C07, ADR 0187 §5), so copy that pressured the reader would BE
+// the penalty the decision forbids. The same argument the recommendation need
+// makes, applied to a social invitation, where it matters more.
+function mingleIntroductionsNeed(ctx) {
+  const n = Number(ctx.openMingleIntroductions) || 0;
+  if (n <= 0) return null;
+  const subject = n === 1 ? 'An introduction is' : `${n} introductions are`;
+  return {
+    id: 'mingle_introductions',
+    title: n === 1 ? 'Someone from another craft was introduced to you' : 'You have introductions waiting',
+    what: 'Mingle pairs builders across crafts — you opted in, and a pairing is waiting on your answer.',
+    state: 'action_needed',
+    severity: 'info',
+    message: `${subject} waiting on you. Saying no costs nothing at all — no rank, no karma, no streak, `
+      + 'and it does not change how often you are paired again.',
+    action: { label: n === 1 ? 'See the introduction' : 'See the introductions', href: '/#/collab' },
+  };
+}
+
+const NEEDS = [artKeyNeed, helpRequestsNeed, taskRecommendationsNeed, boardVotesNeed, mingleIntroductionsNeed];
 
 // ---- founding grace (task 1002739 / direction §5.6, idea 1000701) -----------
 //
@@ -269,7 +295,7 @@ module.exports = {
   computeNeeds,
   // exported for tests / direct reuse
   artKeyNeed,
-  helpRequestsNeed, taskRecommendationsNeed, boardVotesNeed,
+  helpRequestsNeed, taskRecommendationsNeed, boardVotesNeed, mingleIntroductionsNeed,
   foundingGraceActive,
   FOUNDING_GRACE_DAYS,
   SETTINGS_PATH,

package/modules/hall-ui/public/collab.html

@@ -46,6 +46,25 @@
           </div>
         </section>
 
+        <!-- SOCIAL MODE ONLY (task 1003178 / C08). Not a page and not a nav item:
+             this panel is part of Collab, and it appears because the hall is in
+             social mode — the shell stamps data-social="on" on the document root
+             from /me, and collab.js reveals this section from that. With social
+             off the page is exactly what it was, which is the point: the hall
+             changes, it does not gain a destination. -->
+        <section class="scroll" id="cb-mingle-section" aria-labelledby="cb-mingle-h" hidden>
+          <h2 class="scroll__h" id="cb-mingle-h">Introductions</h2>
+          <p class="scroll__lede" id="cb-mingle-note">
+            Mingle pairs you with someone from a different craft. Saying no costs nothing
+            at all — no rank, no karma, no streak, and it does not change how often you
+            are paired again.
+          </p>
+          <ul class="ov-rows" id="cb-mingle"></ul>
+          <div class="empty-state" id="cb-mingle-empty" hidden>
+            <p>No introductions right now. You will see one here when a pairing round runs.</p>
+          </div>
+        </section>
+
         <section class="scroll" aria-labelledby="cb-mine-h">
           <h2 class="scroll__h" id="cb-mine-h">Your asks</h2>
           <p class="scroll__lede">

package/modules/hall-ui/public/collab.js

@@ -143,6 +143,78 @@
         ? `Matching your craft: ${crafts.join(', ')}.`
         : 'You have not set a craft, so only requests addressed to you by name reach you.';
     }
+
+    // The social half. Best-effort and LAST: an introductions read that fails
+    // must never take the help requests down with it — those are the page.
+    try { await loadMingle(); } catch (_) { /* the panel stays as it was */ }
+  }
+
+  // ---- social mode: introductions (task 1003178 / C08) ----------------------
+  //
+  // READ THE MODE OFF THE DOCUMENT, never re-derive it. The shell stamps
+  // data-social="on" from /me's resolved pair of switches (C07: the project
+  // enabled mingle AND this builder opted in). Asking the server again here would
+  // be a second answer to one question, and a page that decided for itself
+  // whether social was on could disagree with the rest of the hall.
+  const socialOn = () => document.documentElement.dataset.social === 'on';
+
+  // The other person in the pair — the row is written from the VIEWER's side, so
+  // it names who they were introduced to rather than echoing both ids back.
+  function otherOf(pair, meId) {
+    const lo = String(pair.builder_lo), hi = String(pair.builder_hi);
+    return String(meId) === lo
+      ? { id: hi, login: pair.hi_login, name: pair.hi_name, craft: pair.craft_hi, myCraft: pair.craft_lo }
+      : { id: lo, login: pair.lo_login, name: pair.lo_name, craft: pair.craft_lo, myCraft: pair.craft_hi };
+  }
+
+  function mingleRow(pair, meId) {
+    const o = otherOf(pair, meId);
+    const who = escapeHtml(o.name || o.login || `builder ${o.id}`);
+    return `<li class="ov-row">
+      <div class="ov-row__main">
+        <a class="ov-row__title" href="/builders/profile?id=${escapeHtml(String(o.id))}">${who}</a>
+        <p class="ov-row__sub">A ${escapeHtml(String(o.craft))} — you are a ${escapeHtml(String(o.myCraft))}. Mingle pairs across crafts.</p>
+      </div>
+      <div class="ov-row__right">
+        <div class="ov-row__actions">
+          <button class="btn-accent" data-mingle="accepted" data-id="${escapeHtml(String(pair.id))}">Say yes</button>
+          <button class="btn-ghost" data-mingle="declined" data-id="${escapeHtml(String(pair.id))}">Not now</button>
+        </div>
+      </div>
+    </li>`;
+  }
+
+  async function loadMingle() {
+    const section = $('#cb-mingle-section');
+    if (!section) return;
+    // Off is off: the section stays hidden and nothing is fetched. A page that
+    // fetched anyway would make "social is off" cost a request on every load.
+    if (!socialOn()) { section.hidden = true; return; }
+    section.hidden = false;
+
+    const r = await api.request('GET', '/mingle');
+    const pairs = (r.ok && r.data && r.data.open_pairs) || [];
+    const meId = (r.ok && r.data && r.data.you) || null;
+    paint('#cb-mingle', '#cb-mingle-empty', pairs.map((p) => mingleRow(p, meId)).join(''), pairs.length);
+  }
+
+  async function decideMingle(id, decision) {
+    if (settling) return;
+    settling = true;
+    try {
+      const r = await api.request('POST', `/mingle/pairs/${id}/decide`, { decision });
+      if (!r.ok) {
+        toast(window.OTB.errMessage ? window.OTB.errMessage(r.data) : 'Could not answer that introduction.');
+        return;
+      }
+      // Neutral either way. "Declined" must not read as a failure — declining is
+      // free, and a toast that sounded disappointed would be the penalty C07's
+      // decision forbids, delivered by the UI instead of the schema.
+      toast(decision === 'accepted' ? 'Said yes — say hello.' : 'Not now. Nothing changes for you.');
+      await load();
+    } finally {
+      settling = false;
+    }
   }
 
   async function settle(id, status) {
@@ -162,6 +234,12 @@
   }
 
   document.addEventListener('click', (ev) => {
+    const mingleBtn = ev.target && ev.target.closest ? ev.target.closest('[data-mingle]') : null;
+    if (mingleBtn) {
+      ev.preventDefault();
+      decideMingle(Number(mingleBtn.getAttribute('data-id')), mingleBtn.getAttribute('data-mingle'));
+      return;
+    }
     const btn = ev.target && ev.target.closest ? ev.target.closest('[data-settle]') : null;
     if (!btn) return;
     ev.preventDefault();

package/modules/hall-ui/public/hall-render.js

@@ -205,6 +205,12 @@
       rank: normalizeRank(builder?.rank),
       graduated,
       showWork: shipStepCurrent,
+      // task 1003178 (C08): the index owns its own /me, so it passes the social
+      // mode through too — otherwise the hall's busiest page would be the one
+      // page the mode never reached. Read off ctx.lastMeState (the live getter),
+      // not a local: renderNav takes (builder, onboarding) and is called from
+      // five sites, so there is no `me` in scope here.
+      social: (ctx.lastMeState && ctx.lastMeState.social) || null,
       builder,
     });
 

package/modules/hall-ui/public/shell.js

@@ -522,7 +522,32 @@
     }
   }
 
-  // applyAccess({ authed, rank, graduated, showWork }) — settle nav visibility.
+  // SOCIAL MODE (task 1003178 / C08, goal 1000075). The owner's directive is that
+  // social is "scoped into the ENTIRE builders hall, not a single social tab", and
+  // the criterion says outright that a /social route with the same hall around it
+  // does NOT satisfy it. So social is a MODE stamped on the document root, beside
+  // data-theme and for the same reason: every hall page loads this shell, so one
+  // attribute lets any surface — a stylesheet, a page script, a widget — read the
+  // mode without a route, a nav item, or a second fetch.
+  //
+  // OFF is the default and the fallback. `/me.social` is null when lifecycle is
+  // disabled or the read failed, and null is OFF: a mode that cannot be read is
+  // not on. It is only ON when BOTH of C07's switches are (the project enabled
+  // mingle AND this builder opted in) — the server resolves that pair, this never
+  // re-derives it.
+  //
+  // Written as an attribute rather than kept in `access` on purpose: CSS can hit
+  // it (`:root[data-social="on"] …`), which is what lets a surface change how it
+  // READS without every page script learning about social.
+  function applySocial(social) {
+    var on = !!(social && social.enabled === true);
+    var root = document.documentElement;
+    if (on) root.dataset.social = 'on';
+    else delete root.dataset.social;
+  }
+
+  // applyAccess({ authed, rank, graduated, showWork, social }) — settle nav
+  // visibility and the social mode.
   // Called by builders.js on the index (it owns /me there) and by the shell's own
   // probe elsewhere. Cosmetic only; the server enforces (ADR 0016).
   function applyAccess(state) {
@@ -531,6 +556,7 @@
       if ('rank' in state) access.rank = state.rank ? String(state.rank).toLowerCase() : null;
       if ('graduated' in state) access.graduated = !!state.graduated;
       if ('showWork' in state) access.showWork = !!state.showWork;
+      if ('social' in state) applySocial(state.social);
       if (state.builder) renderUser(state.builder);
     }
     document.querySelectorAll('#app-sidebar [data-gate]').forEach(function (el) {
@@ -744,6 +770,9 @@
         rank: me.builder.rank,
         graduated: !!(me.onboarding && me.onboarding.graduated),
         showWork: showWork,
+        // task 1003178 (C08): the mode rides the identity every page already
+        // fetches, so no surface needs a route or a second call to know.
+        social: me.social || null,
         builder: me.builder,
       });
     }).catch(function () { /* cosmetic only */ });

package/modules/lifecycle/lifecycle.js

@@ -22,6 +22,7 @@ const goalSuggest = require('./goal-suggest');
 const helpRequests = require('./help-requests');
 const taskRecommendations = require('./task-recommendations');
 const activity = require('./activity');
+const mingle = require('./mingle');
 
 module.exports = {
   // --- retired doorway leaks (ADR 0093 §3) ---------------------------------
@@ -52,6 +53,13 @@ module.exports = {
   // builder, exposed the same way and for the same reason — a recommendation
   // nobody surfaces is merely stored.
   openTaskRecommendationsFor: (...a) => taskRecommendations.countOpenForRecipient(...a),
+  // task 1003178 (C08): social MODE, and the count of open introductions. The
+  // mode is the pair of switches C07 resolved (project enabled AND this builder
+  // opted in) — the kernel's /me carries it so every hall surface can read the
+  // mode WITHOUT importing this module, which is what makes social a mode rather
+  // than a page. The count feeds the needs roster, the same slot C01 and C03 use.
+  socialModeFor: (...a) => mingle.mingleStateFor(...a),
+  openMingleIntroductionsFor: (...a) => mingle.countOpenPairsFor(...a),
   getTask: (...a) => db.getTask(...a),
   // findTaskBySourceRef: the create-vector idempotency read (task 1003114 / R03
   // of goal 1000074). copy-desk turns an artist's copy proposal into a task and

package/modules/lifecycle/mingle.js

@@ -306,6 +306,22 @@ async function openPairsFor(builderId, deps = {}) {
   return rows;
 }
 
+// How many open introductions are waiting on this builder — the count the hall's
+// needs roster renders (task 1003178 / C08). A COUNT rather than the rows,
+// because /me is the session-open hot path and the roster only needs a number;
+// the rows are `openPairsFor`, read by the surface that shows them.
+async function countOpenPairsFor(builderId, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT count(*)::int AS n
+       FROM lifecycle_mingle_pairs
+      WHERE status = 'proposed'
+        AND (builder_lo = $1 OR builder_hi = $1)`,
+    [builderId]
+  );
+  return rows[0] ? rows[0].n : 0;
+}
+
 // Accept or decline an introduction you are part of.
 //
 // ONE ROW, ONE TABLE. There is nothing else to write, and that absence IS the
@@ -333,5 +349,5 @@ module.exports = {
   parseEnabled, projectEnabled, setProjectEnabled,
   optInState, setOptIn, mingleStateFor,
   eligibleBuilders, isCrossCraft, planPairs, pairKey, openPairKeys,
-  runMingleRound, openPairsFor, decidePair,
+  runMingleRound, openPairsFor, countOpenPairsFor, decidePair,
 };

package/modules/lifecycle/routes/mingle.js

@@ -55,6 +55,11 @@ module.exports = function buildMingleRouter() {
     return res.json({
       mingle: state,
       open_pairs: pairs,
+      // task 1003178 (C08): WHICH SIDE OF THE PAIR THE CALLER IS. A pair row
+      // carries builder_lo/builder_hi with no marker for "you", so a surface
+      // rendering it from the viewer's side would otherwise need a second /me
+      // fetch just to find out which id to name. The route already knows.
+      you: String(req.builder.id),
       // Served VERBATIM from the module. The criterion asks for cross-craft to be
       // chosen deliberately and RECORDED; this is where it is read, and a
       // restatement here could drift from the matcher that actually runs.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.517",
+  "version": "1.19.518",
   "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/routes/me.js

@@ -105,7 +105,7 @@ module.exports = function buildMeRouter() {
       builder, activeClaims, estVsActual, unlocked, lockedWithProgress, streakInfo,
       recentGrades, builderAvg, onboardingRow, shipCount, recentKarma, karma30d, discordLink, boxConnected, cliAuthed,
       behaviorPrefs, geminiKeyRow, needsRebaseTasks, foundingBuilder, helpRequestCount,
-      taskRecommendationCount, boardVotesPending,
+      taskRecommendationCount, boardVotesPending, socialMode, mingleIntroductionCount,
     ] = await Promise.all([
       db.getBuilderById(req.builder.id),
       lc().getActiveClaimsForBuilder(req.builder.id),
@@ -205,6 +205,29 @@ module.exports = function buildMeRouter() {
           return await government.pendingBoardVotesFor(req.builder.id);
         } catch (_) { return null; }
       })(),
+      // task 1003178 (C08): SOCIAL MODE — the pair of switches C07 resolved
+      // (the project enabled mingle AND this builder opted in). It rides /me
+      // because the criterion's whole point is that social changes the HALL
+      // rather than adding a destination: every page already loads /me, so the
+      // shell can stamp the mode on the document and any surface can read it.
+      // Same fan-out slot and FAIL-OPEN posture as the reads above — null, not a
+      // throw, and the shell treats null as OFF (a mode that cannot be read is
+      // not on).
+      (async () => {
+        try {
+          const lifecycle = lc();
+          if (!lifecycle || !lifecycle.socialModeFor) return null;
+          return await lifecycle.socialModeFor(req.builder.id);
+        } catch (_) { return null; }
+      })(),
+      // The introductions waiting on this builder, for the needs roster.
+      (async () => {
+        try {
+          const lifecycle = lc();
+          if (!lifecycle || !lifecycle.openMingleIntroductionsFor) return 0;
+          return await lifecycle.openMingleIntroductionsFor(req.builder.id);
+        } catch (_) { return 0; }
+      })(),
     ]);
     // V3.R84 (#302), criterion C3: the builder's month-to-date spend vs their
     // monthly budget. Surfaced here so the CLI (session-start ping) and the hall
@@ -257,6 +280,19 @@ module.exports = function buildMeRouter() {
       // Resolved by economy (never re-derived); null if economy is disabled.
       reward: rewardPolicySafe(),
       est_vs_actual: estVsActual,
+      // task 1003178 (C08, goal 1000075): SOCIAL MODE. The owner's directive is
+      // that social is "scoped into the ENTIRE builders hall, not a single social
+      // tab", and this key is the mechanism: every hall page already loads /me,
+      // so the shell stamps the mode on the document and any surface reads it
+      // from there. A /social ROUTE is what the criterion explicitly does not
+      // accept, so there is deliberately no route to add — the mode travels with
+      // the identity the whole hall is already fetching.
+      //
+      // Shape: { enabled, project_enabled, opted_in, opted_in_at }, both switches
+      // reported separately so a surface can say WHICH half is off (C07). null
+      // when lifecycle is disabled or the read failed, and the shell treats null
+      // as OFF — a mode that cannot be read is not on.
+      social: socialMode,
       unlocked,
       locked_with_progress: lockedWithProgress,
       streak: {
@@ -354,6 +390,8 @@ module.exports = function buildMeRouter() {
         // this builder, read through the same `lifecycle` port so core never
         // imports the module (ADR 0093).
         openTaskRecommendations: taskRecommendationCount,
+        // task 1003178 (C08): open mingle introductions waiting on this builder.
+        openMingleIntroductions: mingleIntroductionCount,
       }) : [],
     };
     // Module→core contribution seam (BV1.R42, ADR 0083). Let each enabled module

package/src/module-api.js

@@ -45,7 +45,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.517'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.518'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/mingle.mjs

@@ -283,6 +283,32 @@ test('a declined pair may be introduced again — a decline is not a permanent s
   assert.equal(mingle.planPairs(eligible, { excludePairs: new Set() }).length, 1);
 });
 
+test('the roster COUNT sees both sides of a pair, and only open ones', async () => {
+  // task 1003178 (C08) added countOpenPairsFor for the needs roster, and the
+  // grader was right that it shipped untested while every other DB function here
+  // is driven against the recording pool. A count is exactly the kind of query
+  // that goes wrong quietly: miss a side of the pair and half the hall never
+  // learns it has an introduction waiting.
+  const pool = {
+    queries: [],
+    async query(sql, params) {
+      this.queries.push({ sql, params });
+      return { rows: [{ n: 3 }] };
+    },
+  };
+  const n = await mingle.countOpenPairsFor(42, { pool });
+  assert.equal(n, 3);
+  const { sql, params } = pool.queries[0];
+  assert.match(sql, /builder_lo = \$1 OR builder_hi = \$1/, 'either side of the pair counts');
+  assert.match(sql, /status = 'proposed'/, 'a settled introduction is not waiting on anyone');
+  assert.deepEqual(params, [42]);
+});
+
+test('the count answers 0 rather than undefined on an empty read', async () => {
+  const pool = { async query() { return { rows: [] }; } };
+  assert.equal(await mingle.countOpenPairsFor(42, { pool }), 0);
+});
+
 test('the exclude set is built from OPEN pairs only, never from declines', async () => {
   const pool = recordingPool({ openPairs: [['1', '2']] });
   await mingle.openPairKeys({ pool });

package/tests/social_mode.mjs

@@ -0,0 +1,181 @@
+// tests/social_mode.mjs — with social on, the HALL changes; it does not gain a
+// tab (task 1003178 / C08, goal 1000075; criterion collab-hall-becomes-a-mode).
+//
+// The criterion is unusual in that it states its own DISQUALIFIER: "a /social
+// route with the same hall around it does NOT satisfy it". So the first block
+// below tests the absence — no route, no nav item, no page file — and the rest
+// tests that existing surfaces read differently instead.
+//
+// The owner's directive, verbatim in the goal: social "is certainly something
+// that should be scoped into the ENTIRE builders hall, not a single social tab".
+import { strict as assert } from 'node:assert';
+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 read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+
+const SHELL = read('modules', 'hall-ui', 'public', 'shell.js');
+const HALL_RENDER = read('modules', 'hall-ui', 'public', 'hall-render.js');
+const COLLAB_JS = read('modules', 'hall-ui', 'public', 'collab.js');
+const COLLAB_HTML = read('modules', 'hall-ui', 'public', 'collab.html');
+const ME = read('src', 'bongos', 'routes', 'me.js');
+const NEEDS = read('modules', 'builder-settings', 'builder-needs.js');
+const needs = require(path.join(ROOT, 'modules', 'builder-settings', 'builder-needs.js'));
+
+// ── 1. THE DISQUALIFIER: social is not a destination ────────────────────────
+
+test('THE DISQUALIFIER: there is no /social page in the hall', () => {
+  const hall = fs.readdirSync(path.join(ROOT, 'modules', 'hall-ui', 'public'));
+  for (const f of hall) {
+    assert.ok(!/^social\.(html|js|css)$/.test(f),
+      `${f} exists — a social PAGE is exactly what this criterion refuses`);
+  }
+});
+
+test('THE DISQUALIFIER: no /social route is served, and no page gate names one', () => {
+  const serve = read('src', 'bongos', 'serve-internal.js');
+  assert.ok(!/\/social\b/.test(serve), 'serve-internal routes nothing at /social');
+  const oracle = read('tests', 'hall_page_gate_map.mjs');
+  assert.ok(!/'\/builders\/social'/.test(oracle), 'the page-gate oracle has no /social row');
+});
+
+test('THE DISQUALIFIER: social adds no nav item', () => {
+  // A nav entry would BE the tab. The whole mechanism is an attribute on the
+  // document, so there is nothing to link to.
+  //
+  // The end marker is NAV_COLLAPSE_KEY, which follows the model. An earlier
+  // draft sliced to `function icon(` — which is DEFINED ABOVE NAV, so the slice
+  // returned an empty string and the assertion passed over nothing. It only
+  // surfaced because adding a real Social tab as a mutation did not red it.
+  const start = SHELL.indexOf('var NAV = [');
+  const end = SHELL.indexOf('var NAV_COLLAPSE_KEY');
+  assert.ok(start > -1 && end > start, 'the NAV model was actually located');
+  const nav = SHELL.slice(start, end);
+  assert.ok(nav.includes("id: 'roster'"), 'and the slice really holds the nav items');
+  assert.ok(!/social/i.test(nav), 'the nav model must not mention social');
+});
+
+// ── 2. SOCIAL IS A MODE, STAMPED ON THE DOCUMENT ────────────────────────────
+
+test('the shell stamps the mode on the document root, beside data-theme', () => {
+  // An attribute on <html> is what lets ANY surface — a stylesheet, a page
+  // script, a widget — read the mode without a route or a second fetch. That is
+  // the structural difference between a mode and a page.
+  assert.match(SHELL, /function applySocial\(social\)/);
+  assert.match(SHELL, /root\.dataset\.social = 'on'/);
+  assert.match(SHELL, /delete root\.dataset\.social/);
+});
+
+test('OFF is the default and the fallback — null is not on', () => {
+  // /me.social is null when lifecycle is disabled or the read failed. A mode
+  // that cannot be read is not on.
+  const fn = SHELL.slice(SHELL.indexOf('function applySocial'));
+  const body = fn.slice(0, fn.indexOf('\n  }'));
+  assert.match(body, /social && social\.enabled === true/,
+    'only an explicit enabled:true turns the mode on');
+});
+
+test('BOTH switches decide it, and the client never re-derives them', () => {
+  // C07 resolved the pair (project enabled AND builder opted in) server-side.
+  // A client that recomputed the mode could disagree with the rest of the hall.
+  assert.ok(!/opted_in|project_enabled/.test(SHELL),
+    'the shell reads `enabled`, never the two switches it came from');
+  assert.match(ME, /socialModeFor/);
+  assert.match(ME, /social: socialMode/);
+});
+
+test('the mode rides /me, which every hall page already fetches', () => {
+  // This is why no new route is needed — and why one would be the wrong shape.
+  assert.match(SHELL, /social: me\.social \|\| null/);
+  assert.match(HALL_RENDER, /social: \(ctx\.lastMeState && ctx\.lastMeState\.social\) \|\| null/);
+});
+
+test('the index passes the mode too — the busiest page is not the one it misses', () => {
+  // renderNav takes (builder, onboarding) and is called from five sites, so the
+  // value must come off the live ctx getter rather than a local `me`.
+  const fn = HALL_RENDER.slice(HALL_RENDER.indexOf('function renderNav('));
+  const body = fn.slice(0, fn.indexOf('\n  }'));
+  assert.ok(!/\bme\?\./.test(body), 'renderNav has no `me` in scope — reading one would throw');
+});
+
+test('a social read can never break a profile', () => {
+  // /me is the session-open hot path. Same fail-open posture as the C01/C03
+  // reads it sits beside.
+  const slot = ME.slice(ME.indexOf('socialModeFor') - 600, ME.indexOf('socialModeFor') + 200);
+  assert.match(slot, /catch \(_\) \{ return null; \}/);
+});
+
+// ── 3. EXISTING SURFACES READ DIFFERENTLY ───────────────────────────────────
+
+test('HOME changes: an introduction becomes a need in the roster', () => {
+  // The needs roster is how a collab feature reaches the whole hall — it is
+  // where C01 and C03 already live, and it renders on Home's Standing card and
+  // in the CLI nudge without either learning about mingle.
+  const roster = needs.computeNeeds({ openMingleIntroductions: 2 }).items;
+  const row = roster.find((n) => n.id === 'mingle_introductions');
+  assert.ok(row, 'the need is produced');
+  assert.equal(row.state, 'action_needed');
+  assert.match(row.action.href, /\/#\/collab/, 'it points at an EXISTING surface, not a new one');
+});
+
+test('no introductions means no row — the roster is not padded', () => {
+  assert.equal(needs.computeNeeds({ openMingleIntroductions: 0 }).items.find((n) => n.id === 'mingle_introductions'), undefined);
+  assert.equal(needs.computeNeeds({}).items.find((n) => n.id === 'mingle_introductions'), undefined);
+});
+
+test('the invitation never pressures — declining is free, so the copy says so', () => {
+  // Mingle is declinable without penalty (C07, ADR 0187 §5). Wording that
+  // pressured the reader would BE the penalty the decision forbids — the same
+  // argument the recommendation need makes, and it matters more for a social
+  // invitation than for a task.
+  const row = needs.computeNeeds({ openMingleIntroductions: 1 }).items;
+  const n = row.find((x) => x.id === 'mingle_introductions');
+  assert.equal(n.severity, 'info', 'info, never a demand');
+  assert.match(n.message, /costs nothing/);
+  assert.match(n.message, /does not change how often you are paired/,
+    'and it names the no-future-weight half, which is the part a reader would doubt');
+});
+
+test('COLLAB changes: the introductions panel is revealed BY THE MODE', () => {
+  // Not by a rank, not by a route, not by a second fetch — by the document
+  // attribute the shell stamped. That is what "the surface reads differently"
+  // means in practice.
+  assert.match(COLLAB_JS, /document\.documentElement\.dataset\.social === 'on'/);
+  assert.match(COLLAB_HTML, /id="cb-mingle-section"[^>]*hidden/);
+});
+
+test('with social OFF the page is exactly what it was, and costs nothing extra', () => {
+  // A page that fetched anyway would make "social is off" cost a request on
+  // every load, and a panel that rendered empty would still be a visible change.
+  const fn = COLLAB_JS.slice(COLLAB_JS.indexOf('async function loadMingle'));
+  const body = fn.slice(0, fn.indexOf('\n  }'));
+  const guard = body.indexOf('if (!socialOn())');
+  assert.ok(guard > -1, 'the mode is checked');
+  assert.ok(guard < body.indexOf("api.request('GET', '/mingle')"),
+    'and it is checked BEFORE anything is fetched');
+});
+
+test('the introductions read is best-effort — it cannot take the page down', () => {
+  // Help requests ARE the Collab page; the social half is additive.
+  assert.match(COLLAB_JS, /try \{ await loadMingle\(\); \} catch \(_\)/);
+});
+
+test('the row is written from the VIEWER\'s side, without a second /me', () => {
+  // A pair carries builder_lo/builder_hi with no marker for "you", so the route
+  // says which side the caller is rather than making the page fetch to find out.
+  const routes = read('modules', 'lifecycle', 'routes', 'mingle.js');
+  assert.match(routes, /you: String\(req\.builder\.id\)/);
+  assert.match(COLLAB_JS, /r\.data\.you/);
+  assert.match(COLLAB_JS, /function otherOf\(pair, meId\)/);
+});
+
+test('answering an introduction reads neutrally either way', () => {
+  // "Declined" must not read as a failure. A disappointed toast would be the
+  // penalty C07 forbids, delivered by the UI instead of the schema.
+  assert.match(COLLAB_JS, /Not now\. Nothing changes for you\./);
+});