@bongos/core 1.19.357 → 1.19.359

package/docs/api/openapi.json

@@ -205,6 +205,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`."
@@ -12092,6 +12096,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 +13623,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",
@@ -15307,6 +15551,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 +15604,17 @@
           "dependents"
         ]
       },
+      "GetTasksIdRecommendationsResponse": {
+        "type": "object",
+        "properties": {
+          "recommendations": {},
+          "count": {}
+        },
+        "required": [
+          "recommendations",
+          "count"
+        ]
+      },
       "GetTasksNewcomerFloorResponse": {
         "type": "object",
         "properties": {
@@ -15925,6 +16202,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 +19083,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 +19794,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 307,
-  "x-schema-count": 343,
+  "x-endpoint-count": 312,
+  "x-schema-count": 350,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 229,
+  "x-response-schemas": 234,
   "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. 312 endpoints across 51 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`.
@@ -507,13 +507,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 +546,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. |