@bongos/core 1.19.513 → 1.19.515

package/docs/api/openapi.json

@@ -161,6 +161,10 @@
       "name": "memory",
       "description": "Endpoints under `/api/bongos/memory`."
     },
+    {
+      "name": "mingle",
+      "description": "Endpoints under `/api/bongos/mingle`."
+    },
     {
       "name": "modules",
       "description": "Endpoints under `/api/bongos/modules`."
@@ -10054,6 +10058,253 @@
         ]
       }
     },
+    "/mingle": {
+      "get": {
+        "operationId": "get_mingle",
+        "tags": [
+          "mingle"
+        ],
+        "summary": "GET /mingle",
+        "description": ", and OWN-SCOPED — your own state, never someone else's. Who else has opted in to being introduced is a fact about them.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/mingle.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetMingleResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/mingle/opt-in": {
+      "put": {
+        "operationId": "put_mingle_opt_in",
+        "tags": [
+          "mingle"
+        ],
+        "summary": "PUT /mingle/opt-in",
+        "description": ", OWN-SCOPED. Keyed by the SESSION, never a body field — consent you can give on someone else's behalf is not consent.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/mingle.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutMingleOptInRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PutMingleOptInResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/mingle/pairs/{id}/decide": {
+      "post": {
+        "operationId": "post_mingle_pairs_id_decide",
+        "tags": [
+          "mingle"
+        ],
+        "summary": "POST /mingle/pairs/:id/decide",
+        "description": ". The UPDATE itself requires the caller to be one of the two people in the pair, so a builder cannot answer an introduction they are not part of — enforced in SQL, not by a check here that a later caller could skip.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/mingle.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostMinglePairsIdDecideRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostMinglePairsIdDecideResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/mingle/project": {
+      "put": {
+        "operationId": "put_mingle_project",
+        "tags": [
+          "mingle"
+        ],
+        "summary": "PUT /mingle/project",
+        "description": "perm: mingle.manage (floor metic) — see the header. Offering the feature to the project is an operator act; it still cannot pair anyone who has not opted themselves in.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `mingle.manage` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/lifecycle/routes/mingle.js",
+        "x-permissions": [
+          "mingle.manage"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutMingleProjectRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/mingle/round": {
+      "post": {
+        "operationId": "post_mingle_round",
+        "tags": [
+          "mingle"
+        ],
+        "summary": "POST /mingle/round",
+        "description": "perm: mingle.manage — running a round writes introductions for other people, so it is an operator action rather than something a builder does to themselves. Refuses on its own when the project switch is off (runMingleRound checks).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `mingle.manage` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/lifecycle/routes/mingle.js",
+        "x-permissions": [
+          "mingle.manage"
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostMingleRoundRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostMingleRoundResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/modules": {
       "get": {
         "operationId": "get_modules",
@@ -10786,7 +11037,7 @@
           "projects"
         ],
         "summary": "GET /projects/featured",
-        "description": "a curated public showcase; no auth by design.\n\n**Rank:** `public` — No authentication — any caller.",
+        "description": "the public map of projects; no auth by design.\n\n**Rank:** `public` — No authentication — any caller.",
         "x-rank": "public",
         "x-source": "modules/platform-identity/routes/projects.js",
         "responses": {
@@ -16840,6 +17091,19 @@
           "files"
         ]
       },
+      "GetMingleResponse": {
+        "type": "object",
+        "properties": {
+          "mingle": {},
+          "open_pairs": {},
+          "matching": {}
+        },
+        "required": [
+          "mingle",
+          "open_pairs",
+          "matching"
+        ]
+      },
       "GetModulesResponse": {
         "type": "object",
         "properties": {
@@ -20219,6 +20483,54 @@
         },
         "additionalProperties": true
       },
+      "PostMinglePairsIdDecideRequest": {
+        "type": "object",
+        "properties": {
+          "decision": {
+            "type": "string",
+            "enum": [
+              "accepted",
+              "declined"
+            ]
+          }
+        },
+        "required": [
+          "decision"
+        ],
+        "additionalProperties": false
+      },
+      "PostMinglePairsIdDecideResponse": {
+        "type": "object",
+        "properties": {
+          "pair": {}
+        },
+        "required": [
+          "pair"
+        ]
+      },
+      "PostMingleRoundRequest": {
+        "type": "object",
+        "properties": {
+          "limit": {
+            "type": "integer",
+            "minimum": 1
+          }
+        },
+        "additionalProperties": false
+      },
+      "PostMingleRoundResponse": {
+        "type": "object",
+        "properties": {
+          "paired": {},
+          "count": {},
+          "skipped": {}
+        },
+        "required": [
+          "paired",
+          "count",
+          "skipped"
+        ]
+      },
       "PostModulesKeyEnableRequest": {
         "type": "object",
         "properties": {
@@ -21683,6 +21995,41 @@
           "granted"
         ]
       },
+      "PutMingleOptInRequest": {
+        "type": "object",
+        "properties": {
+          "opted_in": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "opted_in"
+        ],
+        "additionalProperties": false
+      },
+      "PutMingleOptInResponse": {
+        "type": "object",
+        "properties": {
+          "opted_in": {},
+          "updated_at": {}
+        },
+        "required": [
+          "opted_in",
+          "updated_at"
+        ]
+      },
+      "PutMingleProjectRequest": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "enabled"
+        ],
+        "additionalProperties": false
+      },
       "PutTasksIdDependenciesRequest": {
         "type": "object",
         "properties": {
@@ -21834,9 +22181,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 347,
-  "x-schema-count": 379,
+  "x-endpoint-count": 352,
+  "x-schema-count": 387,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 259,
+  "x-response-schemas": 263,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 347 endpoints across 56 route files.
+> **Generated from the live route files** — the route file is authoritative. 352 endpoints across 57 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -399,6 +399,16 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/memory/files` | `any-builder` | — | GET /memory/files — list the AUTHENTICATED builder's memory files (metadata only, no content). |
 | POST | `/api/bongos/memory/sync` | `any-builder` | `files` | POST /memory/sync — push a builder's local memory files to the server. |
 
+## `mingle` (5)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/mingle` | `any-builder` | — | , and OWN-SCOPED — your own state, never someone else's. |
+| PUT | `/api/bongos/mingle/opt-in` | `any-builder` | `opted_in` | , OWN-SCOPED. |
+| POST | `/api/bongos/mingle/pairs/:id/decide` | `any-builder` | `decision` | . |
+| PUT | `/api/bongos/mingle/project` | `metic+archon` | `enabled` | perm: mingle.manage (floor metic) — see the header. |
+| POST | `/api/bongos/mingle/round` | `metic+archon` | `limit` | perm: mingle.manage — running a round writes introductions for other people, so it is an operator action rather than something a builder … |
+
 ## `modules` (4)
 
 | Method | Path | Rank | Body | Description |
@@ -439,7 +449,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/projects` | `metic+archon` | — | the full curation list (includes unfeatured + owner attribution). |
 | POST | `/api/bongos/projects` | `metic+archon` | `origin`, `name`, `tagline`, `description`, `art_url`, `type`, `template` | create / update a catalog entry (manual seed for hand-wired instances; federated projects auto-catalogue at registration). |
 | PATCH | `/api/bongos/projects/:id/featured` | `metic+archon` | `featured` | the feature / unfeature control (the ADR 0141 §5 curation gate), BOUNDED BY THE PUBLISH GATE (ADR 0182 D3, task 1002335). |
-| GET | `/api/bongos/projects/featured` | `public` | — | a curated public showcase; no auth by design. |
+| GET | `/api/bongos/projects/featured` | `public` | — | the public map of projects; no auth by design. |
 | POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | invite a builder into a project (ADR 0141 §5, task #1002115). |
 
 ## `provisioning` (21)

package/docs/module-api-changelog.md

@@ -1463,5 +1463,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.511 with no explicit bump. run 33793208383. (task 1002620)
   1.19.513 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         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)
 ---------------------------------------------------------------------------
 ```

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;