@bongos/core 1.19.517 → 1.19.519

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.519'; // 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/agents_validate.mjs

@@ -0,0 +1,354 @@
+// tests/agents_validate.mjs — the pure agent-definition validator (task 1002487,
+// goal 1000038).
+//
+// Gates criterion `agents-malformed-rejected`: a malformed definition (unknown
+// trigger; missing persona; `trigger_spec.event` not in EVENT_CATALOG; scope
+// exceeding an allowed module) is refused with a clear error, and the validator
+// NEVER throws — the loader logs and skips, it does not crash the boot.
+//
+// No database, no fixtures, no fs. Every input is a literal, because the thing
+// under test is a pure decision.
+//
+// Run:  node tests/agents_validate.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const {
+  validateAgentDefinition,
+  EVENT_CATALOG,
+  TRIGGER_TYPES,
+  MODEL_TIERS,
+  RANK_ORDER,
+  SCOPE_RANK_FLOOR,
+} = require('../modules/agents/lib/validate.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+// A definition that passes everything, so each case below can break exactly one
+// thing and attribute the refusal to that one thing.
+const OK_DEF = Object.freeze({
+  name: 'historian',
+  persona: 'Observe the shipped task and report what changed.',
+  trigger_type: 'event',
+  trigger_spec: { event: 'task.shipped' },
+  model_tier: 'default',
+  scope_modules: ['agents'],
+});
+const OPTS = Object.freeze({ authorRank: 'archon', allowedModules: ['agents'] });
+
+const codes = (r) => r.errors.map((e) => e.code);
+const hasCode = (r, code) => codes(r).includes(code);
+
+// --- THE BASELINE -----------------------------------------------------------
+
+await test('the exemplar definition validates, and normalizes into a value', () => {
+  const r = validateAgentDefinition(OK_DEF, OPTS);
+  assert.equal(r.ok, true, `expected ok, got errors: ${JSON.stringify(r.errors)}`);
+  assert.deepEqual(r.errors, []);
+  assert.equal(r.value.name, 'historian');
+  assert.equal(r.value.model_tier, 'default');
+  assert.deepEqual(r.value.scope_modules, ['agents']);
+});
+
+await test('a failed validation returns NO value — nothing downstream can insert it', () => {
+  const r = validateAgentDefinition({ ...OK_DEF, persona: '' }, OPTS);
+  assert.equal(r.ok, false);
+  assert.equal(r.value, null, 'a rejected definition must not hand back a usable row');
+});
+
+// --- THE EVENT CATALOG — the fail-closed rule -------------------------------
+
+await test('EVENT_CATALOG is exactly the v1 wired set, and is frozen', () => {
+  assert.deepEqual(EVENT_CATALOG, ['task.shipped']);
+  assert.equal(Object.isFrozen(EVENT_CATALOG), true, 'a caller must not be able to widen the catalog at runtime');
+});
+
+await test('an UNWIRED event name is REFUSED, never silently accepted', () => {
+  // The whole point of the catalog: an event nothing dispatches would produce an
+  // agent that looks armed and never fires.
+  for (const bad of ['task.completed', 'task.shipped ', 'TASK.SHIPPED', 'claim.created', 'task.*']) {
+    const r = validateAgentDefinition({ ...OK_DEF, trigger_spec: { event: bad } }, OPTS);
+    assert.equal(r.ok, false, `"${bad}" must be refused`);
+    assert.ok(hasCode(r, 'trigger_event_unwired'), `"${bad}" → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('the refusal NAMES the offending event and the catalog', () => {
+  const r = validateAgentDefinition({ ...OK_DEF, trigger_spec: { event: 'task.completed' } }, OPTS);
+  const msg = r.errors.find((e) => e.code === 'trigger_event_unwired').message;
+  assert.ok(msg.includes('task.completed'), `message must name the offender: ${msg}`);
+  assert.ok(msg.includes('task.shipped'), `message must name what IS wired: ${msg}`);
+});
+
+await test('an event trigger with no event name is refused', () => {
+  for (const spec of [{}, { event: '' }, { event: '   ' }, { event: null }, { event: 42 }]) {
+    const r = validateAgentDefinition({ ...OK_DEF, trigger_spec: spec }, OPTS);
+    assert.equal(r.ok, false, `${JSON.stringify(spec)} must be refused`);
+    assert.ok(
+      hasCode(r, 'trigger_event_missing') || hasCode(r, 'trigger_event_unwired'),
+      `${JSON.stringify(spec)} → ${JSON.stringify(codes(r))}`,
+    );
+  }
+});
+
+await test('an on-demand definition needs no event at all', () => {
+  const r = validateAgentDefinition(
+    { ...OK_DEF, trigger_type: 'on-demand', trigger_spec: {} }, OPTS,
+  );
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+});
+
+await test('an on-demand definition carrying an UNWIRED event is still refused', () => {
+  // Fails closed on the event NAME wherever it appears. An inert `event:` key on
+  // an on-demand agent is either a typo'd trigger_type or dead config; both are
+  // bugs the author should be shown rather than have silently accepted.
+  const r = validateAgentDefinition(
+    { ...OK_DEF, trigger_type: 'on-demand', trigger_spec: { event: 'task.completed' } }, OPTS,
+  );
+  assert.equal(r.ok, false);
+  assert.ok(hasCode(r, 'trigger_event_unwired'));
+});
+
+await test('an on-demand definition carrying a WIRED event is accepted', () => {
+  const r = validateAgentDefinition(
+    { ...OK_DEF, trigger_type: 'on-demand', trigger_spec: { event: 'task.shipped' } }, OPTS,
+  );
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+});
+
+// --- THE TRIGGER TYPE -------------------------------------------------------
+
+await test('TRIGGER_TYPES is the v1 pair the DB CHECK also pins', () => {
+  assert.deepEqual(TRIGGER_TYPES, ['event', 'on-demand']);
+});
+
+await test('an unknown trigger type is refused', () => {
+  for (const bad of ['cron', 'webhook', 'Event', 'on demand', '', null, undefined, 7, {}]) {
+    const r = validateAgentDefinition({ ...OK_DEF, trigger_type: bad }, OPTS);
+    assert.equal(r.ok, false, `${JSON.stringify(bad)} must be refused`);
+    assert.ok(hasCode(r, 'trigger_type_unknown'), `${JSON.stringify(bad)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('a non-object trigger_spec is refused rather than coerced', () => {
+  for (const bad of ['task.shipped', 42, [], true]) {
+    const r = validateAgentDefinition({ ...OK_DEF, trigger_spec: bad }, OPTS);
+    assert.equal(r.ok, false, `${JSON.stringify(bad)} must be refused`);
+    assert.ok(hasCode(r, 'trigger_spec_not_object'), `${JSON.stringify(bad)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+// --- THE PERSONA ------------------------------------------------------------
+
+await test('a missing or empty persona is refused', () => {
+  for (const bad of [undefined, null, '', '   ', 42, {}]) {
+    const r = validateAgentDefinition({ ...OK_DEF, persona: bad }, OPTS);
+    assert.equal(r.ok, false, `${JSON.stringify(bad)} must be refused`);
+    assert.ok(hasCode(r, 'persona_missing'), `${JSON.stringify(bad)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('an oversized persona is refused at the same bound the DB CHECK holds', () => {
+  const r = validateAgentDefinition({ ...OK_DEF, persona: 'x'.repeat(32769) }, OPTS);
+  assert.equal(r.ok, false);
+  assert.ok(hasCode(r, 'persona_too_long'));
+  // ...and exactly at the bound it is fine.
+  assert.equal(validateAgentDefinition({ ...OK_DEF, persona: 'x'.repeat(32768) }, OPTS).ok, true);
+});
+
+// --- THE NAME ---------------------------------------------------------------
+
+await test('a name that could not be a filename / URL segment / CLI arg is refused', () => {
+  for (const bad of ['Historian', '1historian', 'the historian', 'his/torian', '-historian', '', 'a'.repeat(65)]) {
+    const r = validateAgentDefinition({ ...OK_DEF, name: bad }, OPTS);
+    assert.equal(r.ok, false, `"${bad}" must be refused`);
+    assert.ok(hasCode(r, 'name_invalid'), `"${bad}" → ${JSON.stringify(codes(r))}`);
+  }
+  assert.equal(validateAgentDefinition({ ...OK_DEF, name: 'a'.repeat(64) }, OPTS).ok, true);
+});
+
+// --- THE MODEL TIER ---------------------------------------------------------
+
+await test('model_tier defaults to `default` when absent, and rejects an unknown tier', () => {
+  assert.deepEqual(MODEL_TIERS, ['default', 'routine']);
+  const { model_tier: _omit, ...noTier } = OK_DEF;
+  const r = validateAgentDefinition(noTier, OPTS);
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+  assert.equal(r.value.model_tier, 'default');
+
+  // spawn.js's resolveModel() deliberately DEGRADES an unknown tier to the default
+  // tier at fire time; that is a runtime safety net, not a licence to author one.
+  const bad = validateAgentDefinition({ ...OK_DEF, model_tier: 'main' }, OPTS);
+  assert.equal(bad.ok, false);
+  assert.ok(hasCode(bad, 'model_tier_unknown'));
+});
+
+await test('there is no `main` tier — an agent is a subagent, never the main session', () => {
+  assert.equal(MODEL_TIERS.includes('main'), false);
+});
+
+// --- THE SCOPE WALL ---------------------------------------------------------
+
+await test('scope exceeding the allowed modules is refused, naming the offenders', () => {
+  const r = validateAgentDefinition(
+    { ...OK_DEF, scope_modules: ['agents', 'government', 'lifecycle'] },
+    { authorRank: 'archon', allowedModules: ['agents'] },
+  );
+  assert.equal(r.ok, false);
+  assert.ok(hasCode(r, 'scope_out_of_bounds'));
+  const msg = r.errors.find((e) => e.code === 'scope_out_of_bounds').message;
+  assert.ok(msg.includes('government') && msg.includes('lifecycle'), `must name the offenders: ${msg}`);
+  assert.ok(!msg.includes("'agents'"), 'must not accuse the module that WAS allowed');
+});
+
+await test('scope FAILS CLOSED when the caller supplies no allowed-module set', () => {
+  // The dangerous default. An empty allowlist must mean "nothing is in scope",
+  // never "everything is" — the same rule goal-scope-check's empty_scope holds.
+  for (const opts of [{ authorRank: 'archon' }, { authorRank: 'archon', allowedModules: [] }, undefined]) {
+    const r = validateAgentDefinition(OK_DEF, opts);
+    assert.equal(r.ok, false, `${JSON.stringify(opts)} must fail closed`);
+    assert.ok(hasCode(r, 'scope_out_of_bounds'), `${JSON.stringify(opts)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('an empty scope_modules is allowed — it grants nothing', () => {
+  const r = validateAgentDefinition({ ...OK_DEF, scope_modules: [] }, { authorRank: 'archon', allowedModules: [] });
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+  assert.deepEqual(r.value.scope_modules, []);
+});
+
+await test('a non-array / non-string scope is refused rather than coerced', () => {
+  for (const bad of ['agents', 42, {}, ['agents', 7], ['agents', '']]) {
+    const r = validateAgentDefinition({ ...OK_DEF, scope_modules: bad }, OPTS);
+    assert.equal(r.ok, false, `${JSON.stringify(bad)} must be refused`);
+    assert.ok(hasCode(r, 'scope_modules_invalid'), `${JSON.stringify(bad)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('a scope_path that escapes the tree is refused', () => {
+  for (const bad of ['../../etc/passwd', '/etc/passwd', 'modules/../../..', 'C:\\Windows']) {
+    const r = validateAgentDefinition({ ...OK_DEF, scope_paths: [bad] }, OPTS);
+    assert.equal(r.ok, false, `"${bad}" must be refused`);
+    assert.ok(hasCode(r, 'scope_paths_invalid'), `"${bad}" → ${JSON.stringify(codes(r))}`);
+  }
+  assert.equal(validateAgentDefinition({ ...OK_DEF, scope_paths: ['modules/agents/'] }, OPTS).ok, true);
+});
+
+// --- THE RANK WALL (ADR 0016 — authority is the author's LIVE rank) ---------
+
+await test('RANK_ORDER is the ladder low→high, and the scope floor is Metic', () => {
+  assert.deepEqual(RANK_ORDER, ['xenos', 'thetes', 'metic', 'archon']);
+  assert.equal(SCOPE_RANK_FLOOR, 'metic');
+});
+
+await test('a sub-Metic author may not scope an agent onto a PROTECTED module', () => {
+  const opts = { allowedModules: ['agents', 'government'], protectedModules: ['government'] };
+  for (const rank of ['xenos', 'thetes']) {
+    const r = validateAgentDefinition({ ...OK_DEF, scope_modules: ['government'] }, { ...opts, authorRank: rank });
+    assert.equal(r.ok, false, `${rank} must not reach a protected module`);
+    assert.ok(hasCode(r, 'scope_protected_rank'), `${rank} → ${JSON.stringify(codes(r))}`);
+  }
+  // Metic+ clear the floor.
+  for (const rank of ['metic', 'archon']) {
+    const r = validateAgentDefinition({ ...OK_DEF, scope_modules: ['government'] }, { ...opts, authorRank: rank });
+    assert.equal(r.ok, true, `${rank} should clear the floor: ${JSON.stringify(r.errors)}`);
+  }
+});
+
+await test('an UNKNOWN author rank fails CLOSED against a protected module', () => {
+  // A file cannot grant authority (ADR 0016). If the caller could not name a live
+  // rank, the definition has no authority to reach a protected module.
+  const opts = { allowedModules: ['government'], protectedModules: ['government'] };
+  for (const rank of [undefined, null, '', 'admin', 'ARCHON']) {
+    const r = validateAgentDefinition({ ...OK_DEF, scope_modules: ['government'] }, { ...opts, authorRank: rank });
+    assert.equal(r.ok, false, `${JSON.stringify(rank)} must fail closed`);
+    assert.ok(hasCode(r, 'scope_protected_rank'), `${JSON.stringify(rank)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('an unknown rank is NOT fatal when no protected module is in scope', () => {
+  // The rank wall guards protected scope only; an ordinary agent does not need a
+  // resolved rank to be structurally valid.
+  const r = validateAgentDefinition(OK_DEF, { authorRank: 'nonsense', allowedModules: ['agents'] });
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+});
+
+// --- NEVER CRASH THE BOOT ---------------------------------------------------
+
+await test('a non-object definition is refused, not thrown on', () => {
+  for (const bad of [null, undefined, 'historian', 42, [], true]) {
+    let r;
+    assert.doesNotThrow(() => { r = validateAgentDefinition(bad, OPTS); }, `${JSON.stringify(bad)} threw`);
+    assert.equal(r.ok, false);
+    assert.ok(hasCode(r, 'not_an_object'), `${JSON.stringify(bad)} → ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('a CIRCULAR trigger_spec is refused, not thrown on', () => {
+  // The size check is over the serialized spec, and JSON.stringify THROWS on a
+  // cycle. A definition file cannot express one, but a db-sourced object can —
+  // and this validator is the thing standing between that and the boot.
+  const spec = { event: 'task.shipped' };
+  spec.self = spec;
+  let r;
+  assert.doesNotThrow(() => { r = validateAgentDefinition({ ...OK_DEF, trigger_spec: spec }, OPTS); });
+  assert.equal(r.ok, false);
+  assert.ok(hasCode(r, 'trigger_spec_unserializable'), JSON.stringify(codes(r)));
+});
+
+await test('an oversized trigger_spec is refused at the DB CHECK bound', () => {
+  const r = validateAgentDefinition(
+    { ...OK_DEF, trigger_spec: { event: 'task.shipped', pad: 'x'.repeat(9000) } }, OPTS,
+  );
+  assert.equal(r.ok, false);
+  assert.ok(hasCode(r, 'trigger_spec_too_long'));
+});
+
+await test('a hostile getter cannot escape the validator', () => {
+  // trigger_spec is PARAMETERS, never payload — and a throwing accessor must
+  // become a refusal, not an exception into the loader.
+  const hostile = { name: 'historian', persona: 'x', trigger_type: 'event' };
+  Object.defineProperty(hostile, 'trigger_spec', { get() { throw new Error('boom'); }, enumerable: true });
+  let r;
+  assert.doesNotThrow(() => { r = validateAgentDefinition(hostile, OPTS); });
+  assert.equal(r.ok, false);
+});
+
+await test('EVERY error carries a code, a field and a human message', () => {
+  const r = validateAgentDefinition(
+    { name: 'BAD NAME', trigger_type: 'cron', trigger_spec: 'nope', scope_modules: ['government'] },
+    { authorRank: 'xenos', allowedModules: ['agents'] },
+  );
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.length >= 4, `expected the whole list, got ${JSON.stringify(codes(r))}`);
+  for (const e of r.errors) {
+    assert.equal(typeof e.code, 'string', JSON.stringify(e));
+    assert.equal(typeof e.field, 'string', JSON.stringify(e));
+    assert.ok(e.message && e.message.length > 10, `message too thin: ${JSON.stringify(e)}`);
+  }
+});
+
+await test('validation reports ALL faults at once, not just the first', () => {
+  // An author fixing a definition file should not have to re-run four times.
+  const r = validateAgentDefinition({ name: 'X', persona: '', trigger_type: 'cron' }, OPTS);
+  for (const code of ['name_invalid', 'persona_missing', 'trigger_type_unknown']) {
+    assert.ok(hasCode(r, code), `${code} missing from ${JSON.stringify(codes(r))}`);
+  }
+});
+
+await test('the validator never MUTATES the definition it was handed', () => {
+  const def = { ...OK_DEF, trigger_spec: { event: 'task.shipped' } };
+  const before = JSON.stringify(def);
+  validateAgentDefinition(def, OPTS);
+  assert.equal(JSON.stringify(def), before);
+});
+
+console.log(`\nagents_validate: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

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/rank_tier_single_source.mjs

@@ -116,6 +116,17 @@ const STATIC_LADDER_FILES = [
   // which holds it against catalog.RANK_ORDER and holds the whole browser parser
   // equal to the server one.
   'modules/hall-ui/public/government.js',
+  // task 1002487: the pure agent-definition validator applies the ADR 0043
+  // sub-Metic floor to an agent's declared scope, so it needs the ladder to
+  // compare against. It is one of the "dependency-free" cases this array exists
+  // for, and for a sharper reason than the browser statics above: its whole
+  // contract is to be checkable with NO database, and the doorway it would
+  // otherwise import (src/module-api.js) eagerly requires ./bongos/pool at load.
+  // Deriving the ladder from api.LIVE_RANK_LADDER would therefore drag a
+  // Postgres pool into a validator that must run in a bare unit test — so the
+  // copy is pinned here instead, which is what makes it provable rather than
+  // merely allowed.
+  'modules/agents/lib/validate.js',
 ];
 test('static ladder copies carry the exact canonical ladder', () => {
   for (const rel of STATIC_LADDER_FILES) {

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\./);
+});