@bongos/core 1.19.358 → 1.19.360

package/docs/api/openapi.json

@@ -73,6 +73,10 @@
       "name": "claims",
       "description": "Endpoints under `/api/bongos/claims`."
     },
+    {
+      "name": "closeness",
+      "description": "Endpoints under `/api/bongos/closeness`."
+    },
     {
       "name": "copy-desk",
       "description": "Endpoints under `/api/bongos/copy-desk`."
@@ -205,6 +209,10 @@
       "name": "sso",
       "description": "Endpoints under `/api/bongos/sso`."
     },
+    {
+      "name": "task-recommendations",
+      "description": "Endpoints under `/api/bongos/task-recommendations`."
+    },
     {
       "name": "task-visuals",
       "description": "Endpoints under `/api/bongos/task-visuals`."
@@ -3191,6 +3199,134 @@
         ]
       }
     },
+    "/closeness/for-me": {
+      "get": {
+        "operationId": "get_closeness_for_me",
+        "tags": [
+          "closeness"
+        ],
+        "summary": "GET /closeness/for-me",
+        "description": ", and OWN-SCOPED — your own graph, never someone else's. Reading another builder's graph would expose who THEY are close to, which is a fact about third parties they did not consent to share.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/closeness.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetClosenessForMeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/closeness/weights": {
+      "get": {
+        "operationId": "get_closeness_weights",
+        "tags": [
+          "closeness"
+        ],
+        "summary": "GET /closeness/weights",
+        "description": "the MODEL is not private, and publishing it is the whole point of the weights being data. It describes how the system scores people; a builder ranked by it is entitled to read it.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/closeness.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetClosenessWeightsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/closeness/with/{builderId}": {
+      "get": {
+        "operationId": "get_closeness_with_builderId",
+        "tags": [
+          "closeness"
+        ],
+        "summary": "GET /closeness/with/:builderId",
+        "description": "One pair — \"why am I close to THEM\", asked directly rather than by paging the graph. Always relative to the CALLER: the pair is (you, them). rank: any-builder.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/closeness.js",
+        "parameters": [
+          {
+            "name": "builderId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `builderId`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetClosenessWithBuilderIdResponse"
+                }
+              }
+            }
+          },
+          "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",
@@ -12092,6 +12228,194 @@
         "security": []
       }
     },
+    "/task-recommendations": {
+      "post": {
+        "operationId": "post_task_recommendations",
+        "tags": [
+          "task-recommendations"
+        ],
+        "summary": "POST /task-recommendations",
+        "description": "recommending is not a privileged act. It grants the recipient nothing they did not already have (the task was claimable by them or it was not), so gating it by rank would only stop newcomers from pointing at something useful.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/recommendations.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostTaskRecommendationsRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostTaskRecommendationsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/task-recommendations/for-me": {
+      "get": {
+        "operationId": "get_task_recommendations_for_me",
+        "tags": [
+          "task-recommendations"
+        ],
+        "summary": "GET /task-recommendations/for-me",
+        "description": "you only ever see what is addressed to you. NOTE WHAT THIS RESPONSE DOES NOT CONTAIN: any signal that the recipient now holds the task. It carries the task's own status so the recipient can judge, and that is all. Claiming is a separate, deliberate act on their part.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/recommendations.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetTaskRecommendationsForMeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/task-recommendations/mine": {
+      "get": {
+        "operationId": "get_task_recommendations_mine",
+        "tags": [
+          "task-recommendations"
+        ],
+        "summary": "GET /task-recommendations/mine",
+        "description": "what I recommended, and what became of it. Unfiltered by default: a declined recommendation stays readable, which is the criterion's \"the recommendation and its author are readable afterwards\".\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/recommendations.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetTaskRecommendationsMineResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/task-recommendations/{id}": {
+      "patch": {
+        "operationId": "patch_task_recommendations_id",
+        "tags": [
+          "task-recommendations"
+        ],
+        "summary": "PATCH /task-recommendations/:id",
+        "description": "Decline. Costs nothing, and this route is where that is visible: it flips a status and returns the row. No karma call, no counter, no notification to the sender beyond the row itself turning up in their own list. rank: any-builder — ownership is enforced in the UPDATE's WHERE, not by rank.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/recommendations.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/PatchTaskRecommendationsIdRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PatchTaskRecommendationsIdResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/task-visuals/{name}": {
       "get": {
         "operationId": "get_task_visuals_name",
@@ -13431,6 +13755,58 @@
         ]
       }
     },
+    "/tasks/{id}/recommendations": {
+      "get": {
+        "operationId": "get_tasks_id_recommendations",
+        "tags": [
+          "tasks"
+        ],
+        "summary": "GET /tasks/:id/recommendations",
+        "description": "The per-task audit read: who recommended this task, to whom, and why. rank: any-builder, and deliberately NOT scoped to the two parties. The criterion's argument for a ledger is that an untraced recommendation is indistinguishable from a task quietly changing hands — a trace only the two people involved can read does not answer that. Tasks are already visible to every builder, and a recommendation says nothing more private than \"this person thought that person should look at this\".\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/recommendations.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/GetTasksIdRecommendationsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/tasks/{id}/ship": {
       "post": {
         "operationId": "post_tasks_id_ship",
@@ -14376,6 +14752,41 @@
           "stale_hours"
         ]
       },
+      "GetClosenessForMeResponse": {
+        "type": "object",
+        "properties": {
+          "closeness": {},
+          "count": {}
+        },
+        "required": [
+          "closeness",
+          "count"
+        ]
+      },
+      "GetClosenessWeightsResponse": {
+        "type": "object",
+        "properties": {
+          "weights": {},
+          "window_days": {},
+          "note": {}
+        },
+        "required": [
+          "weights",
+          "window_days",
+          "note"
+        ]
+      },
+      "GetClosenessWithBuilderIdResponse": {
+        "type": "object",
+        "properties": {
+          "closeness": {},
+          "why": {}
+        },
+        "required": [
+          "closeness",
+          "why"
+        ]
+      },
       "GetDiscordChannelsPlanResponse": {
         "type": "object",
         "properties": {
@@ -15307,6 +15718,28 @@
           "public_key_b64"
         ]
       },
+      "GetTaskRecommendationsForMeResponse": {
+        "type": "object",
+        "properties": {
+          "recommendations": {},
+          "count": {}
+        },
+        "required": [
+          "recommendations",
+          "count"
+        ]
+      },
+      "GetTaskRecommendationsMineResponse": {
+        "type": "object",
+        "properties": {
+          "recommendations": {},
+          "count": {}
+        },
+        "required": [
+          "recommendations",
+          "count"
+        ]
+      },
       "GetTasksClaimableResponse": {
         "type": "object",
         "properties": {
@@ -15338,6 +15771,17 @@
           "dependents"
         ]
       },
+      "GetTasksIdRecommendationsResponse": {
+        "type": "object",
+        "properties": {
+          "recommendations": {},
+          "count": {}
+        },
+        "required": [
+          "recommendations",
+          "count"
+        ]
+      },
       "GetTasksNewcomerFloorResponse": {
         "type": "object",
         "properties": {
@@ -15925,6 +16369,35 @@
           "push"
         ]
       },
+      "PatchTaskRecommendationsIdRequest": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "declined",
+              "withdrawn"
+            ]
+          }
+        },
+        "required": [
+          "status"
+        ],
+        "additionalProperties": false
+      },
+      "PatchTaskRecommendationsIdResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "recommendation": {}
+        },
+        "required": [
+          "ok",
+          "recommendation"
+        ]
+      },
       "PatchTasksIdRequest": {
         "type": "object",
         "properties": {
@@ -18777,6 +19250,42 @@
           "avatar_url"
         ]
       },
+      "PostTaskRecommendationsRequest": {
+        "type": "object",
+        "properties": {
+          "task_id": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "recommended_to": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "task_id",
+          "recommended_to",
+          "reason"
+        ],
+        "additionalProperties": false
+      },
+      "PostTaskRecommendationsResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "recommendation": {}
+        },
+        "required": [
+          "ok",
+          "recommendation"
+        ]
+      },
       "PostTasksIdAbandonRequest": {
         "type": "object",
         "properties": {
@@ -19452,9 +19961,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 307,
-  "x-schema-count": 343,
+  "x-endpoint-count": 315,
+  "x-schema-count": 353,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 229,
+  "x-response-schemas": 237,
   "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. 307 endpoints across 50 route files.
+> **Generated from the live route files** — the route file is authoritative. 315 endpoints across 52 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`.
@@ -143,6 +143,14 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/claims/batch/release` | `any-builder` | `claim_ids`, `force` | Bulk release (task 1758) — the batch twin of resolve(outcome='abandoned'). |
 | POST | `/api/bongos/claims/batch/validate` | `any-builder` | `task_ids` | Dry-run validate (task 1758) — read-only twin of claimTasksBatch's pre-flight checks. |
 
+## `closeness` (3)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/closeness/for-me` | `any-builder` | — | , and OWN-SCOPED — your own graph, never someone else's. |
+| 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. |
+
 ## `copy-desk` (4)
 
 | Method | Path | Rank | Body | Description |
@@ -507,13 +515,22 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/sso/pubkey` | `public` | — | GET /sso/pubkey — the hub's Ed25519 assertion-verification key (public). |
 | POST | `/api/bongos/sso/token` | `public` | `client_id`, `client_secret`, `code`, `redirect_uri` | POST /sso/token — server-to-server code redemption. |
 
+## `task-recommendations` (4)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/task-recommendations` | `any-builder` | `task_id`, `recommended_to`, `reason` | recommending is not a privileged act. |
+| PATCH | `/api/bongos/task-recommendations/:id` | `any-builder` | `status` | Decline. |
+| GET | `/api/bongos/task-recommendations/for-me` | `any-builder` | — | you only ever see what is addressed to you. |
+| GET | `/api/bongos/task-recommendations/mine` | `any-builder` | — | what I recommended, and what became of it. |
+
 ## `task-visuals` (1)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/task-visuals/:name` | `public` | — | the WIDEST path this route can take, declared honestly. |
 
-## `tasks` (29)
+## `tasks` (30)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -537,6 +554,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/tasks/:id/promote` | `metic+archon` | — | backlog→ready promotion; scope mutation; ADR 0090 (was archon). |
 | POST | `/api/bongos/tasks/:id/publish-branch` | `any-builder` | `branch`, `head_sha`, `bundle_b64`, `value_summary` |  |
 | GET | `/api/bongos/tasks/:id/publish-status` | `any-builder` | — | GET /tasks/:id/publish-status?branch=<branch> — poll the PR + prod-deploy state for a server-mediated publish so ship.js can confirm the … |
+| GET | `/api/bongos/tasks/:id/recommendations` | `any-builder` | — | The per-task audit read: who recommended this task, to whom, and why. |
 | POST | `/api/bongos/tasks/:id/ship` | `any-builder` | validated | confirmed → shipped. |
 | POST | `/api/bongos/tasks/:id/visual` | `any-builder` | `image_b64`, `content_type`, `alt` | POST /tasks/:id/visual — attach (or replace) this task's ship-time visual. |
 | DELETE | `/api/bongos/tasks/:id/visual` | `any-builder` | — | DELETE /tasks/:id/visual — remove it again. |

package/modules/builder-settings/builder-needs.js

@@ -121,7 +121,34 @@ function helpRequestsNeed(ctx) {
 
 // The registry. To add a future input the system needs from a builder, append a
 // pure (ctx) => need|null function here — every renderer picks it up for free.
-const NEEDS = [artKeyNeed, helpRequestsNeed];
+// Open task RECOMMENDATIONS waiting on this builder (task 1003173 / C03, goal
+// 1000075; criterion collab-pass-a-task). Sibling of helpRequestsNeed above, and
+// here for the same reason C01's grader round put that one here: a recommendation
+// nobody surfaces is merely stored, and the criterion's whole argument is that a
+// recommendation must be a visible, traceable judgement rather than a task
+// quietly changing hands.
+//
+// 'info', NOT a demand, and the message says so. A recommendation grants the
+// recipient nothing and obliges them to nothing — they still claim it themselves
+// if they want it, and declining costs nothing (ADR 0187 §3). Wording that
+// pressured the reader would BE the penalty the decision forbids.
+function taskRecommendationsNeed(ctx) {
+  const n = Number(ctx.openTaskRecommendations) || 0;
+  if (n <= 0) return null;
+  const subject = n === 1 ? 'A task' : `${n} tasks`;
+  const verb = n === 1 ? 'was' : 'were';
+  return {
+    id: 'task_recommendations',
+    title: n === 1 ? 'Someone recommended a task to you' : 'Tasks were recommended to you',
+    what: 'Another builder thought you should look at a task, and said why. It is a suggestion, not an assignment.',
+    state: 'action_needed',
+    severity: 'info',
+    message: `${subject} ${verb} recommended to you. Nothing has been assigned — you would still claim it yourself, and declining costs nothing.`,
+    action: { label: n === 1 ? 'See the recommendation' : 'See the recommendations', href: '/#/collab' },
+  };
+}
+
+const NEEDS = [artKeyNeed, helpRequestsNeed, taskRecommendationsNeed];
 
 // ---- founding grace (task 1002739 / direction §5.6, idea 1000701) -----------
 //
@@ -199,7 +226,7 @@ module.exports = {
   computeNeeds,
   // exported for tests / direct reuse
   artKeyNeed,
-  helpRequestsNeed,
+  helpRequestsNeed, taskRecommendationsNeed,
   foundingGraceActive,
   FOUNDING_GRACE_DAYS,
   SETTINGS_PATH,