@bongos/core 1.24.17 → 1.24.19

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/bongos/package-core.js",
-  "core_version": "1.24.17",
-  "core_contract": "1.24.17",
-  "source_commit": "f7f9e7577824a2b7f8ddb83390d30f54eeec99a1",
+  "core_version": "1.24.19",
+  "core_contract": "1.24.19",
+  "source_commit": "3a975dad2b3edf44743cb62b149866e7604c00bd",
   "source_ref": "HEAD",
-  "built_at": "2026-10-30T21:15:09.518Z",
+  "built_at": "2026-10-30T22:23:46.466Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 632,
     "agent_docs_stubbed": 32,
-    "functional_verbatim": 3798,
+    "functional_verbatim": 3802,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 4463,
-  "tree_sha256": "64b322c3ab81616c72e8aaec297d36306593b337af36498181187eb6aa237648",
+  "file_count": 4467,
+  "tree_sha256": "5c63a13f123c8ddd1571c37e182c79b9b8e6da29707be38187c10bd014fe973c",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -332,12 +332,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "a2e94297703074317b5bceb88168c4d7c2caa79d4619b2dad16445a8eacd85e8"
+      "sha256": "93014d9ba68f4a28c1c23ca623762df541883df9201aad5ffdfd53bee22a0b8d"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "dee0d76f41a5c0449c9bb506287911470a78744370c225247eb80f74a049c7fe"
+      "sha256": "f4ef4c8a0d192356bcbf81a20d793ad368506a245f9b392d4654776fde6539f0"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -347,17 +347,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "4277b81ea894f709e793e1cc2b9080ca65ac2c50e383e994082c2af3a973d467"
+      "sha256": "fafbd80941536f67f85b55c5c250df1ed152398f30ebec2820d431c99676ffb3"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "9108d90c261aebdbb7e5077c0b6bd8eb678ac88d87a7c989bee01643ef0d8037"
+      "sha256": "0e60eb71a4c912b79c2cac3bc338403883667da5c6f871ed811f21dec58d33f9"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "5fe1ff79bf2840651074640d90f9daab7db4455eddf1d2ace559589bc8b74f70"
+      "sha256": "68e375e1c32558fc6e442849bac87b2a82433d333bee255d3aeb0904b9c3f5a1"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -2457,17 +2457,17 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "2eeb56594f7d73ba944f8154c1ad7dad95be7e3b3979298ca84607db0e3d5ee8"
+      "sha256": "57e77a6ffdbe2d558c088fce69e154b3b595b4d6d10b5053ad4ba0043cb00c46"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "2233f1eced2740296b71eb4bbe3539c6c359d757aa9185fb914c5dde9bcb3549"
+      "sha256": "d2e12182597058030c086d3283f652f8d8e2b2e62900c9babed2eba71a97996a"
     },
     {
       "path": "docs/architecture.md",
       "mode": "0000644",
-      "sha256": "9aafe52bde706254b562411ff290104c0aa5dbe8a29e2e3e61fec89b2f3bb24c"
+      "sha256": "ac90efe1fecf89564c59896f69f6131923dfbfdc480f514af9e86802eb1041de"
     },
     {
       "path": "docs/branding-contract.md",
@@ -3002,7 +3002,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "1cd6c004501b1299126de68b3872cc35e7a015bba3362fc50b155d50db3632d9"
+      "sha256": "b4f62fd2bf2938231647a8b0e7b1337e907a34ac8f43e8e6cc0e992a98516980"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4309,6 +4309,11 @@
       "mode": "0000644",
       "sha256": "e7be74430d0d9349b4f9820ff3f202ef03d8c28363fecbaa532c4b9c119e77ec"
     },
+    {
+      "path": "migrations/core_290_builder_payouts.sql",
+      "mode": "0000644",
+      "sha256": "6a8ca9343a4e7d9657baaadb89f42fe76f9354ce739d09ea51569d12e01d8706"
+    },
     {
       "path": "modules/agents/CLAUDE.md",
       "mode": "0000644",
@@ -5242,7 +5247,7 @@
     {
       "path": "modules/economy/module.json",
       "mode": "0000644",
-      "sha256": "b958458c140d149228f8ed40487f3e982466cf79be585691d4f1ffcbef13480d"
+      "sha256": "0c1dd2a3a6f467697bdd72443d05cc3f99ec51b2b4e6d2efdd2e0f57a03cf6c9"
     },
     {
       "path": "modules/economy/policy.js",
@@ -5287,7 +5292,7 @@
     {
       "path": "modules/economy/routes/project-account.js",
       "mode": "0000644",
-      "sha256": "d2a4dd604dd29ad6b0da1d7d8fadba423b6279fd46866512cd0cc4fbb37ad1cb"
+      "sha256": "1e61263bf8b0aaf2ad0e677fb4a57ab2c02888c296de4ca8fc76ccd2c135f235"
     },
     {
       "path": "modules/economy/routes/reward.js",
@@ -11692,12 +11697,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "53297fe3ccc01d30cac66baffc1c3ddc528b91d3bf36d6c626e97477405a6216"
+      "sha256": "e0cedb6d1124be871e92e8fd4f27ef7eeec6ef68df68255895dc7ef6452f9676"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "f8bc5d960904c6118c3ff73f3181bc1ae4761abccba9f1df71719908ccf12a65"
+      "sha256": "dddc98a9784db55a3d203b3625687dde3cfda384fb3cedca3e8856ba1eefa34d"
     },
     {
       "path": "public-docs/index.html",
@@ -11717,7 +11722,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "33bb0faf10fbdb3afcf054c4ab3be42ae54139ee69f7df8b84340a6d3318466b"
+      "sha256": "9cb23ae01651ae9d0f02febefb647e7cce2567bcdef2cb7d2073bbe27114b7b8"
     },
     {
       "path": "scripts/bongos/CLAUDE.md",
@@ -12947,7 +12952,7 @@
     {
       "path": "scripts/bongos/run-unit-tests.js",
       "mode": "0000644",
-      "sha256": "16b3277dc426f3bb2c7043d1c0b466b7db65c75a277c4e77864457152624cf2a"
+      "sha256": "52b452c7f022282371d0583561498737716103358ed8e010eb9734efe77f2e89"
     },
     {
       "path": "scripts/bongos/runner-drift.js",
@@ -15139,6 +15144,11 @@
       "mode": "0000644",
       "sha256": "f09f297371563a361002d1443414aa5ab65da36ad5e68bfadb634c659aeda6f3"
     },
+    {
+      "path": "src/bongos/builder-payouts.js",
+      "mode": "0000644",
+      "sha256": "b84ffb276778a5ddf018618c689b656c2d5d3a810af9e829dcb5fd20e6d6e81f"
+    },
     {
       "path": "src/bongos/cascade-dispatch.js",
       "mode": "0000644",
@@ -15492,7 +15502,7 @@
     {
       "path": "src/bongos/routes/payout-approvals.js",
       "mode": "0000644",
-      "sha256": "7528a05d03970ea359b8b15e8bdd2a8cc56835e3c867f7662f09b3adf38ea8d5"
+      "sha256": "5575f0616b45c78f57a8fa237ead916f3b04e4eae394f807603d7bf6cb53a912"
     },
     {
       "path": "src/bongos/routes/payout-gates.js",
@@ -15582,7 +15592,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "06f9627d1fd34e3166cb8f6a16db6257307eec862791c77d5e17568dcf83e156"
+      "sha256": "8c2086ebd21b5a8ab1e3b15c65e514db0f7460405b2ef08f6e4a4c1e456ad9c0"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -16399,6 +16409,16 @@
       "mode": "0000644",
       "sha256": "2eecaaa02ad5d2cd8e25449d66dc86aa1884278dbf72656c0d9401129034e247"
     },
+    {
+      "path": "tests/builder_payouts.mjs",
+      "mode": "0000644",
+      "sha256": "45d49e84f826115c43bf9f01a42eae4ee70ffe26fdc02acf303b345c9850d397"
+    },
+    {
+      "path": "tests/builder_payouts_db.mjs",
+      "mode": "0000644",
+      "sha256": "1676f0b2452e0d834df2b49974d4699f918e223e56d2f4193ffe87339b6f1f4a"
+    },
     {
       "path": "tests/builder_tester_tag.mjs",
       "mode": "0000644",

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 657 operations across 83 resource groups
+- 659 operations across 83 resource groups
 
 ## Use it from your project
 

package/clients/bongos-client/bongos-client.global.js

@@ -1037,6 +1037,10 @@ function createClient(opts = {}) {
       getPayoutsApprovals: (args) => request("GET", "/payouts/approvals", { hasBody: false }, args),
       // POST /payouts/approve — rank: archon — POST /payouts/approve
       postPayoutsApprove: (args) => request("POST", "/payouts/approve", { hasBody: true }, args),
+      // GET /payouts/builder-payouts — rank: archon — GET /payouts/builder-payouts
+      getPayoutsBuilderPayouts: (args) => request("GET", "/payouts/builder-payouts", { hasBody: false }, args),
+      // POST /payouts/builder-payouts — rank: archon — POST /payouts/builder-payouts
+      postPayoutsBuilderPayouts: (args) => request("POST", "/payouts/builder-payouts", { hasBody: true }, args),
       // POST /payouts/contracts — rank: archon — POST /payouts/contracts
       postPayoutsContracts: (args) => request("POST", "/payouts/contracts", { hasBody: true }, args),
       // POST /payouts/freezes — rank: archon — POST /payouts/freezes

package/clients/bongos-client/index.cjs

@@ -1036,6 +1036,10 @@ function createClient(opts = {}) {
       getPayoutsApprovals: (args) => request("GET", "/payouts/approvals", { hasBody: false }, args),
       // POST /payouts/approve — rank: archon — POST /payouts/approve
       postPayoutsApprove: (args) => request("POST", "/payouts/approve", { hasBody: true }, args),
+      // GET /payouts/builder-payouts — rank: archon — GET /payouts/builder-payouts
+      getPayoutsBuilderPayouts: (args) => request("GET", "/payouts/builder-payouts", { hasBody: false }, args),
+      // POST /payouts/builder-payouts — rank: archon — POST /payouts/builder-payouts
+      postPayoutsBuilderPayouts: (args) => request("POST", "/payouts/builder-payouts", { hasBody: true }, args),
       // POST /payouts/contracts — rank: archon — POST /payouts/contracts
       postPayoutsContracts: (args) => request("POST", "/payouts/contracts", { hasBody: true }, args),
       // POST /payouts/freezes — rank: archon — POST /payouts/freezes

package/clients/bongos-client/index.d.ts

@@ -144,6 +144,7 @@ export interface GetPageNotesSiteResponse { notes: unknown }
 export interface GetPayTermsResponse { pay_terms: unknown }
 export interface GetPayTypeGatesResponse { gates: unknown }
 export interface GetPayoutsApprovalsResponse { approvals: unknown }
+export interface GetPayoutsBuilderPayoutsResponse { payouts: unknown; page: PageInfo }
 export interface GetPayoutsGatesBuilderIdResponse { gate: unknown }
 export interface GetPayoutsRulesResponse { rules: unknown }
 export interface GetProfilesHandleResponse { account: unknown; cross_project: unknown }
@@ -534,6 +535,7 @@ export interface PostPayoutsAgeRecordsRequest { builder_id: StringifiableId; tie
 export interface PostPayoutsAgeRecordsResponse { record: unknown }
 export interface PostPayoutsApproveRequest { recipient_id?: StringifiableId; amount_cents?: unknown; currency?: unknown; note?: unknown }
 export interface PostPayoutsApproveResponse { approval: unknown }
+export interface PostPayoutsBuilderPayoutsRequest { approval_id: StringifiableId; task_id: StringifiableId }
 export interface PostPayoutsFreezesIdDecideRequest { decision: unknown; statement: unknown }
 export interface PostPayoutsFreezesIdDecideResponse { event: unknown }
 export interface PostPayoutsFreezesRequest { builder_id: StringifiableId; notice_text: unknown; owed_cents?: unknown }
@@ -1675,6 +1677,10 @@ export interface BongosClient {
     getPayoutsApprovals(args?: RequestArgs): Promise<GetPayoutsApprovalsResponse>;
     /** POST /payouts/approve — rank: archon */
     postPayoutsApprove(args?: RequestArgs & { body?: PostPayoutsApproveRequest }): Promise<PostPayoutsApproveResponse>;
+    /** GET /payouts/builder-payouts — rank: archon */
+    getPayoutsBuilderPayouts(args?: RequestArgs): Promise<GetPayoutsBuilderPayoutsResponse>;
+    /** POST /payouts/builder-payouts — rank: archon */
+    postPayoutsBuilderPayouts(args: RequestArgs & { body: PostPayoutsBuilderPayoutsRequest }): Promise<ApiResponse>;
     /** POST /payouts/contracts — rank: archon */
     postPayoutsContracts(args?: RequestArgs): Promise<ApiResponse>;
     /** POST /payouts/freezes — rank: archon */

package/clients/bongos-client/index.mjs

@@ -1033,6 +1033,10 @@ export function createClient(opts = {}) {
       getPayoutsApprovals: (args) => request("GET", "/payouts/approvals", { hasBody: false }, args),
       // POST /payouts/approve — rank: archon — POST /payouts/approve
       postPayoutsApprove: (args) => request("POST", "/payouts/approve", { hasBody: true }, args),
+      // GET /payouts/builder-payouts — rank: archon — GET /payouts/builder-payouts
+      getPayoutsBuilderPayouts: (args) => request("GET", "/payouts/builder-payouts", { hasBody: false }, args),
+      // POST /payouts/builder-payouts — rank: archon — POST /payouts/builder-payouts
+      postPayoutsBuilderPayouts: (args) => request("POST", "/payouts/builder-payouts", { hasBody: true }, args),
       // POST /payouts/contracts — rank: archon — POST /payouts/contracts
       postPayoutsContracts: (args) => request("POST", "/payouts/contracts", { hasBody: true }, args),
       // POST /payouts/freezes — rank: archon — POST /payouts/freezes

package/docs/api/openapi.json

@@ -19595,6 +19595,90 @@
         ]
       }
     },
+    "/payouts/builder-payouts": {
+      "get": {
+        "operationId": "get_payouts_builder_payouts",
+        "tags": [
+          "payouts"
+        ],
+        "summary": "GET /payouts/builder-payouts",
+        "description": "GET /api/bongos/payouts/builder-payouts — every builder payout and where it stands (task 1003183, M04): paid, or owed with its latest try and the reason in words.\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": "src/bongos/routes/payout-approvals.js",
+        "x-permissions": [
+          "payout.approve"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetPayoutsBuilderPayoutsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_payouts_builder_payouts",
+        "tags": [
+          "payouts"
+        ],
+        "summary": "POST /payouts/builder-payouts",
+        "description": "POST /api/bongos/payouts/builder-payouts — send ONE approved payout for ONE task (task 1003183, M04). Body: { approval_id, task_id }. The person and the amount come from the approval, never the body. A person presses it on the website: the approval says what may be paid, and this is the person sending it (Art. I). Pressing again is safe: a paid task answers paid, an owed one retries with the same processor key.\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": "src/bongos/routes/payout-approvals.js",
+        "x-permissions": [
+          "payout.approve"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostPayoutsBuilderPayoutsRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/payouts/contracts": {
       "post": {
         "operationId": "post_payouts_contracts",
@@ -32569,6 +32653,19 @@
           "approvals"
         ]
       },
+      "GetPayoutsBuilderPayoutsResponse": {
+        "type": "object",
+        "properties": {
+          "payouts": {},
+          "page": {
+            "$ref": "#/components/schemas/PageInfo"
+          }
+        },
+        "required": [
+          "payouts",
+          "page"
+        ]
+      },
       "GetPayoutsGatesBuilderIdResponse": {
         "type": "object",
         "properties": {
@@ -38572,6 +38669,22 @@
           "approval"
         ]
       },
+      "PostPayoutsBuilderPayoutsRequest": {
+        "type": "object",
+        "properties": {
+          "approval_id": {
+            "$ref": "#/components/schemas/StringifiableId"
+          },
+          "task_id": {
+            "$ref": "#/components/schemas/StringifiableId"
+          }
+        },
+        "required": [
+          "approval_id",
+          "task_id"
+        ],
+        "additionalProperties": false
+      },
       "PostPayoutsFreezesIdDecideRequest": {
         "type": "object",
         "properties": {
@@ -41644,9 +41757,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 657,
-  "x-schema-count": 705,
+  "x-endpoint-count": 659,
+  "x-schema-count": 707,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 451,
+  "x-response-schemas": 452,
   "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. 657 endpoints across 111 route files.
+> **Generated from the live route files** — the route file is authoritative. 659 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`.
@@ -708,13 +708,15 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | 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)
+## `payouts` (18)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | POST | `/api/bongos/payouts/age-records` | `archon` | `builder_id`, `tier` | POST /api/bongos/payouts/age-records — record a builder's age tier, verified by a person. |
 | GET | `/api/bongos/payouts/approvals` | `archon` | — | GET /api/bongos/payouts/approvals — the log, newest first. |
 | POST | `/api/bongos/payouts/approve` | `archon` | `recipient_id`, `amount_cents`, `currency`, `note` | POST /api/bongos/payouts/approve — approve ONE payout. |
+| GET | `/api/bongos/payouts/builder-payouts` | `archon` | — | GET /api/bongos/payouts/builder-payouts — every builder payout and where it stands (task 1003183, M04): paid, or owed with its latest try… |
+| POST | `/api/bongos/payouts/builder-payouts` | `archon` | `approval_id`, `task_id` | POST /api/bongos/payouts/builder-payouts — send ONE approved payout for ONE task (task 1003183, M04). |
 | POST | `/api/bongos/payouts/contracts` | `archon` | — | POST /api/bongos/payouts/contracts — sign ONE contract. |
 | POST | `/api/bongos/payouts/freezes` | `archon` | `builder_id`, `notice_text`, `owed_cents` | POST /api/bongos/payouts/freezes — a person freezes a builder's payouts by hand. |
 | POST | `/api/bongos/payouts/freezes/:id/decide` | `archon` | `decision`, `statement` | POST /api/bongos/payouts/freezes/:id/decide — uphold or lift a freeze, with the reason the person will read. |

package/docs/architecture.md

@@ -308,6 +308,21 @@ payout_guardian_cosigns(id, builder_id, guardian_id, approval_id | rule_id+run_k
               -- and a co-signature by anyone but the current guardian.
 ```
 
+Builder payouts (migration `core_290`, task 1003183, [ADR 0397](adr/0397-the-payment-rail-is-stripe-connect-with-one-connected-account-per-project.md) D7 — a builder is paid for a task exactly once; `src/bongos/builder-payouts.js`, routes `GET`/`POST /payouts/builder-payouts` gated `payout.approve` plus the person's own web session for the POST; the `payout` movement is booked through the economy module's `economy.account` port in the same transaction. No processor adapter exists yet, so every payout is recorded owed and held `no_processor`):
+
+```
+builder_payouts_owed(id, builder_id FK, task_id FK, approval_id FK payout_approvals,
+              amount_cents, currency, recorded_by FK, created_at)
+              -- written BEFORE anything is sent; UNIQUE (builder_id, task_id) and UNIQUE
+              -- (approval_id): a task is paid once, an approval pays one task.
+builder_payout_attempts(id, owed_id FK, outcome sent|failed|held, processor_ref, reason,
+              actor_id, created_at)
+              -- at most one `sent` per debt (partial UNIQUE); sent needs processor_ref,
+              -- failed/held need a reason. BOTH APPEND-ONLY by trigger. The processor is
+              -- called with idempotency key `bongos-payout-<owed id>`, so a retry after an
+              -- unknown outcome gets the same transfer back.
+```
+
 Store sub-categories (migration `core_280`, task 1004355, [ADR 0342](adr/0342-module-categories-are-eight-parents-with-approved-sub-categories.md) D3 — an author proposes one at publish, a Metic+ person approves, renames or merges it; `src/bongos/module-subcategories.js`):
 
 ```

package/docs/module-api-changelog.md

@@ -3290,5 +3290,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.24.15 with no explicit bump. run 41124515103. (task 1002620)
   1.24.17 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.24.16 with no explicit bump. run 41129472650. (task 1002620)
+  1.24.18 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.24.17 with no explicit bump. run 41131020363. (task 1002620)
+  1.24.19 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.24.18 with no explicit bump. run 41137645458. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/migrations/core_290_builder_payouts.sql

@@ -0,0 +1,86 @@
+-- core_290_builder_payouts.sql — a builder is paid for a task, exactly once, and a payout
+-- that did not go through still says it is owed (task 1003183, goal 1000092 M04;
+-- ADR 0385 decisions 1 and 4, ADR 0397 decisions 2, 5 and 7).
+--
+-- TWO TABLES, BOTH APPEND-ONLY.
+--
+--   builder_payouts_owed      one row per (builder, task): what is owed, and the
+--                             personal approval that authorises it. Written BEFORE
+--                             the processor is asked to move anything, in its own
+--                             committed step, so a crash, a refusal or a timeout
+--                             afterwards still leaves the debt on record. The failure
+--                             this exists to prevent is a builder who was silently
+--                             never paid, with no trace anything was due.
+--   builder_payout_attempts   every try at paying one owed row: sent (with the
+--                             processor's transfer reference), failed (with the
+--                             reason), or held (not sent, with the reason: a gate,
+--                             no processor connected, a missing approval).
+--
+-- EXACTLY ONCE is three rules, each enforced here, not only by the code:
+--   * one owed row per (builder, task), and one per approval (an approval pays one
+--     thing, never two tasks);
+--   * at most one `sent` attempt per owed row;
+--   * the processor is called with an idempotency key derived from the owed row's id,
+--     so a retry after an unknown outcome is answered by the processor with the same
+--     transfer, not a second one.
+--
+-- Amounts are integer cents, as the approval that authorises them is. The money
+-- itself is held by the processor (ADR 0397); the matching `payout` movement is booked
+-- through the economy module's `economy.account` port, in micro-dollars, in the same step as `sent`.
+
+CREATE TABLE IF NOT EXISTS builder_payouts_owed (
+  id            BIGSERIAL   PRIMARY KEY,
+  builder_id    BIGINT      NOT NULL REFERENCES builders(id),
+  task_id       BIGINT      NOT NULL REFERENCES tasks(id),
+  approval_id   BIGINT      NOT NULL REFERENCES payout_approvals(id),
+  amount_cents  BIGINT      NOT NULL,
+  currency      TEXT        NOT NULL,
+  recorded_by   BIGINT      NOT NULL REFERENCES builders(id),
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT builder_payouts_owed_amount_chk CHECK (amount_cents > 0),
+  CONSTRAINT builder_payouts_owed_currency_chk CHECK (currency ~ '^[A-Z]{3}$')
+);
+
+-- one payout per builder per task, and one task per approval
+CREATE UNIQUE INDEX IF NOT EXISTS builder_payouts_owed_one_per_task
+  ON builder_payouts_owed (builder_id, task_id);
+CREATE UNIQUE INDEX IF NOT EXISTS builder_payouts_owed_one_per_approval
+  ON builder_payouts_owed (approval_id);
+CREATE INDEX IF NOT EXISTS builder_payouts_owed_by_time ON builder_payouts_owed (created_at DESC, id DESC);
+
+CREATE TABLE IF NOT EXISTS builder_payout_attempts (
+  id            BIGSERIAL   PRIMARY KEY,
+  owed_id       BIGINT      NOT NULL REFERENCES builder_payouts_owed(id),
+  outcome       TEXT        NOT NULL,
+  processor_ref TEXT,
+  reason        TEXT,
+  actor_id      BIGINT      REFERENCES builders(id),
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT builder_payout_attempts_outcome_chk CHECK (outcome IN ('sent', 'failed', 'held')),
+  CONSTRAINT builder_payout_attempts_reason_len_chk CHECK (reason IS NULL OR length(reason) <= 300),
+  -- a sent attempt names the processor transfer; a failed or held one says why
+  CONSTRAINT builder_payout_attempts_cause_chk CHECK (
+    (outcome = 'sent' AND processor_ref IS NOT NULL) OR
+    (outcome IN ('failed', 'held') AND reason IS NOT NULL AND length(reason) > 0))
+);
+
+-- paid at most once
+CREATE UNIQUE INDEX IF NOT EXISTS builder_payout_attempts_one_sent
+  ON builder_payout_attempts (owed_id) WHERE outcome = 'sent';
+CREATE INDEX IF NOT EXISTS builder_payout_attempts_by_owed ON builder_payout_attempts (owed_id, id DESC);
+
+CREATE OR REPLACE FUNCTION builder_payouts_append_only() RETURNS trigger AS $$
+BEGIN
+  RAISE EXCEPTION '% is append-only: a payout is never edited or deleted, a new attempt is recorded instead', TG_TABLE_NAME;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS builder_payouts_owed_no_rewrite ON builder_payouts_owed;
+CREATE TRIGGER builder_payouts_owed_no_rewrite BEFORE UPDATE OR DELETE ON builder_payouts_owed
+  FOR EACH ROW EXECUTE FUNCTION builder_payouts_append_only();
+DROP TRIGGER IF EXISTS builder_payout_attempts_no_rewrite ON builder_payout_attempts;
+CREATE TRIGGER builder_payout_attempts_no_rewrite BEFORE UPDATE OR DELETE ON builder_payout_attempts
+  FOR EACH ROW EXECUTE FUNCTION builder_payouts_append_only();
+
+INSERT INTO schema_migrations (version) VALUES ('core_290_builder_payouts')
+  ON CONFLICT DO NOTHING;

package/modules/economy/module.json

@@ -8,6 +8,6 @@
   "default": true,
   "maintenance": { "status": "core-maintained" },
   "contributes": { "migrations": true, "routes": ["cost", "credits", "earnings", "leaderboard", "project-account", "reward"] },
-  "provides": ["reward"],
+  "provides": ["reward", "economy.account"],
   "consumes": []
 }

package/modules/economy/routes/project-account.js

@@ -15,11 +15,20 @@
 
 const express = require('express');
 const api = require('../../../src/module-api');
-const { readAccount } = require('../project-account');
+const { readAccount, recordMovement } = require('../project-account');
 
 const log = api.logger('economy');
 
+// The `economy.account` PORT (task 1003183): core's payout path (src/bongos/builder-payouts.js)
+// books its `payout` movement through this, inside its own transaction, without importing the
+// module. Registered here for the reason routes/reward.js gives: the loader runs this factory in
+// the live server and whenever a test rebuilds the router. hasProvider-guarded for re-runs.
+function registerSeams() {
+  if (!api.hasProvider('economy.account')) api.registerProvider('economy.account', { recordMovement });
+}
+
 module.exports = function buildProjectAccountRouter({ processor = null } = {}) {
+  registerSeams();
   const router = express.Router();
 
   // rank: payout.approve (archon floor) — the owner. The account's balance and who was paid what

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.17",
+  "version": "1.24.19",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.24.17",
+      "version": "1.24.19",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.17",
+  "version": "1.24.19",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -10987,5 +10987,17 @@
       "id": "1005029",
       "text": "Artists with both an OpenRouter and a Gemini key saved can now choose which one runs their AI request."
     }
+  ],
+  "1.24.18": [
+    {
+      "id": "1003183",
+      "text": "Builders can now be paid for a task, and never twice. Each payment is written down as owed before anything is sent, so a failed payment still leaves a record. No money moves yet: the Stripe connection comes next."
+    }
+  ],
+  "1.24.19": [
+    {
+      "id": "1005030",
+      "text": "A mockup of the Builders leaderboard now shows the circuit-trace divider from the owner's Studio idea between the column headings and the table. The live page is unchanged."
+    }
   ]
 }