@bongos/core 1.24.16 → 1.24.18

package/docs/copy-registry.json

@@ -3,9 +3,9 @@
   "generator": "scripts/bongos/copy-inventory.js",
   "goal": 1000074,
   "counts": {
-    "strings": 3278,
-    "unique_ids": 2595,
-    "certain": 3278,
+    "strings": 3276,
+    "unique_ids": 2593,
+    "certain": 3276,
     "heuristic": 0,
     "duplicate_ids": 275
   },
@@ -13,7 +13,7 @@
     "builders-hall": {
       "at": "modules/hall-ui/public",
       "files": 172,
-      "strings": 2165
+      "strings": 2163
     },
     "status-dashboard": {
       "at": "modules/status-ui/public",
@@ -7694,7 +7694,7 @@
       "surface": "builders-hall",
       "text": "Free here. {…} bills you for it directly.",
       "file": "modules/hall-ui/public/ai-studio.js",
-      "line": 334,
+      "line": 336,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10200,15 +10200,6 @@
       "origin": "js-markup",
       "confidence": "certain"
     },
-    {
-      "id": "b7d4eeb3f762",
-      "surface": "builders-hall",
-      "text": "My own key",
-      "file": "modules/hall-ui/public/ai-studio.js",
-      "line": 334,
-      "origin": "js-markup",
-      "confidence": "certain"
-    },
     {
       "id": "3d0d554cd684",
       "surface": "builders-hall",
@@ -21693,15 +21684,6 @@
       "origin": "js-markup",
       "confidence": "certain"
     },
-    {
-      "id": "c80c3434ae36",
-      "surface": "builders-hall",
-      "text": "{…} key ending {…}",
-      "file": "modules/hall-ui/public/ai-studio.js",
-      "line": 334,
-      "origin": "js-markup",
-      "confidence": "certain"
-    },
     {
       "id": "5ad81ff61920",
       "surface": "builders-hall",

package/docs/module-api-changelog.md

@@ -3288,5 +3288,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.24.13 with no explicit bump. run 41110951037. (task 1002620)
   1.24.16 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         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)
 ---------------------------------------------------------------------------
 ```

package/docs/page-readings.json

@@ -5,16 +5,16 @@
   "adr": "0341 D3",
   "reread": "node scripts/bongos/page-reader.js --stale",
   "how": ["Generated by node scripts/bongos/page-reader.js (BV2.TW04, task 1004315; ADR 0341 D3). Do not hand-edit.","One entry per page of docs/page-inventory.json. Lines are in page order: the default state first, and a line only another state shows sits where that state shows it, with its state named.","placement: placed = a docs/copy-registry.json row renders it (file, line, string_id); shared = shell text every page of the surface carries (top bar, sidebar, footer), with its row when the registry has one; unplaced = the registry cannot place it (a rewrite becomes an engineer task, ADR 0341 D4).","text keeps {…} where the registry row has a hole, or where a value the page read from its API was filled in. A string that is only such data is counted under omitted.data, not listed.","reading_hash is over the non-shared lines (key, section, text); files_hash is over the page's inventory files. --check compares files_hash only and never opens a browser.","Rendered through the hall-preview harness (hall) and the ui-design kit stub (landing, status), at 1280x800 with the clock pinned, so a reading is the fixture world's page."],
-  "counts": {"pages":52,"lines":5612,"placed":1755,"shared":461,"unplaced":3396,"omitted_data":3766},
+  "counts": {"pages":52,"lines":5612,"placed":1753,"shared":461,"unplaced":3398,"omitted_data":3766},
   "pages": [
     {
       "id": "builders:ai-studio",
       "surface": "builders",
       "title": "Studio",
       "states_read": ["pick","describe","make","waiting","result","result-own","failed","balance","balance-all","out"],
-      "files_hash": "b4dc755790ac158e",
-      "reading_hash": "7fa800b814783e81",
-      "counts": {"lines":102,"placed":40,"shared":8,"unplaced":54},
+      "files_hash": "48c0f2c2c104a63b",
+      "reading_hash": "475acccd2681bd7f",
+      "counts": {"lines":102,"placed":38,"shared":8,"unplaced":56},
       "omitted": {"data":15},
       "notes": [],
       "lines": [
@@ -84,9 +84,9 @@
         {"key":"L0064","section":"How do you want to pay?","text":"PDF","placement":"unplaced","state":"make"},
         {"key":"L0065","section":"How do you want to pay?","text":"“Turn the sketch into a finished hero picture for the landing pa…”","placement":"unplaced","state":"make"},
         {"key":"L0066","section":"How do you want to pay?","text":"change","placement":"unplaced","state":"make"},
-        {"key":"L0067","section":"How do you want to pay?","text":"My own key","placement":"placed","file":"modules/hall-ui/public/ai-studio.js","line":334,"string_id":"b7d4eeb3f762","state":"make"},
-        {"key":"L0068","section":"How do you want to pay?","text":"Free here. {…} bills you for it directly.","placement":"placed","file":"modules/hall-ui/public/ai-studio.js","line":334,"string_id":"e9a1af5dc515","state":"make"},
-        {"key":"L0069","section":"How do you want to pay?","text":"{…} key ending {…}","placement":"placed","file":"modules/hall-ui/public/ai-studio.js","line":334,"string_id":"c80c3434ae36","state":"make"},
+        {"key":"L0067","section":"How do you want to pay?","text":"My own key","placement":"unplaced","state":"make"},
+        {"key":"L0068","section":"How do you want to pay?","text":"Free here. {…} bills you for it directly.","placement":"placed","file":"modules/hall-ui/public/ai-studio.js","line":336,"string_id":"e9a1af5dc515","state":"make"},
+        {"key":"L0069","section":"How do you want to pay?","text":"Gemini key ending {…}","placement":"unplaced","state":"make"},
         {"key":"L0070","section":"How do you want to pay?","text":"My balance","placement":"placed","file":"modules/hall-ui/public/ai-studio.js","line":340,"string_id":"39afdc03594a","state":"make"},
         {"key":"L0071","section":"How do you want to pay?","text":"Usually a few cents. Up to {…} is set aside, and the rest comes back.","placement":"placed","file":"modules/hall-ui/public/ai-studio.js","line":340,"string_id":"664555b65658","state":"make"},
         {"key":"L0072","section":"How do you want to pay?","text":"{…} left","placement":"placed","file":"modules/hall-ui/public/market-watch.js","line":73,"string_id":"92b79edf21f6","state":"make"},
@@ -4216,7 +4216,7 @@
       "surface": "builders",
       "title": "Studio",
       "states_read": ["home","out","flow","flow-pick","status","words-offer","words-edit","reviews","full","full-back","approvals","approvals-before","approvals-phone","approvals-note","approved","sent-back","approvals-page"],
-      "files_hash": "9eda81ed0ffd5014",
+      "files_hash": "6c591072e20de9f0",
       "reading_hash": "bcba11e6cef56218",
       "counts": {"lines":31,"placed":16,"shared":6,"unplaced":9},
       "omitted": {"data":4},

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/ai-studio/keys.js

@@ -65,6 +65,10 @@ function listPublic(rows) {
 function chooseKey(stored, payWith) {
   const own = ['openrouter', 'gemini'].find((p) => (stored || []).includes(p));
   if (payWith === 'ours') return { source: 'ours' };
+  // A named provider picks that key when both are saved.
+  if (isProvider(payWith)) {
+    return (stored || []).includes(payWith) ? { source: 'own', provider: payWith } : { error: 'no_own_key' };
+  }
   if (payWith === 'own' && !own) return { error: 'no_own_key' };
   if (payWith !== undefined && payWith !== null && payWith !== 'own') return { error: 'bad_pay_with' };
   return own ? { source: 'own', provider: own } : { source: 'ours' };

package/modules/ai-studio/routes/ai-studio.js

@@ -173,7 +173,7 @@ module.exports = function buildAiStudioRouter() {
     if (api.validateOrRespond(req, res, {
       prompt: { required: true, type: 'string', maxLength: S.MAX_PROMPT + 200 },
       file_ids: { required: true, type: 'array', maxItems: S.MAX_FILES },
-      pay_with: { type: 'string', enum: ['own', 'ours'] },
+      pay_with: { type: 'string', enum: ['own', 'ours', 'openrouter', 'gemini'] },
     })) return;
     if (!S.isAdult(await db.latestAgeTier(req.builder.id))) return res.fail('adults_only', { status: 403, message: ADULTS_ONLY });
     const checked = S.checkRequest(req.body);

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/modules/hall-ui/public/ai-studio-lib.js

@@ -107,25 +107,31 @@
 
   // The own key the server will run on: OpenRouter first, as keys.chooseKey
   // prefers it (it reports its cost). null when none is saved.
-  function ownKey(keys) {
+  function ownKey(keys) { return ownKeys(keys)[0] || null; }
+
+  // Every own key that is saved, OpenRouter first: step 3 offers one card each,
+  // so a builder with both picks which one runs.
+  function ownKeys(keys) {
     const list = (keys && keys.keys) || [];
-    const set = (p) => list.find((k) => k && k.provider === p && k.set);
-    const k = set('openrouter') || set('gemini');
-    if (!k) return null;
-    return k.provider === 'openrouter'
-      ? { provider: 'openrouter', name: 'OpenRouter', billedBy: 'OpenRouter', last4: k.last4 }
-      : { provider: 'gemini', name: 'Gemini', billedBy: 'Google', last4: k.last4 };
+    return ['openrouter', 'gemini']
+      .map((p) => list.find((k) => k && k.provider === p && k.set))
+      .filter(Boolean)
+      .map((k) => (k.provider === 'openrouter'
+        ? { provider: 'openrouter', name: 'OpenRouter', billedBy: 'OpenRouter', last4: k.last4 }
+        : { provider: 'gemini', name: 'Gemini', billedBy: 'Google', last4: k.last4 }));
   }
 
-  // Step 3's two cards. balance is GET /ai-studio/balance's body.
+  // Step 3's cards. balance is GET /ai-studio/balance's body.
   function payChoices(keys, balance) {
-    const own = ownKey(keys);
+    const owns = ownKeys(keys);
+    const own = owns[0] || null;
     const b = balance || {};
     const avail = b.balance ? b.balance.available_micro : null;
     const max = isMicro(b.max_cost_micro) ? b.max_cost_micro : null;
     const payments = !!b.balance;
     return {
       own,
+      owns,
       payments,
       setAside: max === null ? '' : usd(max),
       left: payments ? `${balanceUsd(avail)} left` : '',
@@ -260,7 +266,7 @@
 
   const lib = {
     MAX_FILES, MAX_IMAGE_BYTES, MAX_PDF_BYTES, IMAGE_TYPES, PDF_TYPE, STEPS, TOPUP_CHOICES, ANSWER_AFTER_SEC,
-    usd, balanceUsd, sizeText, routeOf, checkFile, isImage, stepMarks, quoteLine, ownKey, payChoices,
+    usd, balanceUsd, sizeText, routeOf, checkFile, isImage, stepMarks, quoteLine, ownKey, ownKeys, payChoices,
     waitSteps, clock, isFinished, receipt, againLine, monthSummary, ledgerLine, replyHtml, homeLine,
   };
   if (typeof module !== 'undefined' && module.exports) module.exports = lib;

package/modules/hall-ui/public/ai-studio.js

@@ -331,12 +331,12 @@
     const files = readyFiles();
     const c = lib.payChoices(state.keys, state.balance);
     const thumbs = files.slice(0, 3).map((f) => thumb(f)).join('');
-    const ownCard = c.own ? `
-      <button type="button" class="st-action ais-card ais-card--own" data-pay="own">
-        <span class="st-action__label">My own key</span>
-        <span class="ais-card__line">Free here. ${esc(c.own.billedBy)} bills you for it directly.</span>
-        <span class="ais-card__foot">${esc(c.own.name)} key ending ${esc(c.own.last4 || '')}</span>
-      </button>` : '';
+    const ownCard = c.owns.map((k) => `
+      <button type="button" class="st-action ais-card ais-card--own" data-pay="${esc(k.provider)}">
+        <span class="st-action__label">${c.owns.length > 1 ? `My ${esc(k.name)} key` : 'My own key'}</span>
+        <span class="ais-card__line">Free here. ${esc(k.billedBy)} bills you for it directly.</span>
+        <span class="ais-card__foot">${c.owns.length > 1 ? '' : `${esc(k.name)} `}key ending ${esc(k.last4 || '')}</span>
+      </button>`).join('');
     const balanceCard = c.payments ? `
       <button type="button" class="st-action ais-card ais-card--ours" data-pay="ours" ${c.short ? 'disabled' : ''}>
         <span class="st-action__label">My balance</span>
@@ -346,8 +346,8 @@
     let foot = 'You only pay for what it really cost. If it fails, nothing is taken.';
     let extra = '';
     if (c.payments && c.short) extra = `<p class="ais-faint">Your balance is under ${esc(c.setAside)}. <a href="/builders/ai-studio?view=balance">Add money</a> to pay this way.</p>`;
-    if (!c.own) extra += `<p class="ais-faint">Have your own OpenRouter or Gemini key? <a href="${SETTINGS_KEYS}">Add it in Settings</a> and make things for free here.</p>`;
-    if (!c.own && !c.payments) foot = 'Paying from a balance is not set up here yet, so add your own key in Settings to make something.';
+    if (!c.owns.length) extra += `<p class="ais-faint">Have your own OpenRouter or Gemini key? <a href="${SETTINGS_KEYS}">Add it in Settings</a> and make things for free here.</p>`;
+    if (!c.owns.length && !c.payments) foot = 'Paying from a balance is not set up here yet, so add your own key in Settings to make something.';
     page.innerHTML = `${stepHead('make')}
       <h1 class="ais-ask" data-head tabindex="-1">How do you want to pay?</h1>
       <div class="ais-row ais-row--summary">${thumbs}<span class="ais-grow ais-soft">${esc(lib.quoteLine(state.draft.prompt))}</span><a class="ais-link" href="/builders/ai-studio?step=describe" data-nav="step=describe">change</a></div>

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.16",
+  "version": "1.24.18",
   "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

@@ -10981,5 +10981,17 @@
       "id": "1005028",
       "text": "Settings now has a Your age section where you record your age group, which switches on AI Studio for adults."
     }
+  ],
+  "1.24.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."
+    }
   ]
 }

package/scripts/bongos/run-unit-tests.js

@@ -285,6 +285,10 @@ const INTEGRATION = new Set([
   // causeless or wrongly-directed movement, any UPDATE/DELETE/TRUNCATE, and a second row
   // for one processor reference.
   'project_account_db',
+  // task 1003183: builder payouts from the real migrations — Postgres refuses a second debt
+  // for one task or approval, a second sent attempt, a causeless attempt, and any rewrite;
+  // the real payForTask pays once and books one payout movement.
+  'builder_payouts_db',
   // task 1004408: migration platform_identity_028 deletes the old hub invite's
   // pending rows before a cutoff it reads from the core_upgrades ledger. Only a real
   // engine runs the DO block, the numeric version compare and the one-shot guard.