@bongos/core 1.24.13 → 1.24.15

package/docs/api/openapi.json

@@ -245,6 +245,10 @@
       "name": "pay-terms",
       "description": "Endpoints under `/api/bongos/pay-terms`."
     },
+    {
+      "name": "pay-type-gates",
+      "description": "Endpoints under `/api/bongos/pay-type-gates`."
+    },
     {
       "name": "payouts",
       "description": "Endpoints under `/api/bongos/payouts`."
@@ -257,6 +261,10 @@
       "name": "project",
       "description": "Endpoints under `/api/bongos/project`."
     },
+    {
+      "name": "project-account",
+      "description": "Endpoints under `/api/bongos/project-account`."
+    },
     {
       "name": "project-settings",
       "description": "Endpoints under `/api/bongos/project-settings`."
@@ -1637,7 +1645,7 @@
           "ai-studio"
         ],
         "summary": "POST /ai-studio/uploads",
-        "description": "One file per call, so a request body stays small; the global 64 KB parser skips this path (src/bongos/routes.js) and this parser takes it.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "description": "One file per call, so a request body stays small; the global 64 KB parser skips this path (src/bongos/routes.js) and this parser takes it. Not adults-gated on purpose: an upload is stored here and reaches no AI company until a request sends it, and /ai-studio/requests is gated.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
         "x-source": "modules/ai-studio/routes/ai-studio.js",
         "requestBody": {
@@ -14670,6 +14678,55 @@
         ]
       }
     },
+    "/me/checkout-freshness": {
+      "patch": {
+        "operationId": "patch_me_checkout_freshness",
+        "tags": [
+          "me"
+        ],
+        "summary": "PATCH /me/checkout-freshness",
+        "description": "How far behind this builder's local project folder is (task 1005021, checkout-freshness.js). Written by their own session start; read back by GET /me, which tells the person (and their agent) when the folder could not update itself. Body: { behind, branch, reason }. rank: any-builder — a builder's own report about their own computer; same posture as /me/core-move-seen.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/builder-settings/routes/settings.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PatchMeCheckoutFreshnessRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PatchMeCheckoutFreshnessResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/me/core-move-seen": {
       "patch": {
         "operationId": "patch_me_core_move_seen",
@@ -19280,6 +19337,119 @@
         ]
       }
     },
+    "/pay-type-gates": {
+      "get": {
+        "operationId": "get_pay_type_gates",
+        "tags": [
+          "pay-type-gates"
+        ],
+        "summary": "GET /pay-type-gates",
+        "description": "for met/missing (the same pay information `GET /pay-terms` shows, no person's money); the evidence references and who cleared each requirement are the owner's records, so they come back for an archon only.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/pay-type-gates.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetPayTypeGatesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/pay-type-gates/{payType}/{requirement}": {
+      "put": {
+        "operationId": "put_pay_type_gates_payType_requirement",
+        "tags": [
+          "pay-type-gates"
+        ],
+        "summary": "PUT /pay-type-gates/:payType/:requirement",
+        "description": ".approve (archon floor). Whether a pay type is legal for this project is the owner's call, often with counsel, and it is the same authority that approves payouts — no new atom is minted for it (ADR 0016: enforced here, on the server).\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `payout.approve` (all required).",
+        "x-rank": "archon",
+        "x-source": "modules/lifecycle/routes/pay-type-gates.js",
+        "x-permissions": [
+          "payout.approve"
+        ],
+        "parameters": [
+          {
+            "name": "payType",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `payType`."
+          },
+          {
+            "name": "requirement",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `requirement`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutPayTypeGatesPayTypeRequirementRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PutPayTypeGatesPayTypeRequirementResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/payouts/age-records": {
       "post": {
         "operationId": "post_payouts_age_records",
@@ -20176,6 +20346,40 @@
         "security": []
       }
     },
+    "/project-account": {
+      "get": {
+        "operationId": "get_project_account",
+        "tags": [
+          "project-account"
+        ],
+        "summary": "GET /project-account",
+        "description": ".approve (archon floor) — the owner. The account's balance and who was paid what is the project's own money, so only the payout authority reads it (ADR 0016: enforced here, server-side).\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `payout.approve` (all required).",
+        "x-rank": "archon",
+        "x-source": "modules/economy/routes/project-account.js",
+        "x-permissions": [
+          "payout.approve"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/project-settings": {
       "get": {
         "operationId": "get_project_settings",
@@ -29501,6 +29705,69 @@
         ]
       }
     },
+    "/tasks/{id}/short-name": {
+      "patch": {
+        "operationId": "patch_tasks_id_short_name",
+        "tags": [
+          "tasks"
+        ],
+        "summary": "PATCH /tasks/:id/short-name",
+        "description": "PATCH /tasks/:id/short-name { short_name } — rename a task's 2-3 word name, the one sessions print as \"task N - <name>\" (task 1004958). Its own route because the owner's rule is that the task's AUTHOR may change it, and PATCH /tasks/:id is gated on task.edit, which an author below Metic does not hold. The name is normalised to task-name.js's alphabet (three lowercase words at most), so what reaches the startup notes is a topic and nothing else; the table CHECK holds the same shape. rank: any-builder, narrowed in the handler — the task's author, or a Metic or Archon.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/task-write-routes.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/PatchTasksIdShortNameRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PatchTasksIdShortNameResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/tasks/{id}/visual": {
       "post": {
         "operationId": "post_tasks_id_visual",
@@ -30926,11 +31193,15 @@
           "ok": {
             "type": "boolean"
           },
-          "module": {}
+          "module": {},
+          "terms": {},
+          "adult": {}
         },
         "required": [
           "ok",
-          "module"
+          "module",
+          "terms",
+          "adult"
         ]
       },
       "GetAiStudioTopupQuoteResponse": {
@@ -32280,6 +32551,15 @@
           "pay_terms"
         ]
       },
+      "GetPayTypeGatesResponse": {
+        "type": "object",
+        "properties": {
+          "gates": {}
+        },
+        "required": [
+          "gates"
+        ]
+      },
       "GetPayoutsApprovalsResponse": {
         "type": "object",
         "properties": {
@@ -33587,6 +33867,40 @@
         },
         "additionalProperties": false
       },
+      "PatchMeCheckoutFreshnessRequest": {
+        "type": "object",
+        "properties": {
+          "behind": {
+            "type": "number"
+          },
+          "branch": {
+            "type": "string",
+            "maxLength": 120
+          },
+          "reason": {
+            "type": "string",
+            "maxLength": 40
+          }
+        },
+        "required": [
+          "behind",
+          "reason"
+        ],
+        "additionalProperties": false
+      },
+      "PatchMeCheckoutFreshnessResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "checkout": {}
+        },
+        "required": [
+          "ok",
+          "checkout"
+        ]
+      },
       "PatchMeCoreMoveSeenRequest": {
         "type": "object",
         "properties": {
@@ -34282,6 +34596,28 @@
         },
         "additionalProperties": false
       },
+      "PatchTasksIdShortNameRequest": {
+        "type": "object",
+        "properties": {
+          "short_name": {
+            "type": "string",
+            "maxLength": 80
+          }
+        },
+        "required": [
+          "short_name"
+        ],
+        "additionalProperties": false
+      },
+      "PatchTasksIdShortNameResponse": {
+        "type": "object",
+        "properties": {
+          "task": {}
+        },
+        "required": [
+          "task"
+        ]
+      },
       "PostAccessRequestsInviteRequest": {
         "type": "object",
         "properties": {
@@ -37420,6 +37756,11 @@
           "log_entry_id": {
             "$ref": "#/components/schemas/StringifiableId"
           },
+          "takeaway": {
+            "type": "string",
+            "maxLength": 2000
+          },
+          "wrong": {},
           "scout": {
             "type": "string"
           },
@@ -41013,6 +41354,28 @@
         ],
         "additionalProperties": false
       },
+      "PutPayTypeGatesPayTypeRequirementRequest": {
+        "type": "object",
+        "properties": {
+          "state": {},
+          "evidence_ref": {},
+          "acknowledged": {}
+        },
+        "additionalProperties": false
+      },
+      "PutPayTypeGatesPayTypeRequirementResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "gate": {}
+        },
+        "required": [
+          "ok",
+          "gate"
+        ]
+      },
       "PutProvisioningInstancesIdLogoRequest": {
         "type": "object",
         "properties": {
@@ -41279,9 +41642,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 652,
-  "x-schema-count": 698,
+  "x-endpoint-count": 657,
+  "x-schema-count": 705,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 447,
+  "x-response-schemas": 451,
   "x-generated-by": "scripts/bongos/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. 652 endpoints across 109 route files.
+> **Generated from the live route files** — the route file is authoritative. 657 endpoints across 111 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/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -528,7 +528,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/market-watch/ask/answer` | `any-builder` | `week_of`, `picks`, `names`, `nothing`, `builder_id` | a member answers for themselves only (isMember in gate()). |
 | GET | `/api/bongos/market-watch/home` | `any-builder` | — | every member reads the desk. |
 | GET | `/api/bongos/market-watch/items/:id` | `any-builder` | — | every member reads an item's case file. |
-| POST | `/api/bongos/market-watch/proposals` | `any-builder` | `kind`, `reason`, `item_id`, `dimension`, `value`, `url`, `log_entry_id`, `scout`, `name` | every member may propose; the government decides (task 1004941). |
+| POST | `/api/bongos/market-watch/proposals` | `any-builder` | `kind`, `reason`, `item_id`, `dimension`, `value`, `url`, `log_entry_id`, `takeaway`, `wrong`, `scout`, `name` | every member may propose; the government decides (task 1004941). |
 | POST | `/api/bongos/market-watch/proposals/:id/decide` | `any-builder` | `decision` | THE OWNER'S DECISION. |
 | POST | `/api/bongos/market-watch/proposals/:id/vote` | `metic+archon` | — | PUT TO A VOTE. |
 | GET | `/api/bongos/market-watch/rules` | `any-builder` | — | every member reads the rules (the task); the read grants nothing. |
@@ -538,13 +538,14 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | PUT | `/api/bongos/market-watch/settings/key` | `metic+archon` | `key` |  |
 | DELETE | `/api/bongos/market-watch/settings/key` | `metic+archon` | — |  |
 
-## `me` (55)
+## `me` (56)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/me` | `any-builder` | — | PMS-V2 task 188: response now also carries `unlocked` (server-joined achievement metadata) + `locked_with_progress` (server-computed huma… |
 | GET | `/api/bongos/me/achievements` | `any-builder` | — | The builder's unlocked achievements (joined to achievement metadata). |
 | POST | `/api/bongos/me/anthropic-link` | `any-builder` | `anthropic_email`, `anthropic_user_id` | V3.R10 (task 235), criterion C3 — link the authed builder's Anthropic account. |
+| PATCH | `/api/bongos/me/checkout-freshness` | `any-builder` | `behind`, `branch`, `reason` | How far behind this builder's local project folder is (task 1005021, checkout-freshness.js). |
 | PATCH | `/api/bongos/me/core-move-seen` | `any-builder` | `id` | The core move this builder has been told about (task 1004731, core-move-seen.js): closing the hall's "Upgraded to core X" notice stores t… |
 | GET | `/api/bongos/me/credits` | `any-builder` | — | GET /me/credits — the caller's own ledger. |
 | GET | `/api/bongos/me/cross-project` | `any-builder` | — | the caller's OWN cross-project record + privacy flags (own data). |
@@ -700,6 +701,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 |---|---|---|---|---|
 | GET | `/api/bongos/pay-terms` | `any-builder` | — | GET /pay-terms?task_ids=1,2,3 — what each task pays, in the project's words (task 1004990, ADR 0385 D3), for a list of tasks in one read:… |
 
+## `pay-type-gates` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/pay-type-gates` | `any-builder` | — | for met/missing (the same pay information `GET /pay-terms` shows, no person's money); the evidence references and who cleared each requir… |
+| PUT | `/api/bongos/pay-type-gates/:payType/:requirement` | `archon` | `state`, `evidence_ref`, `acknowledged` | .approve (archon floor). |
+
 ## `payouts` (16)
 
 | Method | Path | Rank | Body | Description |
@@ -733,6 +741,12 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 |---|---|---|---|---|
 | GET | `/api/bongos/project/manage-link` | `archon` | — | GET /project/manage-link — the hub's page for THIS project, where its owner takes it offline or disconnects it (task 1004570). |
 
+## `project-account` (1)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/project-account` | `archon` | — | .approve (archon floor) — the owner. |
+
 ## `project-settings` (8)
 
 | Method | Path | Rank | Body | Description |
@@ -1000,7 +1014,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 |---|---|---|---|---|
 | GET | `/api/bongos/task-visuals/:name` | `public` | — | the WIDEST path this route can take, declared honestly. |
 
-## `tasks` (36)
+## `tasks` (37)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -1027,6 +1041,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | 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. |
+| PATCH | `/api/bongos/tasks/:id/short-name` | `any-builder` | `short_name` | PATCH /tasks/:id/short-name { short_name } — rename a task's 2-3 word name, the one sessions print as "task N - <name>" (task 1004958). |
 | 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. |
 | GET | `/api/bongos/tasks/:id/visuals` | `any-builder` | — | GET /tasks/:id/visuals — the task's named visuals. |

package/docs/architecture.md

@@ -110,6 +110,9 @@ 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)
+  + short_name text (mig core_289, task 1004958) -- 1-3 lowercase words a session writes as "task N - <name>";
+    derived from the title by modules/lifecycle/task-name.js on create, backfilled hourly by the
+    publish-reconciler, renamed by the author via PATCH /tasks/:id/short-name. CHECK holds the safe shape.
   + needs text[] NOT NULL DEFAULT '{}' (mig core_285, task 1004950 / ADR 0395) -- what the task needs beyond the build
     loop: ⊆ {owner, server}. The recommend lists show it only to a viewer holding those capabilities;
     a claim refuses only 'server' without the grant. Visibility elsewhere is unchanged.
@@ -256,6 +259,9 @@ lifecycle_pay_term_sets(id, task_id NULL = the project's standing terms, set_by,
 lifecycle_pay_terms(id, set_id, position, pay_type, amount text, unit, note)
               -- task 1004990 (module lifecycle, lifecycle_018): what a task pays, in the project's words; append-only
               -- history of whole sets (newest current), records only, no default amount.
+lifecycle_pay_type_gates(id, pay_type, requirement, state cleared|revoked, evidence_ref, decided_by, decided_at)
+              -- task 1004991 (module lifecycle, lifecycle_019): ADR 0385's pay-type gates; append-only,
+              -- newest row per requirement is current; a pay term is refused until its type's gate is cleared; no eu_labour row exists.
 store_module_prices(id, module_key, price_cents, price_credits, set_by, set_at)
               -- history; newest row per module is current. Cash only since core_287 (task 1004989):
               -- price_credits is historical, a credit-only newest row reads "price coming". 0 cents = free.