@bongos/core 1.19.349 → 1.19.351

package/docs/api/openapi.json

@@ -205,6 +205,10 @@
       "name": "sso",
       "description": "Endpoints under `/api/bongos/sso`."
     },
+    {
+      "name": "task-visuals",
+      "description": "Endpoints under `/api/bongos/task-visuals`."
+    },
     {
       "name": "tasks",
       "description": "Endpoints under `/api/bongos/tasks`."
@@ -12088,6 +12092,41 @@
         "security": []
       }
     },
+    "/task-visuals/{name}": {
+      "get": {
+        "operationId": "get_task_visuals_name",
+        "tags": [
+          "task-visuals"
+        ],
+        "summary": "GET /task-visuals/:name",
+        "description": "the WIDEST path this route can take, declared honestly. It is reached only for already-public work (see isPubliclyViewable); every other request falls through to auth.requireBuilder INSIDE the handler, because the decision needs the task the filename names. Read the file header before changing this — a mounted middleware cannot express a per-row audience. GET /api/bongos/task-visuals/:name — stream one stored visual.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/lifecycle/routes/visuals.js",
+        "parameters": [
+          {
+            "name": "name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `name`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": []
+      }
+    },
     "/tasks": {
       "get": {
         "operationId": "get_tasks",
@@ -13456,6 +13495,119 @@
         ]
       }
     },
+    "/tasks/{id}/visual": {
+      "post": {
+        "operationId": "post_tasks_id_visual",
+        "tags": [
+          "tasks"
+        ],
+        "summary": "POST /tasks/:id/visual",
+        "description": "POST /tasks/:id/visual — attach (or replace) this task's ship-time visual.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/visuals.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/PostTasksIdVisualRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostTasksIdVisualResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "delete": {
+        "operationId": "delete_tasks_id_visual",
+        "tags": [
+          "tasks"
+        ],
+        "summary": "DELETE /tasks/:id/visual",
+        "description": "DELETE /tasks/:id/visual — remove it again. The counterpart to \"always optional\": a builder who attached the wrong screenshot must be able to take it back, and an image is not prose (the write-once rule of task 1003102 guards a written CLAIM, not the picture beside it). Same ownership gate as the POST. Idempotent — removing an absent visual is a success.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/visuals.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/DeleteTasksIdVisualResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/tasks/{id}/vote": {
       "post": {
         "operationId": "post_tasks_id_vote",
@@ -13945,6 +14097,19 @@
           "removed"
         ]
       },
+      "DeleteTasksIdVisualResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "visual_url": {}
+        },
+        "required": [
+          "ok",
+          "visual_url"
+        ]
+      },
       "ErrorEnvelope": {
         "type": "object",
         "required": [
@@ -18828,6 +18993,46 @@
           "task"
         ]
       },
+      "PostTasksIdVisualRequest": {
+        "type": "object",
+        "properties": {
+          "image_b64": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 7340032
+          },
+          "content_type": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          },
+          "alt": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "image_b64",
+          "content_type"
+        ],
+        "additionalProperties": false
+      },
+      "PostTasksIdVisualResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "visual_url": {},
+          "visual_alt": {},
+          "bytes": {}
+        },
+        "required": [
+          "ok",
+          "visual_url",
+          "visual_alt",
+          "bytes"
+        ]
+      },
       "PostTasksIdVoteRequest": {
         "type": "object",
         "properties": {
@@ -19243,9 +19448,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 304,
-  "x-schema-count": 340,
+  "x-endpoint-count": 307,
+  "x-schema-count": 343,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 227,
+  "x-response-schemas": 229,
   "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. 304 endpoints across 49 route files.
+> **Generated from the live route files** — the route file is authoritative. 307 endpoints across 50 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,7 +507,13 @@ 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. |
 
-## `tasks` (27)
+## `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)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -532,6 +538,8 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | 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 … |
 | 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. |
 | POST | `/api/bongos/tasks/:id/vote` | `metic+archon` | `vote` | POST /tasks/:id/vote { vote: 1 \| -1 \| 0 } — cast/change/clear a peer vote on a confirmed/shipped task. |
 | GET | `/api/bongos/tasks/claimable` | `any-builder` | — | NOTE: /tasks/claimable must come BEFORE /tasks/:id or Express will route 'claimable' to the :id param. |
 | GET | `/api/bongos/tasks/newcomer-floor` | `any-builder` | — | GET /tasks/newcomer-floor — supply gauge for the newcomer queue (task 614). |

package/docs/architecture.md

@@ -106,6 +106,11 @@ versions(id PK 'V1'|'PMS-V1'..., name, track, status, scope_doc_path, ...)  -- t
 tasks(id, version_id, title, description, status, touches text[], est_minutes, est_cost_usd,
       manual_degree, priority, automation_tag, credits_reward, source, source_ref,
       promoted_at, shipped_at, shipped_by, value_summary, created_at, updated_at)
+  + visual_url, visual_alt (mig core_223, task 1003109) -- the OPTIONAL ship-time VISUAL: a
+    screenshot / before-after / diagram, stored on disk under var/task-visuals/ and served by
+    GET /api/bongos/task-visuals/:name. It is value_summary's claim in another medium, so it
+    inherits that summary's audience (public only for shipped|confirmed, and never for a
+    security_sensitive task); never required, and nothing on the ship path blocks on it.
   status ∈ {backlog, ready, active, blocked, completed, confirmed, shipped, abandoned}
     completed = builder declared done (Phase 5 / 2026-05-10)
     confirmed = scanner+smoke passed AND quality grader >= threshold; verified, NOT yet paid
@@ -222,7 +227,7 @@ Bongos views: `claimable_tasks` (rebuilt in 006 to use SELECT t.*; rebuilt again
 - Per-builder "needs" + own Gemini key ([ADR 0073](adr/<redacted>.md), [#1013](https://example.com/builders#/task/1013)): `GET /me` now also carries `needs` ({items, action_needed_count} — the consistent "the system needs an input from you" signal; `modules/builder-settings/builder-needs.js` is the SSOT — carved out in BV1.R80, resolved by `GET /me` via the `builder-settings` kernel port — rendered by the hall Standing card + the CLI `printNeedsNudge`). The own-key (pragmatic BYOK) endpoints, all own-scoped: `GET /me/art-key/own` (masked meta — last4 only), `PUT /me/art-key/own` (validate-on-save via a Google list-models call → encrypt with `src/bongos/secret-box.js` → store; `503 storage_not_configured` until `BUILDER_SECRET_KEY` is set, `422 invalid_key` on a bad key), `DELETE /me/art-key/own`. The existing `GET /me/art-key` (shared-key box-sync delivery) is extended to also deliver the decrypted own key, which `scripts/gds/fetch-art-key.js` syncs into the local `gemini_api_key` slot (own key wins in the `gen_api.py` cascade).
 - Builder memory (ADR 0024 cloneable memory + ADR 0026 BFG). Self-scoped (owner is always `req.builder.id`, never input): `POST /memory/sync` (push own memory; own 64 MB parser, vs the global 64 KB), `GET /memory/files`, `GET /memory/file`, `DELETE /memory/file` (the BFG delete affordance, 6C.2). Cross-builder (input-owner) endpoints — all privileged + audit-logged fail-closed: `GET /memory/builders/:id/files`+`/file` (**archon forensic** read), `GET /memory/bfg/builders/:id/files`+`/file` (**BFG-principal only**, 6B.1 read), and the one cross-builder WRITE `POST /memory/builders/:id/bfg-write` (**BFG-principal only**, kill-switched `BFG_WRITE_ENABLED` default-OFF, namespaced `bfg/`, attributed `author: BFG`, write+audit in one tx — dreams + transparent corrections, 6C.1/6C.2).
 - Session corpus (BFG evaluator — 6D, ADR 0027): `POST /sessions` (upload own session digest; own **4 MB** json parser — capped, vs the global 64 KB — and the digest is per-turn metadata + short scrubbed snippets, never raw transcript content), `GET /sessions/mine` (self-serve), `GET /sessions/search` (cross-builder, **archon-gated** — the BFG-principal stand-in; the principal now exists (6C.1) and the *memory* cross-reads moved to it (6B.1), but these *session* reads still use the archon stand-in pending a retrofit, + audit_log row per read), `GET /sessions/:id` (own self-serve; cross-builder needs archon + audit; non-owner → 404).
-- Public (no auth, `Cache-Control: max-age=60`): `/public/versions`, `/public/progress`, `/public/cost-summary`, `/public/recent-shipped`, `/public/leaderboard`, `/public/grades[?days=N]`, `/public/tasks/:id` ([#604](https://example.com/builders#/task/604) — single-task resolver for `#NNN` doc deep-links; `title`/`value_summary` returned **only** for `shipped`|`confirmed` work and withheld for in-flight tasks so unshipped/security task names can't leak; the status dashboard renders it at `#/task/:id`), `/public/ref-ids` ([#653](https://example.com/builders#/task/653) — `{tasks:[ids]}`, ids only, token-free; the doc-ref linkifier + its CI gate consult it to decide which bare `#NNN` are real task refs). These power `status.example.com`.
+- Public (no auth, `Cache-Control: max-age=60`): `/public/versions`, `/public/progress`, `/public/cost-summary`, `/public/recent-shipped`, `/public/leaderboard`, `/public/grades[?days=N]`, `/public/tasks/:id` ([#604](https://example.com/builders#/task/604) — single-task resolver for `#NNN` doc deep-links; `title`/`value_summary`/`visual_url` returned **only** for `shipped`|`confirmed` work and withheld for in-flight tasks so unshipped/security task names can't leak; the status dashboard renders it at `#/task/:id`), `/public/ref-ids` ([#653](https://example.com/builders#/task/653) — `{tasks:[ids]}`, ids only, token-free; the doc-ref linkifier + its CI gate consult it to decide which bare `#NNN` are real task refs). These power `status.example.com`.
 - Live updates (Server-Sent Events — [#569](https://example.com/builders#/task/569), [ADR 0030](adr/<redacted>.md) signal layer, [ADR 0069](adr/<redacted>.md) transport): an SSE stream at `GET /api/gds/live` ([`src/bongos/routes/live.js`](../src/bongos/routes/live.js)), mounted in both entrypoints (`server.js` + `src/platform-server.js`) so the hall stays live on a game-less boot. This **superseded** the original broadcast-only Colyseus `builders_hall` room (R55 / task 1194 — the room and `src/rooms/BuildersHallRoom.js` were deleted because a Bongos-only instance has no Colyseus in the process). The change-signal layer is **unchanged**: a statement-level Postgres `NOTIFY` trigger (migration 066) on `tasks`/`claims`/`builders`/`builder_onboarding_state`/`credit_log`/`karma_log` fires a `gds_live` notification on every write (incl. direct `psql`); one persistent `LISTEN` connection ([`src/bongos/live-channel.js`](../src/bongos/live-channel.js)) relays each notification, and the SSE endpoint emits an **opaque empty nudge** to open hall tabs (the `{table, op}` is kept server-side so internal table names can't leak); the hall re-runs its `loadAll()` (debounced) on any nudge. No row data crosses the channel — access control stays on the per-panel re-fetches.
 
 **Builder ranks & the trust boundary:** moved to its own canonical reference —