@bongos/core 1.19.418 → 1.19.419

package/docs/api/openapi.json

@@ -77,6 +77,10 @@
       "name": "closeness",
       "description": "Endpoints under `/api/bongos/closeness`."
     },
+    {
+      "name": "connections",
+      "description": "Endpoints under `/api/bongos/connections`."
+    },
     {
       "name": "copy-desk",
       "description": "Endpoints under `/api/bongos/copy-desk`."
@@ -3435,6 +3439,330 @@
         ]
       }
     },
+    "/connections": {
+      "get": {
+        "operationId": "get_connections",
+        "tags": [
+          "connections"
+        ],
+        "summary": "GET /connections",
+        "description": "MY accepted connections (own data, keyed on the session). Own scope, so the counterparty floors on profile_state alone: a private account you connected with appears here and in no public list (D4 §2).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetConnectionsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_connections",
+        "tags": [
+          "connections"
+        ],
+        "summary": "POST /connections",
+        "description": "ask to connect. The REQUESTER is always the session; the body names only who is being asked, and it names them by public handle.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostConnectionsRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostConnectionsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/connections/degree/{handle}": {
+      "get": {
+        "operationId": "get_connections_degree_handle",
+        "tags": [
+          "connections"
+        ],
+        "summary": "GET /connections/degree/:handle",
+        "description": "the degree label between the CALLER and one handle, plus the mutuals it was computed from (own-scope read, D4 §4). Bounded by construction: degreeBetween caps every level and answers null past the caps.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.js",
+        "parameters": [
+          {
+            "name": "handle",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `handle`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetConnectionsDegreeHandleResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/connections/requests": {
+      "get": {
+        "operationId": "get_connections_requests",
+        "tags": [
+          "connections"
+        ],
+        "summary": "GET /connections/requests",
+        "description": "MY pending requests, both directions (own data).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetConnectionsRequestsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/connections/{id}": {
+      "delete": {
+        "operationId": "delete_connections_id",
+        "tags": [
+          "connections"
+        ],
+        "summary": "DELETE /connections/:id",
+        "description": "remove an accepted connection (either side may end it) or cancel a pending request I sent. An ADDRESSEE ending a pending row is a decline, not a delete, and is 404'd here so the cooldown cannot be dodged.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeleteConnectionsIdResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/connections/{id}/accept": {
+      "post": {
+        "operationId": "post_connections_id_accept",
+        "tags": [
+          "connections"
+        ],
+        "summary": "POST /connections/:id/accept",
+        "description": "accept a request addressed to ME. The addressee is the session; a row belonging to anyone else simply does not match, and the 404 that follows is what stops a builder acting on someone else's connection.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostConnectionsIdAcceptResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/connections/{id}/decline": {
+      "post": {
+        "operationId": "post_connections_id_decline",
+        "tags": [
+          "connections"
+        ],
+        "summary": "POST /connections/:id/decline",
+        "description": "decline a request addressed to ME. 204: the requester is never told, so there is nothing to return that they could ever observe.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/connections.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/copy-desk/flags": {
       "post": {
         "operationId": "post_copy_desk_flags",
@@ -15051,6 +15379,15 @@
           "deleted"
         ]
       },
+      "DeleteConnectionsIdResponse": {
+        "type": "object",
+        "properties": {
+          "outcome": {}
+        },
+        "required": [
+          "outcome"
+        ]
+      },
       "DeleteDependenciesResponse": {
         "type": "object",
         "properties": {
@@ -15485,6 +15822,49 @@
           "why"
         ]
       },
+      "GetConnectionsDegreeHandleResponse": {
+        "type": "object",
+        "properties": {
+          "handle": {},
+          "degree": {},
+          "mutuals": {},
+          "mutual_count": {},
+          "truncated": {}
+        },
+        "required": [
+          "handle",
+          "degree",
+          "mutuals",
+          "mutual_count",
+          "truncated"
+        ]
+      },
+      "GetConnectionsRequestsResponse": {
+        "type": "object",
+        "properties": {
+          "incoming": {},
+          "outgoing": {},
+          "incoming_count": {},
+          "outgoing_count": {}
+        },
+        "required": [
+          "incoming",
+          "outgoing",
+          "incoming_count",
+          "outgoing_count"
+        ]
+      },
+      "GetConnectionsResponse": {
+        "type": "object",
+        "properties": {
+          "connections": {},
+          "count": {}
+        },
+        "required": [
+          "connections",
+          "count"
+        ]
+      },
       "GetDiscordChannelsPlanResponse": {
         "type": "object",
         "properties": {
@@ -17932,6 +18312,41 @@
           "reward"
         ]
       },
+      "PostConnectionsIdAcceptResponse": {
+        "type": "object",
+        "properties": {
+          "status": {}
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "PostConnectionsRequest": {
+        "type": "object",
+        "properties": {
+          "handle": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39
+          },
+          "note": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "handle"
+        ],
+        "additionalProperties": false
+      },
+      "PostConnectionsResponse": {
+        "type": "object",
+        "properties": {
+          "status": {}
+        },
+        "required": [
+          "status"
+        ]
+      },
       "PostCopyDeskFlagsIdCloseRequest": {
         "type": "object",
         "properties": {
@@ -20847,9 +21262,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 330,
-  "x-schema-count": 365,
+  "x-endpoint-count": 337,
+  "x-schema-count": 372,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 247,
+  "x-response-schemas": 253,
   "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. 330 endpoints across 53 route files.
+> **Generated from the live route files** — the route file is authoritative. 337 endpoints across 54 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`.
@@ -153,6 +153,18 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/closeness/weights` | `any-builder` | — | the MODEL is not private, and publishing it is the whole point of the weights being data. |
 | GET | `/api/bongos/closeness/with/:builderId` | `any-builder` | — | One pair — "why am I close to THEM", asked directly rather than by paging the graph. |
 
+## `connections` (7)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/connections` | `any-builder` | — | MY accepted connections (own data, keyed on the session). |
+| POST | `/api/bongos/connections` | `any-builder` | `handle`, `note` | ask to connect. |
+| DELETE | `/api/bongos/connections/:id` | `any-builder` | — | remove an accepted connection (either side may end it) or cancel a pending request I sent. |
+| POST | `/api/bongos/connections/:id/accept` | `any-builder` | — | accept a request addressed to ME. |
+| POST | `/api/bongos/connections/:id/decline` | `any-builder` | — | decline a request addressed to ME. |
+| GET | `/api/bongos/connections/degree/:handle` | `any-builder` | — | the degree label between the CALLER and one handle, plus the mutuals it was computed from (own-scope read, D4 §4). |
+| GET | `/api/bongos/connections/requests` | `any-builder` | — | MY pending requests, both directions (own data). |
+
 ## `copy-desk` (4)
 
 | Method | Path | Rank | Body | Description |

package/docs/module-api-changelog.md

@@ -1273,5 +1273,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.416 with no explicit bump. run 33263505319. (task 1002620)
   1.19.418 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.417 with no explicit bump. run 33264139544. (task 1002620)
+  1.19.419 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.418 with no explicit bump. run 33265382684. (task 1002620)
 ---------------------------------------------------------------------------
 ```

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

@@ -263,6 +263,22 @@ function createClient(opts = {}) {
       // GET /closeness/with/{builderId} — rank: any-builder — GET /closeness/with/:builderId
       getClosenessWithBuilderId: (args) => request("GET", "/closeness/with/{builderId}", { hasBody: false }, args),
     },
+    "connections": {
+      // GET /connections — rank: any-builder — GET /connections
+      getConnections: (args) => request("GET", "/connections", { hasBody: false }, args),
+      // POST /connections — rank: any-builder — POST /connections
+      postConnections: (args) => request("POST", "/connections", { hasBody: true }, args),
+      // DELETE /connections/{id} — rank: any-builder — DELETE /connections/:id
+      deleteConnectionsId: (args) => request("DELETE", "/connections/{id}", { hasBody: false }, args),
+      // POST /connections/{id}/accept — rank: any-builder — POST /connections/:id/accept
+      postConnectionsIdAccept: (args) => request("POST", "/connections/{id}/accept", { hasBody: true }, args),
+      // POST /connections/{id}/decline — rank: any-builder — POST /connections/:id/decline
+      postConnectionsIdDecline: (args) => request("POST", "/connections/{id}/decline", { hasBody: true }, args),
+      // GET /connections/degree/{handle} — rank: any-builder — GET /connections/degree/:handle
+      getConnectionsDegreeHandle: (args) => request("GET", "/connections/degree/{handle}", { hasBody: false }, args),
+      // GET /connections/requests — rank: any-builder — GET /connections/requests
+      getConnectionsRequests: (args) => request("GET", "/connections/requests", { hasBody: false }, args),
+    },
     "copyDesk": {
       // POST /copy-desk/flags — rank: any-builder — POST /copy-desk/flags
       postCopyDeskFlags: (args) => request("POST", "/copy-desk/flags", { hasBody: true }, args),

package/modules/platform-identity/account-visibility.js

@@ -0,0 +1,58 @@
+// modules/platform-identity/account-visibility.js — THE effective-visibility
+// predicate for a platform account, published in both forms so a route and a
+// query cannot drift (ADR 0202 D4; the ADR 0182 `publishableSql` precedent).
+//
+// WHAT IT ANSWERS: "may the world see that this account exists at all?" —
+// profile_state = 'active' (consent: a hub session has touched the account,
+// ADR 0171 D3) AND account_visibility = 'public' (existence: the privacy-spec
+// D1 axis). Both floors, ANDed, in one place.
+//
+// WHY ITS OWN FILE. ADR 0202 D4 requires connections to consume ONE shared
+// reader rather than grow a connections-flavoured variant — "adding a second
+// predicate is the drift ADR 0194 D7 exists to prevent". The reader the ADR
+// names belongs to task 1002967, which has not shipped; platform-identity.js is
+// already at the file-size ratchet. So the definition lands here, alone and
+// tiny, and 1002967 ADOPTS it rather than writing a second one.
+//
+// WHAT IT IS NOT. Not a rollup gate: hide_stats suppresses NUMBERS, not
+// existence, and is applied by the rollup readers (ADR 0171 D2), never here.
+// Not authority: an account being visible confers nothing (ADR 0016).
+//
+// Fail-closed: a missing/absent account row is invisible, never visible
+// (ADR 0192 §6 / ADR 0194 §2).
+'use strict';
+
+// The JS twin. `account` is any row carrying profile_state + account_visibility;
+// anything falsy (absent row, unreadable account) answers false.
+function isAccountVisible(account) {
+  if (!account) return false;
+  return account.profile_state === 'active' && account.account_visibility === 'public';
+}
+
+// The SAME predicate as a SQL fragment, for the reads that filter in the
+// database. `alias` qualifies the columns for a joined query (e.g.
+// accountVisibleSql('pa')); omit it for an unaliased single-table query.
+function accountVisibleSql(alias) {
+  // The alias is INTERPOLATED, so it is the one thing here that could carry SQL.
+  // Callers pass a literal, but a helper that builds SQL should refuse anything
+  // that is not a bare identifier rather than trust every future caller.
+  if (alias && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(alias))) {
+    throw new Error('accountVisibleSql: alias must be a bare SQL identifier');
+  }
+  const q = alias ? `${alias}.` : '';
+  return `(${q}profile_state = 'active' AND ${q}account_visibility = 'public')`;
+}
+
+// The CONSENT floor on its own — active, without the existence axis. A private
+// account is still a real participant in its OWN scope: ADR 0202 D4 §2 says its
+// connections appear in its own list and in the counterparty's own list, and an
+// incoming request must name who is asking or it cannot be decided. Those
+// own-scope reads floor on this; every PUBLIC read floors on accountVisibleSql.
+function accountActiveSql(alias) {
+  if (alias && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(alias))) {
+    throw new Error('accountActiveSql: alias must be a bare SQL identifier');
+  }
+  return `(${alias ? `${alias}.` : ''}profile_state = 'active')`;
+}
+
+module.exports = { isAccountVisible, accountVisibleSql, accountActiveSql };