@bongos/core 1.19.514 → 1.19.516

package/docs/module-api-changelog.md

@@ -1465,5 +1465,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.512 with no explicit bump. run 33795977371. (task 1002620)
   1.19.514 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.513 with no explicit bump. run 33796959752. (task 1002620)
+  1.19.515 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.514 with no explicit bump. run 33797825811. (task 1002620)
+  1.19.516 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.515 with no explicit bump. run 33798954769. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -587,6 +587,18 @@ function createClient(opts = {}) {
       // POST /memory/sync — rank: any-builder — POST /memory/sync
       postMemorySync: (args) => request("POST", "/memory/sync", { hasBody: true }, args),
     },
+    "mingle": {
+      // GET /mingle — rank: any-builder — GET /mingle
+      getMingle: (args) => request("GET", "/mingle", { hasBody: false }, args),
+      // PUT /mingle/opt-in — rank: any-builder — PUT /mingle/opt-in
+      putMingleOptIn: (args) => request("PUT", "/mingle/opt-in", { hasBody: true }, args),
+      // POST /mingle/pairs/{id}/decide — rank: any-builder — POST /mingle/pairs/:id/decide
+      postMinglePairsIdDecide: (args) => request("POST", "/mingle/pairs/{id}/decide", { hasBody: true }, args),
+      // PUT /mingle/project — rank: metic+archon — PUT /mingle/project
+      putMingleProject: (args) => request("PUT", "/mingle/project", { hasBody: true }, args),
+      // POST /mingle/round — rank: metic+archon — POST /mingle/round
+      postMingleRound: (args) => request("POST", "/mingle/round", { hasBody: true }, args),
+    },
     "modules": {
       // GET /modules — rank: any-builder — GET /modules
       getModules: (args) => request("GET", "/modules", { hasBody: false }, args),

package/modules/government/catalog.js

@@ -194,6 +194,12 @@ const PERMISSIONS = [
   { key: 'box.fleet.manage', system: false, floor: 'metic', scope: 'any', resource: 'box', guards: 'GET /boxes[/cost-ledger], POST /boxes/:b/close, PATCH .../block (ADR 0157, was archon)' },
   { key: 'autonomy.precheck', system: false, floor: 'metic', guards: 'GET /autonomy/precheck — unsupervised-runner gate (ADR 0157, was archon)' },
   { key: 'discord.channels.manage', system: false, floor: 'metic', guards: 'GET /discord/channels/plan, POST .../reconcile (ADR 0157, was archon)' },
+  // Metic by the discord.channels.manage analogue — configuring a project-wide
+  // social surface — rather than archon. The blast radius is bounded by the OTHER
+  // switch: enabling mingle offers it, and can never pair a builder who has not
+  // personally opted in (task 1003177, ADR 0187 §5), so this atom cannot put
+  // anyone in a room with a stranger on its own.
+  { key: 'mingle.manage', system: false, floor: 'metic', guards: 'PUT /mingle/project (the project half of mingle consent), POST /mingle/round (run a pairing round) — task 1003177, goal 1000075' },
   { key: 'project.curate', system: false, floor: 'metic', guards: 'platform-identity: GET/POST /projects, /projects/invite, PATCH /projects/:id/featured, GET /scouting (ADR 0157, was archon)' },
   { key: 'override_request.decide', system: false, floor: 'metic', guards: 'GET /override-requests, POST .../:id/decide (ADR 0157, was archon)' },
   { key: 'claim.release.any', system: false, floor: 'metic', scope: 'any', resource: 'claim', guards: 'POST /claims/:id/release-on-behalf (ADR 0157, was archon)' },

package/modules/government/migrations/government_009_mingle_manage.sql

@@ -0,0 +1,55 @@
+-- government_009_mingle_manage.sql — grant the new `mingle.manage` atom to the
+-- Metic and Archon rank-roles (task 1003177 / C07, goal 1000075; ADR 0187 §5).
+--
+-- Mingle's two operator routes — `PUT /mingle/project` (the PROJECT half of
+-- mingle consent) and `POST /mingle/round` (run a pairing round) — need a gate,
+-- and BV1.R105 says a modules/*/routes gate is a permission atom and never a
+-- rank: tests/government_require_permission.mjs fails the build on a new
+-- `requireRank`, and the two files still spelling it that way are documented
+-- holdouts rather than a pattern to copy.
+--
+-- FLOOR `metic`, by the `discord.channels.manage` analogue — configuring a
+-- project-wide social surface — rather than archon. What makes that safe is
+-- mingle's OTHER switch: enabling mingle only OFFERS it, and the matcher can never
+-- pair a builder who has not personally opted in (lifecycle_mingle_optin), so this
+-- atom cannot put anyone in a room with a stranger on its own.
+--
+-- A BRAND-NEW key: no rank holds it yet, so BOTH rungs the floor implies are
+-- granted here. RANK_SEED is a cumulative superset — floor `metic` means
+-- {metic, archon} — and the drift guard (tests/government_seed.mjs) compares the
+-- UNION of the run-once seed plus every later grant migration against that
+-- floor-derived seed, per rank. Minting the catalog row WITHOUT this migration is
+-- exactly what that guard caught on this task.
+--
+-- COPY government_004_board_permissions.sql, NOT governance_004_criterion_create.
+-- The `governance_*` grant migrations predate government_001_rename_from_governance,
+-- which renamed `governance_role_permissions` → `government_rank_permissions` and
+-- its `role_key` column → `rank_key`, with NO compatibility shim. Copying one of
+-- those files verbatim — which the first draft of THIS migration did — writes to a
+-- table that no longer exists, so it errors at apply time on any database that
+-- runs migrations in filename order, a fresh install included. The drift guard
+-- above does not catch it: it is a regex over `SELECT '<rank>', unnest(ARRAY[…])`
+-- and never looks at the target table (tests/mingle.mjs now checks that part).
+--
+-- Additive only: one new permission key granted to two ranks; nothing is revoked.
+-- Idempotent (ON CONFLICT DO NOTHING); forward-safe (INSERT only).
+--
+-- One block PER RANK, in the government_004 shape: the drift guard scans for
+-- `SELECT '<rank>', unnest(ARRAY[…])` literally, so a combined
+-- `unnest(ARRAY['metic','archon']), 'key'` form parses as zero grants and reds it.
+
+BEGIN;
+
+INSERT INTO government_rank_permissions (rank_key, permission_key)
+SELECT 'metic', unnest(ARRAY[
+  'mingle.manage'
+])
+ON CONFLICT (rank_key, permission_key) DO NOTHING;
+
+INSERT INTO government_rank_permissions (rank_key, permission_key)
+SELECT 'archon', unnest(ARRAY[
+  'mingle.manage'
+])
+ON CONFLICT (rank_key, permission_key) DO NOTHING;
+
+COMMIT;

package/modules/lifecycle/migrations/lifecycle_007_mingle.sql

@@ -0,0 +1,134 @@
+-- lifecycle_007_mingle.sql — mingle: pairing two builders who do NOT share a craft,
+-- and only when both the project and the person said yes (task 1003177 / C07,
+-- goal 1000075; criterion collab-mingle-two-switches, ADR 0187 §5).
+--
+-- TWO SWITCHES, AND THIS TABLE IS ONLY THE SECOND ONE. Consent is the project
+-- enabling mingle AND the individual opting in. The PROJECT switch is not here —
+-- it is `project_settings['mingle.enabled']` (migration core_231), because a
+-- project-wide knob belongs in the project's own store and forking a second one is
+-- what src/bongos/project-settings.js exists to prevent. This table is the
+-- per-builder half. Both are read on every pairing; either one off means no pair.
+--
+-- WHY AN EXPLICIT ROW RATHER THAN A behavior_prefs KEY. Opting in to be
+-- auto-introduced to a stranger a few times a week is a real-world social
+-- commitment, so the record of it should say WHEN it was given and be legible on
+-- its own — not be one key inside a jsonb blob of unrelated UI knobs. It also
+-- keeps the write inside this module: lifecycle may READ core `builders`, but the
+-- behaviour prefs belong to builder-settings and writing them from here would
+-- reach across a module boundary (ADR 0083).
+--
+-- FAIL CLOSED, both halves. No row means NOT participating — never "hasn't said
+-- no". `opted_in = false` is a deliberate withdrawal and is kept rather than
+-- deleted, so the surface can tell "asked and declined the whole feature" from
+-- "never offered it", the same distinction ADR 0171 draws between a hidden account
+-- and one that never federated.
+--
+-- MODULE-OWNED and `lifecycle_`-prefixed, so fitness check 11 permits it (ADR 0083
+-- §Decision #5). Mirrors lifecycle_004_help_requests and lifecycle_005_task_-
+-- recommendations, its siblings under this goal.
+
+CREATE TABLE IF NOT EXISTS lifecycle_mingle_optin (
+  builder_id   bigint PRIMARY KEY REFERENCES builders(id),
+
+  -- The switch itself. See the header: absent ≠ false ≠ true.
+  opted_in     boolean NOT NULL,
+
+  -- When consent was last changed. The criterion calls mingle a real-world social
+  -- commitment; a consent record with no timestamp cannot answer "since when".
+  updated_at   timestamptz NOT NULL DEFAULT now()
+);
+
+-- The matcher's read: everyone currently participating.
+CREATE INDEX IF NOT EXISTS lifecycle_mingle_optin_in_idx
+  ON lifecycle_mingle_optin (builder_id) WHERE opted_in = true;
+
+COMMENT ON TABLE lifecycle_mingle_optin IS
+  'The per-builder half of mingle consent (task 1003177). The project half is project_settings[''mingle.enabled'']; both must be on. No row means not participating.';
+
+
+-- ---------------------------------------------------------------------------
+-- The pairs
+-- ---------------------------------------------------------------------------
+--
+-- A PROPOSAL, never an obligation. A row here says "you two were introduced"; it
+-- is declinable, and declining is terminal and free.
+--
+-- DECLINING COSTS NOTHING, AND THE SCHEMA IS WHERE THAT IS TRUE. There is no
+-- decline counter, no cooldown column, no cost or streak field on either party,
+-- and no karma or credit reference anywhere in this file — a table that recorded
+-- a decline ANYWHERE BUT HERE would be the penalty the criterion forbids. This is
+-- the same posture lifecycle_005 takes for a declined recommendation, deliberately
+-- restated rather than cross-referenced, because the next person to add a column
+-- reads this file and not that one.
+--
+-- Nothing reads `status` back into matching, either: the matcher's eligibility read
+-- never joins this table, so a decline cannot make the decliner less likely to be
+-- paired again. That is the "no future matching weight" half of the criterion, and
+-- it is a property of the READ, not a promise made here.
+
+CREATE TABLE IF NOT EXISTS lifecycle_mingle_pairs (
+  id             bigserial PRIMARY KEY,
+
+  -- Ordered low/high at write time so a pair has ONE row whichever way round it
+  -- was generated, and the open-pair unique index below actually bites.
+  builder_lo     bigint NOT NULL REFERENCES builders(id),
+  builder_hi     bigint NOT NULL REFERENCES builders(id),
+
+  -- The crafts that made this pair legal, recorded AS MATCHED. The criterion asks
+  -- for cross-craft "chosen deliberately and recorded"; storing the two crafts
+  -- means a pair can be audited later even if a builder changes their disciplines
+  -- afterwards, which a re-derivation from builders.preferred_disciplines could
+  -- not do.
+  craft_lo       text NOT NULL,
+  craft_hi       text NOT NULL,
+
+  -- 'proposed' — introduced, nobody has answered
+  -- 'accepted' — someone said yes
+  -- 'declined' — someone said no. Terminal, and carries NO consequence.
+  status         text NOT NULL DEFAULT 'proposed',
+
+  -- Who answered. A record of what happened, never an input to matching.
+  decided_by     bigint REFERENCES builders(id),
+  decided_at     timestamptz,
+
+  created_at     timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT lifecycle_mingle_pairs_status_chk
+    CHECK (status IN ('proposed', 'accepted', 'declined')),
+
+  -- Pairing someone with themselves is not a pairing.
+  CONSTRAINT lifecycle_mingle_pairs_not_self_chk
+    CHECK (builder_lo <> builder_hi),
+
+  -- The ordering invariant the open-pair index depends on.
+  CONSTRAINT lifecycle_mingle_pairs_ordered_chk
+    CHECK (builder_lo < builder_hi),
+
+  -- CROSS-CRAFT IS A DATABASE CONSTRAINT, not only a matcher rule. The criterion's
+  -- first testable claim is "a pair is only ever cross-craft"; enforcing it solely
+  -- in the matcher would leave any future writer — a backfill, a second caller, a
+  -- fixture — free to violate the one property the feature is named for.
+  CONSTRAINT lifecycle_mingle_pairs_cross_craft_chk
+    CHECK (craft_lo <> craft_hi),
+
+  CONSTRAINT lifecycle_mingle_pairs_decided_chk
+    CHECK ((status = 'proposed') = (decided_at IS NULL))
+);
+
+-- One OPEN proposal per pair. Partial, so a pair CAN be introduced again in a later
+-- round after it was settled — a permanent unique key would make a single decline
+-- final between two people forever, which is a consequence, and declining is free.
+CREATE UNIQUE INDEX IF NOT EXISTS lifecycle_mingle_pairs_open_uniq
+  ON lifecycle_mingle_pairs (builder_lo, builder_hi) WHERE status = 'proposed';
+
+-- "What am I being introduced to right now" — both sides of an open pair.
+CREATE INDEX IF NOT EXISTS lifecycle_mingle_pairs_open_lo_idx
+  ON lifecycle_mingle_pairs (builder_lo) WHERE status = 'proposed';
+CREATE INDEX IF NOT EXISTS lifecycle_mingle_pairs_open_hi_idx
+  ON lifecycle_mingle_pairs (builder_hi) WHERE status = 'proposed';
+
+COMMENT ON TABLE lifecycle_mingle_pairs IS
+  'A cross-craft mingle introduction (task 1003177). Declinable, and a decline is terminal, free, and never read back into matching.';
+
+INSERT INTO schema_migrations (version) VALUES ('lifecycle_007_mingle')
+ON CONFLICT (version) DO NOTHING;

package/modules/lifecycle/mingle.js

@@ -0,0 +1,337 @@
+// modules/lifecycle/mingle.js — mingle: two switches, cross-craft, declinable
+// without penalty (task 1003177 / C07, goal 1000075; criterion
+// collab-mingle-two-switches, ADR 0187 §5).
+//
+// THE DECISION. Mingle introduces two builders who do NOT share a craft. The
+// owner's reasoning (ADR 0187 §5) is the goal's founding premise — the person you
+// need is often not another one of you — and it is also what keeps mingle doing
+// something the craft-matched Collab request path does not already do.
+// Same-craft pairing was considered and REJECTED as duplicating
+// collab-page-matches-my-craft; do not "improve" the matcher by adding it back.
+//
+// TWO SWITCHES, AND ONE IS NOT CONSENT. A pair happens only when the PROJECT has
+// enabled mingle AND the individual has opted in. Auto-pairing a person with a
+// stranger a few times a week is a real-world social commitment, so the project
+// enabling it for everyone is not the person agreeing to it, and a person opting
+// in on an instance that never turned it on is not the project offering it. Both
+// are read on every pairing, and both FAIL CLOSED: absent is "no", never
+// "hasn't said no yet" (the ADR 0171 posture, inherited).
+//
+// DECLINING IS FREE, AND THAT IS A PROPERTY OF THE READ, NOT A PROMISE.
+// "Without penalty" means declining affects no rank, no karma, no streak and no
+// future matching weight — and the criterion insists that be verifiable rather
+// than stated. Two things make it so, and both are structural:
+//
+//   1. `decline()` writes ONE row in ONE table — the pair it is settling. It
+//      touches no credit, karma, rank or streak surface, and there is no counter
+//      anywhere to touch (see lifecycle_007_mingle.sql, which says the same thing
+//      about the schema).
+//   2. `eligibleBuilders()` — the matcher's ONLY input about who may be paired —
+//      never reads lifecycle_mingle_pairs at all. A decline therefore cannot make
+//      the decliner less likely to be paired again, because the read that decides
+//      that has no way to see it. The one thing pair history does gate is a second
+//      OPEN proposal for the same two people, which is the unique index's job and
+//      is about not double-introducing, not about declines.
+//
+// tests/mingle.mjs drives both against a recording pool and fails if either stops
+// being true.
+//
+// THE CRAFT VOCABULARY IS NOT REDEFINED HERE. help-requests.js declares itself the
+// one place that knows how a craft maps to `builders.preferred_disciplines`
+// ('builder' the craft is 'engineer' the discipline), so this file consumes
+// `craftMapSql` / `craftForDiscipline` from it rather than re-deriving. Two
+// spellings of the same craft would silently match nobody.
+//
+// Reaches core only through the doorway (ADR 0083). The core tables it reads
+// (builders) are read-only here.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { pool } = api;
+const { craftMapSql } = require('./help-requests');
+
+// The PROJECT switch. A module-owned knob in the project's own store
+// (project_settings, migration core_231) — deliberately NOT a second settings
+// table, which is the thing src/bongos/project-settings.js exists to prevent, and
+// deliberately not registered in that file's core SETTING_KEYS: the key is
+// namespaced to this surface, and a module's knob is the module's to name.
+const MINGLE_ENABLED_KEY = 'mingle.enabled';
+
+const MAX_ROWS = 100;
+
+// THE MATCHING RULE, RECORDED. The criterion asks for cross-craft to be "chosen
+// deliberately and recorded", so the rule is data a reader can fetch (the route
+// serves this verbatim) rather than a shape you have to infer from the SQL — the
+// same reason closeness-weights.json exists.
+const MATCHING = Object.freeze({
+  rule: 'cross_craft',
+  description:
+    'A pair is two builders whose crafts do not overlap at all — an engineer with '
+    + 'an artist or an ideator, never two of the same. The premise is that the '
+    + 'person you need is often not another one of you.',
+  // Stated because it is the road not taken, and an unexplained absence reads as
+  // an oversight to the next person holding the matcher.
+  rejected: 'same_craft — it duplicates the craft-matched Collab request path (criterion collab-page-matches-my-craft).',
+  // DISJOINT, not merely "different". A builder who is both an artist and an
+  // engineer shares a craft with every engineer, so pairing them would put two of
+  // the same in a room and call it cross-craft.
+  overlap: 'none',
+  consent: 'Both switches required: the project enables mingle AND the builder opts in. Either off means no pair.',
+  decline: 'Terminal and free — no rank, karma, streak or matching effect. The eligibility read never sees pair history.',
+});
+
+function matchingModel() { return MATCHING; }
+
+// ---------------------------------------------------------------------------
+// Switch 1 — the project
+// ---------------------------------------------------------------------------
+
+// TRUE only for an explicit, recognised yes. Everything else — absent, blank,
+// 'maybe', a value that was valid before someone tightened this — is NO.
+//
+// This is the one place mingle deliberately DIVERGES from the rot timer's posture
+// in src/bongos/project-settings.js. That file reports a bad value on the screen
+// of the person who can fix it, because all of its callers are read surfaces. This
+// is a consent gate: an unreadable switch must not open, so it fails closed the
+// way ADR 0171's consent state does. One enforces, one reports.
+function parseEnabled(raw) {
+  if (raw == null) return false;
+  return ['true', '1', 'on', 'yes'].includes(String(raw).trim().toLowerCase());
+}
+
+async function projectEnabled(deps = {}) {
+  const get = deps.getSetting || api.projectSettings.get;
+  let row;
+  try {
+    row = await get(MINGLE_ENABLED_KEY);
+  } catch (_) {
+    // FAIL CLOSED. An unreadable switch is not permission.
+    return false;
+  }
+  return parseEnabled(row && row.value);
+}
+
+async function setProjectEnabled(enabled, builderId = null, deps = {}) {
+  const set = deps.setSetting || api.projectSettings.set;
+  await set(MINGLE_ENABLED_KEY, enabled ? 'true' : 'false', builderId);
+  return { key: MINGLE_ENABLED_KEY, enabled: !!enabled };
+}
+
+// ---------------------------------------------------------------------------
+// Switch 2 — the builder
+// ---------------------------------------------------------------------------
+
+// null = never offered / never answered. Deliberately distinct from false, which
+// is a deliberate withdrawal — a surface that cannot tell them apart cannot ask
+// the right question.
+async function optInState(builderId, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    'SELECT opted_in, updated_at FROM lifecycle_mingle_optin WHERE builder_id = $1',
+    [builderId]
+  );
+  if (!rows[0]) return { opted_in: null, updated_at: null };
+  return { opted_in: rows[0].opted_in === true, updated_at: rows[0].updated_at };
+}
+
+async function setOptIn(builderId, optedIn, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `INSERT INTO lifecycle_mingle_optin (builder_id, opted_in, updated_at)
+          VALUES ($1, $2, now())
+     ON CONFLICT (builder_id) DO UPDATE
+            SET opted_in = EXCLUDED.opted_in, updated_at = now()
+      RETURNING builder_id, opted_in, updated_at`,
+    [builderId, !!optedIn]
+  );
+  return rows[0];
+}
+
+// BOTH switches, resolved together, for one builder. The surface that asks "can I
+// mingle" gets back which half is off, because "no" with no reason is a dead end
+// for the person who could turn their own half on.
+async function mingleStateFor(builderId, deps = {}) {
+  const [project, mine] = await Promise.all([projectEnabled(deps), optInState(builderId, deps)]);
+  return {
+    enabled: project && mine.opted_in === true,
+    project_enabled: project,
+    opted_in: mine.opted_in,
+    opted_in_at: mine.updated_at,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The matcher
+// ---------------------------------------------------------------------------
+
+// Everyone the project may introduce right now: opted in, active, and carrying at
+// least one craft.
+//
+// IT DOES NOT JOIN lifecycle_mingle_pairs, AND MUST NOT. This read is the whole of
+// "who may be paired", so the moment it can see a decline, declining has a
+// matching cost and the criterion is broken. See the header.
+//
+// A builder with no `preferred_disciplines` produces no rows through the unnest and
+// is therefore absent — the correct fail-closed answer, and the same one
+// help-requests gives: belonging to a craft is a claim about yourself the system
+// should not assume on your behalf.
+async function eligibleBuilders(deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT b.id::text AS builder_id,
+            array_agg(DISTINCT ${craftMapSql('d')}) FILTER (WHERE ${craftMapSql('d')} IS NOT NULL) AS crafts
+       FROM lifecycle_mingle_optin o
+       JOIN builders b ON b.id = o.builder_id
+       CROSS JOIN LATERAL unnest(b.preferred_disciplines) AS d
+      WHERE o.opted_in = true
+        AND b.status = 'active'
+      GROUP BY b.id
+      ORDER BY b.id`
+  );
+  return rows
+    .map((r) => ({ builder_id: String(r.builder_id), crafts: (r.crafts || []).filter(Boolean).sort() }))
+    .filter((b) => b.crafts.length > 0);
+}
+
+// PURE. Is this pair legal? Disjoint craft sets — see MATCHING.overlap.
+function isCrossCraft(craftsA, craftsB) {
+  const a = new Set(craftsA || []);
+  if (!a.size || !(craftsB || []).length) return false;
+  return !(craftsB || []).some((c) => a.has(c));
+}
+
+// PURE. Given eligible builders, produce cross-craft pairs — each builder in at
+// most one pair. Greedy over a stable order so the same input always yields the
+// same pairing (a matcher that shuffles cannot be tested, and cannot be explained
+// to the person it introduced).
+//
+// `excludePairs` is the set of "lo:hi" keys that already hold an OPEN proposal. It
+// is NOT decline history: settled pairs are absent from it and may be introduced
+// again, because a decline that permanently separated two people would be a
+// consequence, and declining is free.
+function planPairs(eligible, { excludePairs = new Set(), limit = MAX_ROWS } = {}) {
+  const taken = new Set();
+  const out = [];
+  const list = [...eligible].sort((a, b) => String(a.builder_id).localeCompare(String(b.builder_id)));
+  for (let i = 0; i < list.length && out.length < limit; i++) {
+    const a = list[i];
+    if (taken.has(a.builder_id)) continue;
+    for (let j = i + 1; j < list.length; j++) {
+      const b = list[j];
+      if (taken.has(b.builder_id)) continue;
+      if (!isCrossCraft(a.crafts, b.crafts)) continue;
+      const pair = orderPair(a, b);
+      if (excludePairs.has(pairKey(pair.lo.builder_id, pair.hi.builder_id))) continue;
+      taken.add(a.builder_id); taken.add(b.builder_id);
+      out.push({
+        builder_lo: pair.lo.builder_id,
+        builder_hi: pair.hi.builder_id,
+        // One representative craft each. The sets are disjoint, so any pick
+        // differs — recording them is what lets a pair be audited later even if
+        // someone changes their disciplines afterwards.
+        craft_lo: pair.lo.crafts[0],
+        craft_hi: pair.hi.crafts[0],
+      });
+      break;
+    }
+  }
+  return out;
+}
+
+function orderPair(a, b) {
+  return String(a.builder_id).padStart(24, '0') <= String(b.builder_id).padStart(24, '0')
+    ? { lo: a, hi: b } : { lo: b, hi: a };
+}
+
+function pairKey(lo, hi) { return `${lo}:${hi}`; }
+
+async function openPairKeys(deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT builder_lo::text AS lo, builder_hi::text AS hi
+       FROM lifecycle_mingle_pairs WHERE status = 'proposed'`
+  );
+  return new Set(rows.map((r) => pairKey(String(r.lo), String(r.hi))));
+}
+
+// Introduce everyone who can be introduced, and write the pairs. Refuses outright
+// when the PROJECT switch is off — the per-builder switch is already enforced by
+// eligibleBuilders, which only ever returns people who opted in.
+async function runMingleRound({ limit = MAX_ROWS } = {}, deps = {}) {
+  if (!(await projectEnabled(deps))) return { paired: [], skipped: 'project_disabled' };
+  const activePool = deps.pool || pool;
+  const [eligible, open] = await Promise.all([eligibleBuilders(deps), openPairKeys(deps)]);
+  const planned = planPairs(eligible, { excludePairs: open, limit });
+  if (!planned.length) return { paired: [], skipped: null };
+
+  // ONE insert for the whole round, not one per pair. The round is bounded to
+  // MAX_ROWS and runs rarely, so this is not a hot path — but a loop of awaited
+  // INSERTs is also a partial write when the tenth throws, and unnest() makes the
+  // round atomic for free. ON CONFLICT DO NOTHING lets the open-pair unique index
+  // drop a pair another round introduced a moment ago rather than failing all of
+  // them; RETURNING is therefore what was actually written, never what was planned.
+  const { rows } = await activePool.query(
+    `INSERT INTO lifecycle_mingle_pairs (builder_lo, builder_hi, craft_lo, craft_hi)
+     SELECT * FROM unnest($1::bigint[], $2::bigint[], $3::text[], $4::text[])
+     ON CONFLICT DO NOTHING
+      RETURNING id, builder_lo::text AS builder_lo, builder_hi::text AS builder_hi,
+                craft_lo, craft_hi, status, created_at`,
+    [
+      planned.map((p) => p.builder_lo),
+      planned.map((p) => p.builder_hi),
+      planned.map((p) => p.craft_lo),
+      planned.map((p) => p.craft_hi),
+    ]
+  );
+  return { paired: rows, skipped: null };
+}
+
+// The open introductions for one builder, either side of the pair.
+async function openPairsFor(builderId, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT p.id, p.builder_lo::text AS builder_lo, p.builder_hi::text AS builder_hi,
+            p.craft_lo, p.craft_hi, p.status, p.created_at,
+            lo.github_login AS lo_login, lo.display_name AS lo_name,
+            hi.github_login AS hi_login, hi.display_name AS hi_name
+       FROM lifecycle_mingle_pairs p
+       JOIN builders lo ON lo.id = p.builder_lo
+       JOIN builders hi ON hi.id = p.builder_hi
+      WHERE p.status = 'proposed'
+        AND (p.builder_lo = $1 OR p.builder_hi = $1)
+      ORDER BY p.created_at DESC`,
+    [builderId]
+  );
+  return rows;
+}
+
+// Accept or decline an introduction you are part of.
+//
+// ONE ROW, ONE TABLE. There is nothing else to write, and that absence IS the
+// "without penalty" guarantee — see the header and the migration. Do not add a
+// counter, a cooldown, or a karma/credit call here.
+async function decidePair(pairId, builderId, decision, deps = {}) {
+  const activePool = deps.pool || pool;
+  if (!['accepted', 'declined'].includes(decision)) return { error: 'bad_decision' };
+  const { rows } = await activePool.query(
+    `UPDATE lifecycle_mingle_pairs
+        SET status = $3, decided_by = $2, decided_at = now()
+      WHERE id = $1
+        AND status = 'proposed'
+        AND (builder_lo = $2 OR builder_hi = $2)
+      RETURNING id, builder_lo::text AS builder_lo, builder_hi::text AS builder_hi,
+                craft_lo, craft_hi, status, decided_by::text AS decided_by, decided_at`,
+    [pairId, builderId, decision]
+  );
+  if (!rows[0]) return { error: 'not_found' };
+  return { pair: rows[0] };
+}
+
+module.exports = {
+  MINGLE_ENABLED_KEY, MAX_ROWS, MATCHING, matchingModel,
+  parseEnabled, projectEnabled, setProjectEnabled,
+  optInState, setOptIn, mingleStateFor,
+  eligibleBuilders, isCrossCraft, planPairs, pairKey, openPairKeys,
+  runMingleRound, openPairsFor, decidePair,
+};

package/modules/lifecycle/module.json

@@ -21,6 +21,7 @@
       "help-requests",
       "recommendations",
       "closeness",
+      "mingle",
       "visuals",
       "kickoff-seed",
       "rot"