@bongos/core 1.19.425 → 1.19.427

package/modules/platform-identity/routes/scouting.js

@@ -1,10 +1,20 @@
-// modules/platform-identity/routes/scouting.js — the INTERNAL cross-project
-// scouting view (ADR 0141 §4, task #1002114; Metic floor per ADR 0157). Ranks
-// builders across ALL hosted projects from platform_identity_builder_project_activity.
-// A talent tool for the platform operator — NOT authority (the rollup is
-// descriptive; authority stays local, ADR 0141 / ADR 0016). Consent is enforced
-// IN listScoutingRollup itself (ADR 0171 D2/D3): only profile_state='active',
-// non-hidden builders appear, so this surface honors hide by construction.
+// modules/platform-identity/routes/scouting.js — the cross-project RECRUITING
+// DIRECTORY (ADR 0141 §4, task 1002114; graduated to project owners by ADR 0210,
+// task 1002290). Ranks builders across ALL hosted projects from
+// platform_identity_builder_project_activity. A talent tool — NOT authority (the
+// rollup is descriptive; authority stays local, ADR 0141 / ADR 0016).
+//
+// WHO READS IT: a hub operator holding `project.curate` (floor metic since ADR
+// 0157) OR a project owner — someone whose own project reported them as its
+// owner at check-in and whose sign-in the hub itself witnessed. That OR lives in
+// ../scouting-authz.js, which carries the full argument for why reading an
+// instance-asserted ownership claim is not the ADR 0201 D3 inversion.
+//
+// WHO APPEARS IN IT: consent is enforced IN listScoutingRollup itself, by the
+// shared scoutingListableSql predicate — active, publicly visible, not hidden,
+// and not opted out of recruiting (ADR 0171 D2/D3 + privacy spec D1). So this
+// surface honors both the hide flag and the recruiting opt-out by construction,
+// and widening WHO may read it could not widen WHAT is shown.
 //
 // Reaches core only through the doorway (ADR 0083).
 'use strict';
@@ -12,25 +22,55 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
+const scoutingAuthz = require('../scouting-authz');
 
-const { pool, requireBuilder, requirePermission, parsePagination } = api;
+const { pool, requireBuilder, parsePagination } = api;
+
+// Resolved at CALL time, never at load. Proofs that exercise this route pin a
+// PARTIAL doorway (tests/profile_route.mjs stubs pool + the two gates and
+// nothing else), and a module-scope api.logger() would make this file
+// unrequireable there — a logging line is not worth breaking a privacy proof
+// over. my-projects.js reaches the doorway logger the same lazy way.
+let resolvedLog = null;
+const log = {
+  error: (msg) => {
+    if (!resolvedLog) resolvedLog = typeof api.logger === 'function' ? api.logger('platform-identity') : { error: () => {} };
+    resolvedLog.error(msg);
+  },
+};
 
 module.exports = function scoutingRoutes() {
   const router = express.Router();
 
-  // rank: archon — the internal talent directory across every project. The Archon
-  // gate here is the load-bearing protection ("NOT shown to builders"): a non-Archon
-  // is 403'd before any cross-builder data is read.
-  router.get('/scouting', requireBuilder, requirePermission('project.curate'), async (req, res) => {
-    const { limit } = parsePagination(req, { defaultLimit: 100, maxLimit: 500 });
-    try {
-      const builders = await pi.listScoutingRollup({ limit, pool });
-      res.json({ builders });
-    } catch (err) {
-      console.error('[platform-identity] GET /scouting', err);
-      res.fail('scouting_failed', { status: 500, message: 'internal error' });
-    }
-  });
+  // The atom is spelled in the middleware list below, not hidden inside
+  // requireScoutingReader, so route-rank-check.js and gen-api-docs.js classify
+  // this route from its real gate. A helper-hidden gate would record a
+  // privileged route as any-builder — wrong in the dangerous direction.
+
+  // rank: metic+archon — the internal talent directory across every project.
+  // Read by a `project.curate` holder OR a project owner (ADR 0210, task 1002290);
+  // a caller who is neither gets the unchanged permission refusal before any
+  // cross-builder data is read.
+  router.get(
+    '/scouting',
+    requireBuilder,
+    // Ownership is asked FIRST — one indexed LIMIT-1 lookup, paid by the operator
+    // path too. The alternative is asking the permission gate first, and it is not
+    // available: a middleware that has denied has already SENT its response, so
+    // there is nothing to fall through from. Paying a round-trip is what keeps the
+    // 403 byte-identical to the one this route always produced (ADR 0210 D2).
+    scoutingAuthz.requireScoutingReader({ curateGate: api.requirePermission('project.curate'), pool, log }),
+    async (req, res) => {
+      const { limit } = parsePagination(req, { defaultLimit: 100, maxLimit: 500 });
+      try {
+        const builders = await pi.listScoutingRollup({ limit, pool });
+        res.json({ builders });
+      } catch (err) {
+        log.error(`GET /scouting failed: ${err && err.message}`);
+        res.fail('scouting_failed', { status: 500, message: 'internal error' });
+      }
+    },
+  );
 
   return router;
 };

package/modules/platform-identity/routes/sso.js

@@ -17,6 +17,7 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
+const scoutingAuthz = require('../scouting-authz');
 const hubKeys = require('../hub-keys');
 const hubDevice = require('../hub-device');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
@@ -114,6 +115,11 @@ function registerSeams() {
       // THROWS on a bad read by design — an empty set means "nobody is hidden",
       // which a database error must never be allowed to say.
       hiddenGithubIds: (githubIds) => pi.hiddenGithubIds(githubIds, { pool }),
+      // task 1002290 (ADR 0210): "does this hub account own a project?", the
+      // second audience the /people page gate admits beside `project.curate`.
+      // The ownership fact lives in this module, so the answer does too; core
+      // asks through the port and treats an absent one as a denial.
+      isProjectOwner: (githubId) => scoutingAuthz.hasOwnerMembership(githubId, { pool }),
     });
   }
 }

package/modules/platform-identity/scouting-authz.js

@@ -0,0 +1,139 @@
+// modules/platform-identity/scouting-authz.js — WHO may read the cross-project
+// recruiting directory (GET /scouting; the hall's /people page renders the same
+// data). ADR 0210, task 1002290 — goal 1000045 C5: "project owners (not only
+// Archons) browse builder profiles to recruit".
+//
+// TWO DOORS, DELIBERATELY DIFFERENT KINDS — the modules/lifecycle/goal-authz.js
+// shape (owner OR rank), which the project-admin-console spec names as the
+// design of record:
+//
+//   RANK      — `project.curate`, floor metic (ADR 0157 lowered it from archon).
+//               The hub OPERATOR's door, unchanged: the atom, the 403 body, the
+//               floors map. Nothing about it moves here.
+//   OWNERSHIP — an instance-asserted, hub-witnessed `membership_kind = 'owner'`
+//               project membership. The PROJECT OWNER's door, and the whole of
+//               what this file adds.
+//
+// WHY OWNERSHIP IS SAFE TO READ HERE, WHEN ADR 0201 D3 SAYS A HUB-HELD OWNER
+// LIST IS NEVER A GATE. The thing that ADR rejects is `platform_identity_-
+// projects.owner_github_id`: a hub CATALOG column, written by hub curation, with
+// no instance behind it — consulting it before an ADMISSION would be the hub
+// deciding who may admit on someone else's box, the ADR 0141 inversion.
+// `platform_identity_project_memberships.membership_kind` is a different record
+// with a different provenance: the PROJECT ITSELF reports it over the
+// client_id + client_secret channel at `POST /sso/membership/check-in`
+// (src/bongos/auth-admission.js decides the value from its OWN first-admin
+// config), and `touchMembership` refuses to write it unless the hub has already
+// witnessed that person sign in (`signin_verified_at`, ADR 0205 D1/D2). So this
+// gate reads the instance's own claim about its own archon, mirrored — authority
+// stays local, exactly as ADR 0141 requires. And the act being gated is a HUB
+// READ of the hub's own directory, not an admission on anyone else's box.
+//
+// NOT AUTHORITY, IN EITHER DIRECTION (ADR 0016). Owning a project buys exactly
+// one thing: reading a descriptive, consent-filtered list. It confers no rank, no
+// claim right, no admission power, and it is never consulted by anything else.
+// The reverse also holds and is load-bearing for task 1002290's other half: a
+// builder's recruiting opt-out changes who can SEE them and grants or denies
+// them nothing — the two axes never touch.
+//
+// LIVE GAP, NAMED ON PURPOSE (ADR 0210 §Consequences; blocker filed). "Project
+// owner" per the goal spec is "the registrant plus delegates they grant". Today
+// an instance reports `owner` for its FIRST ADMIN only, so the REGISTRANT half
+// works and DELEGATES do not: a second archon on a project holds `member` on the
+// hub and reaches /scouting only via `project.curate`. Nothing here needs to
+// change when that is fixed — this gate reads whatever the instance reports.
+'use strict';
+
+const pi = require('./platform-identity');
+
+// The coarse membership value that means "this person is an owner of this
+// project", in the CURRENT vocabulary (ADR 0177 — `role`/'builder' is the legacy
+// spelling platform_identity_010's trigger keeps in lockstep; 'owner' is
+// unchanged across the rename, so there is no legacy value to also accept).
+const OWNER_MEMBERSHIP_KIND = 'owner';
+
+// The one `platform_identity_sso_clients.status` value that means the project is
+// still live on the platform (the other is 'suspended' — migration
+// platform_identity_001_tables.sql). Suspending a client is the operator's
+// revocation lever; see hasOwnerMembership for why this gate answers to it.
+const ACTIVE_CLIENT_STATUS = 'active';
+
+// isProjectOwnerMembership(row) — the PURE predicate: is this one membership row
+// an owner membership the hub itself witnessed a sign-in for? Fail-closed on an
+// absent row, and on a row the hub never witnessed — an un-witnessed row is a
+// client's own unproven claim (ADR 0205 D4, the `membershipBacksRollup` rule).
+function isProjectOwnerMembership(membership) {
+  return !!membership
+    && membership.membership_kind === OWNER_MEMBERSHIP_KIND
+    && !!membership.signin_verified_at;
+}
+
+// hasOwnerMembership(githubId) — does this hub account own at least one project
+// that is still ACTIVE on the platform? EXISTENCE only: which project, and how
+// many, is not this gate's question, so the query stops at the first row. A
+// non-numeric principal (core's 'system:bfg' shape) answers false rather than
+// throwing a bigint cast mid-request — the isNumericGithubId guard every read in
+// this module carries.
+//
+// THE CLIENT JOIN IS THE REVOCATION DIMENSION, and without it this door could
+// never be shut. A membership row is written once and never expires: nothing
+// ages it out, and the only ways it stops saying `owner` are the instance
+// reporting a lower kind at a later check-in, or the builder leaving of their
+// own accord. Neither is available to the platform operator dealing with a rogue
+// or compromised project. Suspending its client (`setClientStatus`) IS that
+// lever — it is what already stops the project signing anyone in — so the read
+// it derives must answer to it too. Otherwise suspending a project would leave
+// its owner reading every builder on the platform, indefinitely.
+async function hasOwnerMembership(githubId, { pool }) {
+  if (!pi.isNumericGithubId(githubId)) return false;
+  const { rows } = await pool.query(
+    `SELECT m.membership_kind, m.signin_verified_at
+       FROM platform_identity_project_memberships m
+       JOIN platform_identity_sso_clients c ON c.client_id = m.client_id
+      WHERE m.github_id = $1 AND m.membership_kind = $2
+        AND m.signin_verified_at IS NOT NULL
+        AND c.status = $3
+      LIMIT 1`,
+    [githubId, OWNER_MEMBERSHIP_KIND, ACTIVE_CLIENT_STATUS],
+  );
+  return isProjectOwnerMembership(rows[0]);
+}
+
+// requireScoutingReader({ curateGate, pool, log }) — the OR gate as one
+// middleware, mounted after requireBuilder. `curateGate` is the ALREADY-BUILT
+// `requirePermission('project.curate')` middleware: the atom is spelled in the
+// route's own middleware list, where route-rank-check.js and gen-api-docs.js can
+// see it, so widening the door cannot make the route's recorded rank read looser
+// than it is.
+//
+// ORDER IS THE DESIGN. The ownership question is asked FIRST and, when it
+// answers yes, the request proceeds without the permission gate ever running.
+// When it answers no — or throws — the request falls through to the UNMODIFIED
+// permission gate, so a caller who is neither owner nor operator gets exactly the
+// 403 this route has always produced: the same code, the same `required`/`held`,
+// the same floors map naming the metic floor. The widening can therefore only
+// ever ADMIT; it cannot change, soften, or swallow a refusal.
+//
+// FAIL-CLOSED ON THE OWNERSHIP QUESTION ITSELF. A database blip while asking
+// "does this person own a project" must not admit, and must not 500 either: it
+// falls to the permission gate, which denies unless the caller holds the atom.
+// The failure mode of the new door is "the old door, unchanged".
+function requireScoutingReader({ curateGate, pool, log }) {
+  return async function scoutingReaderGate(req, res, next) {
+    try {
+      if (await hasOwnerMembership(req.builder && req.builder.github_id, { pool })) return next();
+    } catch (err) {
+      // Message only — a query error can carry row data (the requirePermission
+      // precedent). The request continues to the rank door, which denies.
+      log.error(`scouting owner check failed, falling back to the permission gate: ${err && err.message}`);
+    }
+    return curateGate(req, res, next);
+  };
+}
+
+module.exports = {
+  OWNER_MEMBERSHIP_KIND,
+  isProjectOwnerMembership,
+  hasOwnerMembership,
+  requireScoutingReader,
+};

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.425",
+  "version": "1.19.427",
   "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/scripts/hall-preview/server.js

@@ -116,6 +116,9 @@ const FIXTURE_FALLBACKS = [
   // craft and the page window are query string, which fixture matching ignores.
   [/^builders\/\d+\/activity$/, (q) => (q.section === 'goals' ? 'builders__activity-goals' : 'builders__activity-tasks')],
   [/^inbox\/by-builder\/\d+$/, 'inbox__by-builder'],
+  // the profile's connections section (task 1002296) — one degree fixture serves
+  // any handle, since the handle is the address and the label is the payload.
+  [/^connections\/degree\/[^/]+$/, 'connections__degree'],
 ];
 
 function loadFixture(name) {

package/src/bongos/auth.js

@@ -390,9 +390,54 @@ const PAGE_GATES = Object.freeze({
   requireNonXenosPage: Object.freeze({ permission: 'page.view.builder', deniedTo: '/builders/not-ready' }),
   requireGovernmentPage: Object.freeze({ permission: 'page.view.government', deniedTo: '/builders' }),
   requireGovernmentManagePage: Object.freeze({ permission: 'government.manage', deniedTo: '/builders' }),
-  requireProjectCuratePage: Object.freeze({ permission: 'project.curate', deniedTo: '/builders' }),
+  // `alsoAdmits` — a SECOND, non-rank audience this page's DATA ROUTE admits, so
+  // the page can follow it (ADR 0210, task 1002290). /people fronts GET /scouting,
+  // which since R14 admits a `project.curate` holder OR a PROJECT OWNER; a page
+  // gate that could only ever ask about a permission would leave the widened
+  // audience staring at a redirect. The value names a function on the
+  // `platform-identity.hub` port — the module that owns the ownership fact — and
+  // is consulted ONLY after the permission check has already refused, so it can
+  // widen and never narrow. Absent port, absent function, or a throw: no admit.
+  requireProjectCuratePage: Object.freeze({
+    permission: 'project.curate', deniedTo: '/builders', alsoAdmits: 'isProjectOwner',
+  }),
 });
 
+// The `alsoAdmits` door — "is this visitor the page's OTHER audience?", asked of
+// the module that owns the answer, only for the one gate that declares one.
+//
+// FAIL-CLOSED, EVERY WAY IT CAN FAIL: a gate with no `alsoAdmits`, a hub module
+// that is off (every non-hub instance), a port that never grew the function, or a
+// resolver that throws all answer FALSE — the visitor is redirected exactly as
+// before. The only outcome that admits is an explicit truthy answer.
+//
+// Not authority (ADR 0016): the answer gates a PAGE SHELL and nothing else, and
+// every data endpoint behind that shell still carries its own server-side gate.
+async function pageGateAlsoAdmits(name, session) {
+  const { alsoAdmits } = PAGE_GATES[name];
+  if (!alsoAdmits) return false;
+  // The WHOLE lookup is inside the try, not just the call: resolving a seam can
+  // throw too, and a throw there would 500 the page instead of taking the clean
+  // deny-redirect every other failure here takes. One catch, one outcome.
+  try {
+    const hub = seams.resolveOptional('platform-identity.hub');
+    // OWN property only. Every object inherits `constructor`, `valueOf` and
+    // `toString`, each of which is a function whose result is truthy — so a plain
+    // `hub[name]` lookup would let a mis-typed or mis-declared `alsoAdmits` admit
+    // EVERYONE. Unreachable today (the only value is a frozen literal), but a
+    // fail-OPEN default has no business sitting in an authorization path.
+    if (!hub || !Object.prototype.hasOwnProperty.call(hub, alsoAdmits)) return false;
+    const ask = hub[alsoAdmits];
+    if (typeof ask !== 'function') return false;
+    return !!(await ask(session.github_id));
+  } catch (err) {
+    // Message only — the answer came from a query that can carry row data.
+    require('./logger').logger.child({ src: 'auth' })
+      .error({ err: err && err.message }, `${name} ${alsoAdmits} check failed`);
+    return false;
+  }
+}
+
 // A builder's effective permission set, or NULL when authority cannot be
 // ESTABLISHED (the `governance` port is absent or malformed, or the resolver
 // threw). Every caller must read null as a DENIAL: admitting when the authority
@@ -446,6 +491,15 @@ async function runPageGate(name, req, res, next) {
   }
   const held = await resolveHeldPermissions(session.builder_id, session.raw_permission_keys);
   if (held === null || !held.has(permission)) {
+    // The rank door said no. A page whose data route admits a SECOND audience
+    // asks that door before redirecting (ADR 0210) — consulted here and nowhere
+    // else, so it can only widen. Asked on the authority-outage branch too,
+    // because the ownership fact does not come from the authority system: not
+    // asking would make the page narrower than the route it fronts.
+    if (await pageGateAlsoAdmits(name, session)) {
+      next();
+      return;
+    }
     // N-1 (task 1002613): a bare deniedTo rendered nothing — every denial read as
     // "I signed in and got dumped at the home page". Name the permission (and an
     // authority outage, distinctly) in the query so the hall shell can say why.
@@ -488,8 +542,10 @@ async function requireGovernmentManagePage(req, res, next) {
 // The /people builder-directory page (task 1002577) — gated on the
 // `project.curate` ATOM, the same key its one data route (GET /scouting,
 // modules/platform-identity) checks, so the page layer can never drift wider
-// than the API it fronts. Spec R14 (goal 1000045) widens the atom's audience
-// later; this gate follows it automatically.
+// than the API it fronts. R14 (goal 1000045, ADR 0210) widened that route to a
+// SECOND audience that is not a rank at all — a project owner — so this gate
+// carries the same OR through `alsoAdmits` above: the two doors of the page are
+// exactly the two doors of the route, and neither layer can drift from it.
 async function requireProjectCuratePage(req, res, next) {
   return runPageGate('requireProjectCuratePage', req, res, next);
 }

package/src/module-api.js

@@ -33,7 +33,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.425'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.427'; // 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/account_privacy_flags.mjs

@@ -284,23 +284,33 @@ test('the discoverable toggle names EXACTLY what it grants — the D3 sliver, na
     'the section ships hidden — it reveals only where the hub module answers');
 });
 
-test('each toggle claims exactly what is enforced — visibility in force, recruiting not yet', () => {
+test('each toggle claims exactly what is enforced — and BOTH are now in force', () => {
   const js = readFileSync(join(ROOT, 'modules/hall-ui/public/settings.js'), 'utf8');
   const html = readFileSync(join(ROOT, 'modules/hall-ui/public/settings.html'), 'utf8');
-  // A toggle may promise only what a read path actually enforces, and the two
-  // rows are at different stages. Task 1002967 wired VISIBILITY into every
-  // public read, so its row moved to the present tense here — and it must also
-  // say the page 404s to the OWNER, because that is the surprising half of D2
-  // (the owner reads their record through the own-scope side door instead).
-  // DISCOVERABILITY is still stored-only: no recruiting surface reads it, so a
-  // present-tense promise there would be the "protection you do not have" this
-  // assertion pair exists to prevent.
+  // A toggle may promise only what a read path actually enforces. The two rows
+  // reached that point one task apart. Task 1002967 wired VISIBILITY into every
+  // public read, so its row moved to the present tense — and it must also say
+  // the page 404s to the OWNER, because that is the surprising half of D2 (the
+  // owner reads their record through the own-scope side door instead). Task
+  // 1002290 then wired RECRUITING REACH into listScoutingRollup, the one reader
+  // behind /scouting and the hall's People directory, so its row followed on the
+  // same terms. The assertions are unchanged in KIND — copy must track
+  // enforcement — only in which tense each row is now required to be in.
   assert.match(js, /Private hides the page from everyone — including you/,
     'visibility is enforced now, so the row says so — and names the 404-to-self');
   assert.doesNotMatch(js, /Private will hide the page/,
     'the future tense outlived its truth the moment resolveHandle joined the predicate');
-  assert.match(html, /profile page setting applies now[\s\S]*Recruiter discoverability is saved to your[\s\S]*starts applying as the recruiting surfaces land/,
-    'the section note splits the two: one in force, one recorded and waiting');
-  assert.doesNotMatch(js, /Recruiters looking for builders (?:can|are able to) find you\b/,
-    'no present-tense promise about recruiting reach — nothing reads that flag yet');
+  assert.match(js, /Recruiters looking for builders can find you\b/,
+    'recruiting reach is enforced now (task 1002290), so the row promises it in the present tense');
+  assert.doesNotMatch(js, /will be able to find you/,
+    'the future tense outlived its truth the moment listScoutingRollup joined the reach predicate');
+  assert.match(js, /takes you out of the People directory straight away/,
+    'and the row names the ONE surface that reads the flag today — a promise you can go and check');
+  assert.doesNotMatch(js, /every recruiting view/,
+    'never a promise over surfaces that do not exist yet: the D3 recruiter sliver is unbuilt, so no '
+    + 'guard here could hold that claim, and the copy rule is that a toggle promises exactly what is enforced');
+  assert.match(html, /profile page setting applies now[\s\S]*Recruiter discoverability applies now too/,
+    'the section note now says both are live, rather than splitting them');
+  assert.doesNotMatch(html, /starts applying as the recruiting surfaces land/,
+    'the "recorded and waiting" note must not outlive the surface that started reading it');
 });

package/tests/effective_visibility_predicate.mjs

@@ -77,6 +77,8 @@ import {
   rollupVisibleSql,
   isRollupVisible,
   isRecruiterDiscoverable,
+  recruiterReachSql,
+  scoutingListableSql,
 } from '../modules/platform-identity/account-visibility.js';
 
 const require = createRequire(import.meta.url);
@@ -244,7 +246,14 @@ function blankComments(src) {
 const SPELLINGS = [
   [/\bprofile_state\s*(?:=|==|===|!=|!==|<>)\s*['"]/g, "profile_state compared to a literal"],
   [/\baccount_visibility\s*(?:=|==|===|!=|!==|<>)\s*['"]/g, 'account_visibility compared to a literal'],
-  [/\bCOALESCE\s*\(\s*recruiter_discoverable/gi, 'the recruiter-reach COALESCE'],
+  // The reach COALESCE, in every form a real query writes it. The unqualified
+  // spelling alone was a hole: the ONE production copy of this predicate is
+  // written `COALESCE(${q}recruiter_discoverable, …)` and emits
+  // `COALESCE(pa.recruiter_discoverable, …)`, and NEITHER matched — so the rule
+  // that is supposed to make this file the only home for the reach answer was
+  // catching only the spelling nobody uses. A drift copy would most likely be
+  // aliased too (task 1002290, found in this task's adversarial review).
+  [/\bCOALESCE\s*\(\s*(?:[A-Za-z_$][\w$]*|\$\{[^}]*\})?\s*\.?\s*recruiter_discoverable/gi, 'the recruiter-reach COALESCE'],
   [/\bNOT\s+(?:[A-Za-z_][\w]*\.)?hide_stats\b/g, 'a SQL NOT hide_stats'],
   [/\bhide_stats\s*(?:=|==|===)\s*(?:true|false)\b/g, 'hide_stats compared to a boolean'],
 ];
@@ -318,8 +327,14 @@ function accountStatements(code) {
   return out;
 }
 
-/** Does this function body route through one of the shared predicates? */
-const ADOPTS = /\b(?:accountVisibleSql|accountActiveSql|rollupVisibleSql|isAccountVisible|isAccountActive|isRollupVisible)\s*\(/;
+/**
+ * Does this function body route through one of the shared predicates?
+ * scoutingListableSql (task 1002290) is COMPOSED from rollupVisibleSql and
+ * recruiterReachSql inside the owner file, so a reader that joins it has adopted
+ * the shared rule — but it must be named here, or wiring the recruiting reach in
+ * would read as a reader that stopped adopting anything.
+ */
+const ADOPTS = /\b(?:accountVisibleSql|accountActiveSql|rollupVisibleSql|scoutingListableSql|isAccountVisible|isAccountActive|isRollupVisible)\s*\(/;
 
 // ===========================================================================
 // Self-tests — the machinery is the guard, so it gets proved too.
@@ -342,6 +357,17 @@ t('SPELLINGS catch a hand-written variant in either language, and leave writes a
   assert.ok(caught("AND account_visibility = 'public'"), 'the existence axis in SQL');
   assert.ok(caught("acct.account_visibility === 'private'"), 'the existence axis in JS');
   assert.ok(caught('COALESCE(recruiter_discoverable, account_visibility)'), 'the recruiter COALESCE');
+  // The forms a REAL query carries — an alias, a template variable, and the two
+  // together. Testing only the bare spelling is how this rule came to match
+  // nothing that ships: the ONE production copy emits `COALESCE(pa.recruiter_-
+  // discoverable, …)` from source that reads `COALESCE(${q}recruiter_-
+  // discoverable, …)`, and the rule matched NEITHER (task 1002290, found in this
+  // task's adversarial review — and then again one form later, which is why all
+  // four are pinned rather than the one that failed first).
+  assert.ok(caught('COALESCE(pa.recruiter_discoverable, TRUE)'), 'the reach COALESCE, aliased');
+  assert.ok(caught('COALESCE(${q}recruiter_discoverable, x)'), 'the reach COALESCE, as the builder writes it');
+  assert.ok(caught('COALESCE(${alias}.recruiter_discoverable, TRUE)'), 'a template alias AND a dot — the drift copy most likely to be written');
+  assert.ok(!caught('COALESCE(hide_stats, false)'), 'and it is the REACH column it watches, not any COALESCE');
   assert.ok(caught('AND NOT pa.hide_stats'), 'the hide half of a rollup predicate');
   // A WRITE names the column but compares it to nothing — it decides no visibility.
   assert.ok(!caught("profile_state = CASE WHEN $5::boolean THEN 'active' ELSE x END"), 'an upsert is not a predicate');
@@ -390,10 +416,24 @@ t('rollupVisibleSql is COMPOSED from accountVisibleSql, never restated', () => {
   assert.match(rollupVisibleSql('pa'), /AND NOT pa\.hide_stats/, 'and add exactly the hide term');
 });
 
-t('the alias is the one interpolated thing, and both builders refuse a non-identifier', () => {
+t('scoutingListableSql is COMPOSED from the rollup AND the reach halves (task 1002290)', () => {
+  // The recruiting directory asks BOTH questions; a leaderboard asks only the
+  // first. Composition is what keeps that distinction from becoming two rules.
+  assert.ok(scoutingListableSql('pa').includes(rollupVisibleSql('pa')),
+    'the directory predicate must literally contain the rollup predicate');
+  assert.ok(scoutingListableSql('pa').includes(recruiterReachSql('pa')),
+    'and the reach predicate — wiring reach in is the whole of task 1002290');
+  assert.ok(!rollupVisibleSql('pa').includes('recruiter_discoverable'),
+    'and reach must NOT leak back down into the rollup rule: the community spec D3 '
+    + 'leaderboards join rollupVisibleSql and the opt-out must not empty them');
+});
+
+t('the alias is the one interpolated thing, and every builder refuses a non-identifier', () => {
   const inject = "pa; DROP TABLE platform_identity_accounts --";
   assert.throws(() => accountVisibleSql(inject), /bare SQL identifier/);
   assert.throws(() => rollupVisibleSql(inject), /bare SQL identifier/);
+  assert.throws(() => recruiterReachSql(inject), /bare SQL identifier/);
+  assert.throws(() => scoutingListableSql(inject), /bare SQL identifier/);
 });
 
 t('the JS ports answer exactly what the SQL asks, row for row', () => {
@@ -655,6 +695,11 @@ function accountFilter(where, params) {
   if (/\bprofile_state = 'active'/.test(where)) tests.push((r) => r.profile_state === 'active');
   if (/\baccount_visibility = 'public'/.test(where)) tests.push((r) => r.account_visibility === 'public');
   if (/\bNOT (?:[a-z_]+\.)?hide_stats\b/.test(where)) tests.push((r) => !r.hide_stats);
+  // The recruiting-reach COALESCE (task 1002290). Modelled through the shared JS
+  // twin, not re-implemented — an interpreter that read this term its own way
+  // could agree with a WRONG query. Unmodelled it would degrade to no filter,
+  // which is precisely what this interpreter exists to refuse.
+  if (/COALESCE\((?:[a-z_]+\.)?recruiter_discoverable,/.test(where)) tests.push(isRecruiterDiscoverable);
 
   const byId = /\b(?:[a-z_]+\.)?github_id = \$(\d+)/.exec(where);
   if (byId) { consumed.add(byId[1]); const v = params[Number(byId[1]) - 1]; tests.push((r) => String(r.github_id) === String(v)); }