@bongos/core 1.24.23 → 1.24.25

package/docs/page-readings.json

@@ -5,7 +5,7 @@
   "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":1750,"shared":461,"unplaced":3401,"omitted_data":3791},
+  "counts": {"pages":52,"lines":5651,"placed":1762,"shared":461,"unplaced":3428,"omitted_data":3797},
   "pages": [
     {
       "id": "builders:ai-studio",
@@ -599,7 +599,7 @@
       "surface": "builders",
       "title": "Deploy",
       "states_read": ["work","out"],
-      "files_hash": "aa2f04c47a6f0a28",
+      "files_hash": "d6dcbe183e4963f5",
       "reading_hash": "b9b3d3cdbfae00be",
       "counts": {"lines":17,"placed":5,"shared":8,"unplaced":4},
       "omitted": {"data":3},
@@ -1118,7 +1118,7 @@
       "surface": "builders",
       "title": "Fleet costs",
       "states_read": ["ledger","out"],
-      "files_hash": "59f05ab36918fc65",
+      "files_hash": "734f72fc06bbad36",
       "reading_hash": "382e521aaa529c82",
       "counts": {"lines":32,"placed":9,"shared":8,"unplaced":15},
       "omitted": {"data":13},
@@ -2768,10 +2768,10 @@
       "surface": "builders",
       "title": "Project settings",
       "states_read": ["default"],
-      "files_hash": "2ca4ed0416148deb",
-      "reading_hash": "4f7a29f2c2f0ad7c",
-      "counts": {"lines":38,"placed":20,"shared":8,"unplaced":10},
-      "omitted": {"data":31},
+      "files_hash": "a182b780fad8350e",
+      "reading_hash": "fb1de73bb67c5c0d",
+      "counts": {"lines":77,"placed":32,"shared":8,"unplaced":37},
+      "omitted": {"data":37},
       "notes": [],
       "lines": [
         {"key":"L0001","section":"skip link","text":"Skip to content","placement":"shared","file":"modules/hall-ui/public/shell.js","line":881,"string_id":"87cee78ca134"},
@@ -2791,27 +2791,66 @@
         {"key":"L0015","section":"The fundamentals","text":"days ({…}–{…})","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":115,"string_id":"0e2bef756977"},
         {"key":"L0016","section":"The fundamentals","text":"offered","placement":"unplaced","occurrences":2},
         {"key":"L0017","section":"The fundamentals","text":"New category label","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":193,"string_id":"87f09d983f6c","attr":"placeholder"},
-        {"key":"L0018","section":"The fundamentals","text":"Add","placement":"placed","file":"modules/hall-ui/public/ai-studio.js","line":469,"string_id":"e4da002ae135"},
+        {"key":"L0018","section":"The fundamentals","text":"Add","placement":"placed","file":"modules/hall-ui/public/ai-studio.js","line":567,"string_id":"e4da002ae135"},
         {"key":"L0019","section":"The fundamentals","text":"committed config","placement":"unplaced"},
         {"key":"L0020","section":"The fundamentals","text":"not yet real","placement":"unplaced"},
         {"key":"L0021","section":"The fundamentals","text":"not available ({…})","placement":"unplaced"},
-        {"key":"L0022","section":"Danger zone","text":"Danger zone","placement":"placed","file":"modules/hall-ui/public/project-settings.html","line":56,"string_id":"13b22e48d9fb"},
-        {"key":"L0023","section":"Danger zone","text":"This project is hosted on {…}, and that is where it is taken offline or removed. Both links below open this project’s page there.","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":412,"string_id":"e97b2d549f10"},
-        {"key":"L0024","section":"Danger zone","text":"Manage this project on {…}","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":413,"string_id":"4e261fd15bd5"},
-        {"key":"L0025","section":"Danger zone","text":"Take it offline","placement":"placed","file":"modules/hall-ui/public/project-settings.html","line":59,"string_id":"da9da6e866bd"},
-        {"key":"L0026","section":"Danger zone","text":"— stops the project and its nightly backups but keeps everything: its database, its backups and your repository on GitHub. You can bring it back.","placement":"placed","file":"modules/hall-ui/public/project-settings.html","line":59,"string_id":"61ebc5d684fd"},
-        {"key":"L0027","section":"Danger zone","text":"Disconnect from Bongos entirely","placement":"placed","file":"modules/hall-ui/public/project-settings.html","line":60,"string_id":"d3efd513694b"},
-        {"key":"L0028","section":"Danger zone","text":"— erases the project’s server, its database and every backup, and releases its name and web address. Your repository on GitHub is kept. This cannot be undone.","placement":"placed","file":"modules/hall-ui/public/project-settings.html","line":60,"string_id":"d9ad3ee37a88"},
-        {"key":"L0029","section":"footer","text":"Sign out","placement":"shared","file":"modules/hall-ui/public/shell.js","line":520,"string_id":"1883ad7f07fc"},
-        {"key":"L0030","section":"Danger zone","text":"Builders hall · this session","placement":"placed","file":"modules/hall-ui/public/craft-mode.js","line":670,"string_id":"fd1903586e8e"},
-        {"key":"L0031","section":"What are you doing now?","text":"What are you doing now?","placement":"placed","file":"modules/hall-ui/public/craft-mode.js","line":671,"string_id":"60853319f290"},
-        {"key":"L0032","section":"What are you doing now?","text":"Pick one. You can switch any time from the top bar.","placement":"placed","file":"modules/hall-ui/public/craft-mode.js","line":672,"string_id":"4f87d5b17b54"},
-        {"key":"L0033","section":"What are you doing now?","text":"Building","placement":"unplaced"},
-        {"key":"L0034","section":"What are you doing now?","text":"{…} and {…}","placement":"placed","file":"modules/hall-ui/public/profile-nudge.js","line":77,"string_id":"56b00d773232","occurrences":3},
-        {"key":"L0035","section":"What are you doing now?","text":"Artistry","placement":"unplaced"},
-        {"key":"L0036","section":"What are you doing now?","text":"Ideating","placement":"unplaced"},
-        {"key":"L0037","section":"What are you doing now?","text":"Turn thoughts into ideas.","placement":"unplaced"},
-        {"key":"L0038","section":"What are you doing now?","text":"Ask me again next session","placement":"placed","file":"modules/hall-ui/public/craft-mode.js","line":675,"string_id":"fa86bf403775"}
+        {"key":"L0022","section":"Where the money went","text":"Where the money went","placement":"placed","file":"modules/hall-ui/public/project-settings.html","line":57,"string_id":"197969e4126a"},
+        {"key":"L0023","section":"Where the money went","text":"What this project has spent, what each builder has been paid, and what it has promised but not paid yet. A balance only means something after those promises.","placement":"placed","file":"modules/hall-ui/public/project-settings.html","line":58,"string_id":"b857cc458c6f"},
+        {"key":"L0024","section":"Where the money went","text":"Balance","placement":"unplaced"},
+        {"key":"L0025","section":"Where the money went","text":"on our record","placement":"unplaced"},
+        {"key":"L0026","section":"Where the money went","text":"Owed but not paid","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":477,"string_id":"eae3165eaaa0"},
+        {"key":"L0027","section":"Where the money went","text":"2 payments","placement":"unplaced"},
+        {"key":"L0028","section":"Where the money went","text":"Approved, not started","placement":"unplaced"},
+        {"key":"L0029","section":"Where the money went","text":"1 approval","placement":"unplaced"},
+        {"key":"L0030","section":"Where the money went","text":"{…} of {…}","placement":"placed","file":"modules/hall-ui/public/sky-panel.js","line":120,"string_id":"73c1372b43d9"},
+        {"key":"L0031","section":"Where the money went","text":"what is really free","placement":"unplaced"},
+        {"key":"L0032","section":"Owed but not paid","text":"Owed but not paid","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":477,"string_id":"eae3165eaaa0"},
+        {"key":"L0033","section":"Owed but not paid","text":"Builder","placement":"unplaced"},
+        {"key":"L0034","section":"Owed but not paid","text":"Task","placement":"placed","file":"modules/hall-ui/public/task.js","line":512,"string_id":"eff70e59d12e"},
+        {"key":"L0035","section":"Owed but not paid","text":"Amount","placement":"unplaced"},
+        {"key":"L0036","section":"Owed but not paid","text":"Owed since","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":477,"string_id":"0ba40083f03e"},
+        {"key":"L0037","section":"Owed but not paid","text":"Last try","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":477,"string_id":"165c5f26ef60"},
+        {"key":"L0038","section":"Owed but not paid","text":"Waiting — no payment processor connected yet","placement":"unplaced"},
+        {"key":"L0039","section":"Owed but not paid","text":"Did not go through — {…}","placement":"unplaced"},
+        {"key":"L0040","section":"By builder","text":"By builder","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":493,"string_id":"fa9356114e6b"},
+        {"key":"L0041","section":"By builder","text":"Builder","placement":"unplaced"},
+        {"key":"L0042","section":"By builder","text":"Spent","placement":"unplaced"},
+        {"key":"L0043","section":"By builder","text":"Paid","placement":"unplaced"},
+        {"key":"L0044","section":"By builder","text":"Owed","placement":"unplaced"},
+        {"key":"L0045","section":"By builder","text":"Approved","placement":"unplaced"},
+        {"key":"L0046","section":"By builder","text":"Spent is the recorded cost of each builder’s sessions (API, compute). Paid, owed and approved are payouts.","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":502,"string_id":"a553a7f1f108"},
+        {"key":"L0047","section":"Money out, by month","text":"Money out, by month","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":513,"string_id":"8a30ab62ad1d"},
+        {"key":"L0048","section":"Money out, by month","text":"Dec 2025","placement":"unplaced"},
+        {"key":"L0049","section":"Money out, by month","text":"Jan 2026","placement":"unplaced"},
+        {"key":"L0050","section":"Money out, by month","text":"Feb 2026","placement":"unplaced"},
+        {"key":"L0051","section":"Money out, by month","text":"Mar 2026","placement":"unplaced"},
+        {"key":"L0052","section":"Money out, by month","text":"Apr 2026","placement":"unplaced"},
+        {"key":"L0053","section":"Money out, by month","text":"May 2026","placement":"unplaced"},
+        {"key":"L0054","section":"Money out, by month","text":"Jun 2026","placement":"unplaced"},
+        {"key":"L0055","section":"Money out, by month","text":"Jul 2026","placement":"unplaced"},
+        {"key":"L0056","section":"Money out, by month","text":"Aug 2026","placement":"unplaced"},
+        {"key":"L0057","section":"Money out, by month","text":"Sep 2026","placement":"unplaced"},
+        {"key":"L0058","section":"Money out, by month","text":"Oct 2026","placement":"unplaced"},
+        {"key":"L0059","section":"Money out, by month","text":"Nov 2026","placement":"unplaced"},
+        {"key":"L0060","section":"Money out, by month","text":"Each month is recorded spend ({…} over these {…} months) plus payouts and fees out of the project account. Read from the cost log and the account’s own record.","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":513,"string_id":"1f3b826a05d4"},
+        {"key":"L0061","section":"Danger zone","text":"Danger zone","placement":"placed","file":"modules/hall-ui/public/project-settings.html","line":69,"string_id":"13b22e48d9fb"},
+        {"key":"L0062","section":"Danger zone","text":"This project is hosted on {…}, and that is where it is taken offline or removed. Both links below open this project’s page there.","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":412,"string_id":"e97b2d549f10"},
+        {"key":"L0063","section":"Danger zone","text":"Manage this project on {…}","placement":"placed","file":"modules/hall-ui/public/project-settings.js","line":413,"string_id":"4e261fd15bd5"},
+        {"key":"L0064","section":"Danger zone","text":"Take it offline","placement":"placed","file":"modules/hall-ui/public/project-settings.html","line":72,"string_id":"da9da6e866bd"},
+        {"key":"L0065","section":"Danger zone","text":"— stops the project and its nightly backups but keeps everything: its database, its backups and your repository on GitHub. You can bring it back.","placement":"placed","file":"modules/hall-ui/public/project-settings.html","line":72,"string_id":"61ebc5d684fd"},
+        {"key":"L0066","section":"Danger zone","text":"Disconnect from Bongos entirely","placement":"placed","file":"modules/hall-ui/public/project-settings.html","line":73,"string_id":"d3efd513694b"},
+        {"key":"L0067","section":"Danger zone","text":"— erases the project’s server, its database and every backup, and releases its name and web address. Your repository on GitHub is kept. This cannot be undone.","placement":"placed","file":"modules/hall-ui/public/project-settings.html","line":73,"string_id":"d9ad3ee37a88"},
+        {"key":"L0068","section":"footer","text":"Sign out","placement":"shared","file":"modules/hall-ui/public/shell.js","line":520,"string_id":"1883ad7f07fc"},
+        {"key":"L0069","section":"Danger zone","text":"Builders hall · this session","placement":"placed","file":"modules/hall-ui/public/craft-mode.js","line":670,"string_id":"fd1903586e8e"},
+        {"key":"L0070","section":"What are you doing now?","text":"What are you doing now?","placement":"placed","file":"modules/hall-ui/public/craft-mode.js","line":671,"string_id":"60853319f290"},
+        {"key":"L0071","section":"What are you doing now?","text":"Pick one. You can switch any time from the top bar.","placement":"placed","file":"modules/hall-ui/public/craft-mode.js","line":672,"string_id":"4f87d5b17b54"},
+        {"key":"L0072","section":"What are you doing now?","text":"Building","placement":"unplaced"},
+        {"key":"L0073","section":"What are you doing now?","text":"{…} and {…}","placement":"placed","file":"modules/hall-ui/public/profile-nudge.js","line":77,"string_id":"56b00d773232","occurrences":3},
+        {"key":"L0074","section":"What are you doing now?","text":"Artistry","placement":"unplaced"},
+        {"key":"L0075","section":"What are you doing now?","text":"Ideating","placement":"unplaced"},
+        {"key":"L0076","section":"What are you doing now?","text":"Turn thoughts into ideas.","placement":"unplaced"},
+        {"key":"L0077","section":"What are you doing now?","text":"Ask me again next session","placement":"placed","file":"modules/hall-ui/public/craft-mode.js","line":675,"string_id":"fa86bf403775"}
       ]
     },
     {

package/migrations/core_291_payout_nda_tax.sql

@@ -0,0 +1,75 @@
+-- core_291_payout_nda_tax.sql — contractor pay: an NDA on file and tax details
+-- collected before the first payout (task 1004908, goal 1000092 N4; ADR 0385,
+-- the "Contractor pay" row of the per-flow map).
+--
+-- WHY. The owner's legal framework (cited by Article only) puts two more papers
+-- in front of paying our own contractors: an NDA recorded for the person (the
+-- beta overlay, Art. XI) and identity and tax details collected through the
+-- processor's onboarding. Both join the gates core_284 built: a payout to someone
+-- without them is held, and the hold tells them why (no silent stop).
+--
+-- SHAPE. Two append-only tables (a correction is a new row; the latest row wins),
+-- under core_284's shared refuse-change trigger:
+--
+--   payout_ndas         whether a signed NDA is on file for a builder: on_file or
+--                       withdrawn, which version, and where the signed copy lives
+--                       (a reference such as an e-signature envelope id). The NDA's
+--                       own text is never stored here.
+--   payout_tax_details  whether the processor's onboarding has collected the
+--                       person's identity and tax details: collected or incomplete,
+--                       who says so (the processor once one is wired, or a person
+--                       who checked), and the processor's onboarding reference.
+--                       There is NO column for a tax id, and the reference refuses
+--                       anything that looks like one: the processor holds those
+--                       details, Bongos only records that they exist.
+--
+-- Neither table records a rate, a schedule or a refusal to take work: they are
+-- independent contractors (Art. IV), and these papers only gate money moving.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS payout_ndas (
+  id           bigserial   PRIMARY KEY,
+  builder_id   bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  status       text        NOT NULL CHECK (status IN ('on_file', 'withdrawn')),
+  nda_version  text        NOT NULL CHECK (nda_version ~ '^[A-Za-z0-9._-]{1,40}$'),
+  reference    text        CHECK (reference IS NULL OR length(reference) <= 200),
+  recorded_by  bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  recorded_at  timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT payout_ndas_not_self CHECK (recorded_by <> builder_id)
+);
+CREATE INDEX IF NOT EXISTS payout_ndas_builder_idx ON payout_ndas (builder_id, id DESC);
+
+CREATE TABLE IF NOT EXISTS payout_tax_details (
+  id            bigserial   PRIMARY KEY,
+  builder_id    bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  status        text        NOT NULL CHECK (status IN ('collected', 'incomplete')),
+  collected_by  text        NOT NULL CHECK (collected_by ~ '^(processor|person):[A-Za-z0-9._-]{1,60}$'),
+  reference     text        CHECK (reference IS NULL OR length(reference) <= 200),
+  recorded_by   bigint      REFERENCES builders(id) ON DELETE RESTRICT,
+  recorded_at   timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT payout_tax_details_not_self CHECK (recorded_by IS NULL OR recorded_by <> builder_id),
+  -- nine digits in a row (dashes and spaces ignored) is the shape of a US tax id
+  CONSTRAINT payout_tax_details_no_tax_id CHECK (reference IS NULL OR regexp_replace(reference, '[\s-]', '', 'g') !~ '[0-9]{9}')
+);
+CREATE INDEX IF NOT EXISTS payout_tax_details_builder_idx ON payout_tax_details (builder_id, id DESC);
+
+DO $$
+DECLARE t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY['payout_ndas', 'payout_tax_details'] LOOP
+    EXECUTE format('DROP TRIGGER IF EXISTS %I ON %I', t || '_no_update_delete', t);
+    EXECUTE format('CREATE TRIGGER %I BEFORE UPDATE OR DELETE ON %I FOR EACH ROW EXECUTE FUNCTION payout_gates_refuse_change()', t || '_no_update_delete', t);
+    EXECUTE format('DROP TRIGGER IF EXISTS %I ON %I', t || '_no_truncate', t);
+    EXECUTE format('CREATE TRIGGER %I BEFORE TRUNCATE ON %I FOR EACH STATEMENT EXECUTE FUNCTION payout_gates_refuse_change()', t || '_no_truncate', t);
+    EXECUTE format('REVOKE UPDATE, DELETE, TRUNCATE ON %I FROM PUBLIC', t);
+  END LOOP;
+END;
+$$;
+
+-- A hold may now name the two new reasons.
+ALTER TABLE payout_freezes DROP CONSTRAINT IF EXISTS payout_freezes_reason_check;
+ALTER TABLE payout_freezes ADD CONSTRAINT payout_freezes_reason_check
+  CHECK (reason IN ('sanctions_match', 'sanctions_unscreened', 'age_no_money', 'age_needs_guardian', 'age_unknown', 'nda_missing', 'tax_details_missing', 'manual'));
+
+COMMIT;

package/migrations/core_292_module_sale_payouts.sql

@@ -0,0 +1,170 @@
+-- core_292_module_sale_payouts.sql — a module sale is split by the project's own rule, and
+-- each contributor and the seller is paid their share, exactly once, through the same
+-- approved payout path as a task (task 1004910, goal 1000092 N6; ADR 0388, ADR 0385 D4,
+-- ADR 0397 D7).
+--
+-- FOUR TABLES, ALL APPEND-ONLY (the builder_payouts_append_only() refusal from core_290).
+--
+--   module_split_rules        the project's rule for one module: the seller, the seller's
+--                             share and the contributors' pool, in basis points of the
+--                             price (they add to 10000: the platform fee is paid by the
+--                             buyer ON TOP and is never in here, ADR 0388 D1), and the
+--                             credit row kinds the pool counts as weight (ADR 0387 D5).
+--                             The newest row per module is the rule now; a sale keeps the
+--                             rule it sold under (D2), so a rule is never edited.
+--   module_sales              one row per sale the processor reported: the price the
+--                             seller and contributors share, the platform fee kept apart,
+--                             and the rule it sold under. One row per processor sale.
+--   module_sale_shares_owed   the owed-but-unpaid record (the M04 idea, keyed by sale
+--                             instead of task): one row per (sale, person, role), with the
+--                             weight inputs that produced it, so a person can check their
+--                             share from inputs they can see (Art. VIII). Written in the
+--                             same step as the sale, BEFORE anything is sent.
+--   module_share_attempts     every try at paying one share: sent / failed / held, as
+--                             builder_payout_attempts. At most one `sent` per share.
+--
+-- ONE APPROVAL PAYS ONE THING. A share is paid only under a person's logged approval for
+-- exactly that person and amount (payout_approvals). module_share_approvals binds one
+-- approval to one share, and a trigger on each side refuses an approval already spent by
+-- the other (a task payout, core_290, or a share here), so no approval pays twice.
+--
+-- Additive (new tables, two triggers on core_290's table, three indexes for the weight
+-- read). Idempotent.
+
+CREATE TABLE IF NOT EXISTS module_split_rules (
+  id                BIGSERIAL   PRIMARY KEY,
+  module_key        TEXT        NOT NULL REFERENCES store_modules(module_key),
+  seller_id         BIGINT      NOT NULL REFERENCES builders(id),
+  seller_bps        INTEGER     NOT NULL,
+  contributors_bps  INTEGER     NOT NULL,
+  credit_row_kinds  TEXT[]      NOT NULL,
+  set_by            BIGINT      NOT NULL REFERENCES builders(id),
+  created_at        TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT module_split_rules_bps_chk CHECK (
+    seller_bps BETWEEN 0 AND 10000 AND contributors_bps BETWEEN 0 AND 10000 AND seller_bps + contributors_bps = 10000),
+  CONSTRAINT module_split_rules_kinds_chk CHECK (cardinality(credit_row_kinds) BETWEEN 1 AND 10)
+);
+CREATE INDEX IF NOT EXISTS module_split_rules_current ON module_split_rules (module_key, created_at DESC, id DESC);
+
+CREATE TABLE IF NOT EXISTS module_sales (
+  id                  BIGSERIAL   PRIMARY KEY,
+  module_key          TEXT        NOT NULL REFERENCES store_modules(module_key),
+  processor_sale_ref  TEXT        NOT NULL,
+  price_cents         BIGINT      NOT NULL,
+  platform_fee_cents  BIGINT      NOT NULL DEFAULT 0,
+  currency            TEXT        NOT NULL,
+  rule_id             BIGINT      NOT NULL REFERENCES module_split_rules(id),
+  pool_unassigned_cents BIGINT    NOT NULL DEFAULT 0,
+  recorded_by         BIGINT      NOT NULL REFERENCES builders(id),
+  created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT module_sales_price_chk CHECK (price_cents > 0),
+  CONSTRAINT module_sales_fee_chk CHECK (platform_fee_cents >= 0),
+  CONSTRAINT module_sales_unassigned_chk CHECK (pool_unassigned_cents >= 0 AND pool_unassigned_cents <= price_cents),
+  CONSTRAINT module_sales_currency_chk CHECK (currency ~ '^[A-Z]{3}$'),
+  CONSTRAINT module_sales_ref_chk CHECK (length(processor_sale_ref) BETWEEN 1 AND 200)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS module_sales_one_per_ref ON module_sales (processor_sale_ref);
+CREATE INDEX IF NOT EXISTS module_sales_by_time ON module_sales (created_at DESC, id DESC);
+
+CREATE TABLE IF NOT EXISTS module_sale_shares_owed (
+  id            BIGSERIAL   PRIMARY KEY,
+  sale_id       BIGINT      NOT NULL REFERENCES module_sales(id),
+  recipient_id  BIGINT      NOT NULL REFERENCES builders(id),
+  role          TEXT        NOT NULL,
+  amount_cents  BIGINT      NOT NULL,
+  currency      TEXT        NOT NULL,
+  weight        BIGINT,
+  weight_total  BIGINT,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  CONSTRAINT module_sale_shares_role_chk CHECK (role IN ('seller', 'contributor')),
+  CONSTRAINT module_sale_shares_amount_chk CHECK (amount_cents > 0),
+  CONSTRAINT module_sale_shares_currency_chk CHECK (currency ~ '^[A-Z]{3}$'),
+  -- a contributor's share shows the weight that produced it; a seller's share has none
+  CONSTRAINT module_sale_shares_weight_chk CHECK (
+    (role = 'seller' AND weight IS NULL AND weight_total IS NULL) OR
+    (role = 'contributor' AND weight > 0 AND weight_total >= weight))
+);
+CREATE UNIQUE INDEX IF NOT EXISTS module_sale_shares_one_per_role ON module_sale_shares_owed (sale_id, recipient_id, role);
+CREATE INDEX IF NOT EXISTS module_sale_shares_by_recipient ON module_sale_shares_owed (recipient_id, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS module_share_approvals (
+  share_id      BIGINT      PRIMARY KEY REFERENCES module_sale_shares_owed(id),
+  approval_id   BIGINT      NOT NULL REFERENCES payout_approvals(id),
+  bound_by      BIGINT      NOT NULL REFERENCES builders(id),
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS module_share_approvals_one_per_approval ON module_share_approvals (approval_id);
+
+CREATE TABLE IF NOT EXISTS module_share_attempts (
+  id            BIGSERIAL   PRIMARY KEY,
+  share_id      BIGINT      NOT NULL REFERENCES module_sale_shares_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 module_share_attempts_outcome_chk CHECK (outcome IN ('sent', 'failed', 'held')),
+  CONSTRAINT module_share_attempts_reason_len_chk CHECK (reason IS NULL OR length(reason) <= 300),
+  CONSTRAINT module_share_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))
+);
+CREATE UNIQUE INDEX IF NOT EXISTS module_share_attempts_one_sent ON module_share_attempts (share_id) WHERE outcome = 'sent';
+CREATE INDEX IF NOT EXISTS module_share_attempts_by_share ON module_share_attempts (share_id, id DESC);
+
+DROP TRIGGER IF EXISTS module_split_rules_no_rewrite ON module_split_rules;
+CREATE TRIGGER module_split_rules_no_rewrite BEFORE UPDATE OR DELETE ON module_split_rules
+  FOR EACH ROW EXECUTE FUNCTION builder_payouts_append_only();
+DROP TRIGGER IF EXISTS module_sales_no_rewrite ON module_sales;
+CREATE TRIGGER module_sales_no_rewrite BEFORE UPDATE OR DELETE ON module_sales
+  FOR EACH ROW EXECUTE FUNCTION builder_payouts_append_only();
+DROP TRIGGER IF EXISTS module_sale_shares_owed_no_rewrite ON module_sale_shares_owed;
+CREATE TRIGGER module_sale_shares_owed_no_rewrite BEFORE UPDATE OR DELETE ON module_sale_shares_owed
+  FOR EACH ROW EXECUTE FUNCTION builder_payouts_append_only();
+DROP TRIGGER IF EXISTS module_share_approvals_no_rewrite ON module_share_approvals;
+CREATE TRIGGER module_share_approvals_no_rewrite BEFORE UPDATE OR DELETE ON module_share_approvals
+  FOR EACH ROW EXECUTE FUNCTION builder_payouts_append_only();
+DROP TRIGGER IF EXISTS module_share_attempts_no_rewrite ON module_share_attempts;
+CREATE TRIGGER module_share_attempts_no_rewrite BEFORE UPDATE OR DELETE ON module_share_attempts
+  FOR EACH ROW EXECUTE FUNCTION builder_payouts_append_only();
+
+-- The contributors' weight read (module-payouts.js WEIGHTS_SQL) runs on every split preview
+-- and every sale. These two make each of its steps an index lookup instead of a scan of an
+-- ever-growing table: a module's shipped tasks, and the sessions that shipped any of them.
+-- (credit_log by task is idx_credit_log_task, core_189.) credit_log by session_id is only
+-- indexed for one reason (uniq_credit_session_token_reward, a partial index a bound reason
+-- list cannot use), so a plain one is added too.
+CREATE INDEX IF NOT EXISTS idx_tasks_shipped_module ON tasks (module_key)
+  WHERE module_key IS NOT NULL AND status = 'shipped';
+CREATE INDEX IF NOT EXISTS idx_session_records_task_ids ON session_records USING gin (task_ids);
+CREATE INDEX IF NOT EXISTS idx_credit_log_session ON credit_log (session_id)
+  WHERE session_id IS NOT NULL;
+
+-- one approval pays one thing, across a task payout and a module share. Each table's unique
+-- index stops a second use WITHIN it; across the two, an EXISTS alone would race (two
+-- transactions, one per table, each blind to the other's uncommitted row). So both sides
+-- first take a transaction lock on the approval id: the second waits for the first to
+-- commit, and its EXISTS then runs on a fresh snapshot that sees the row.
+CREATE OR REPLACE FUNCTION payout_approval_spent_once() RETURNS trigger AS $$
+BEGIN
+  PERFORM pg_advisory_xact_lock(1004910, hashtext(NEW.approval_id::text));
+  IF TG_TABLE_NAME = 'module_share_approvals' THEN
+    IF EXISTS (SELECT 1 FROM builder_payouts_owed WHERE approval_id = NEW.approval_id) THEN
+      RAISE EXCEPTION 'approval % already pays a task; one approval pays one thing', NEW.approval_id;
+    END IF;
+  ELSIF EXISTS (SELECT 1 FROM module_share_approvals WHERE approval_id = NEW.approval_id) THEN
+    RAISE EXCEPTION 'approval % already pays a module share; one approval pays one thing', NEW.approval_id;
+  END IF;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS module_share_approvals_spent_once ON module_share_approvals;
+CREATE TRIGGER module_share_approvals_spent_once BEFORE INSERT ON module_share_approvals
+  FOR EACH ROW EXECUTE FUNCTION payout_approval_spent_once();
+DROP TRIGGER IF EXISTS builder_payouts_owed_spent_once ON builder_payouts_owed;
+CREATE TRIGGER builder_payouts_owed_spent_once BEFORE INSERT ON builder_payouts_owed
+  FOR EACH ROW EXECUTE FUNCTION payout_approval_spent_once();
+
+INSERT INTO schema_migrations (version) VALUES ('core_292_module_sale_payouts')
+  ON CONFLICT DO NOTHING;

package/migrations/core_293_cash_outs.sql

@@ -0,0 +1,184 @@
+-- core_293_cash_outs.sql — a person withdraws their own balance to their bank, with
+-- holds, a minimum and a record of every failure (task 1004911, goal 1000092 N7;
+-- ADR 0385 D1/D8, ADR 0397 D2/D7).
+--
+-- NO MONEY IS HERE. The person's money sits in their own processor-held connected
+-- account (ADR 0397 D2); a cash-out asks the processor to pay it out from there to the
+-- bank the person gave the processor. Bongos never holds it, never sees the bank
+-- details, and never sums these rows into a balance.
+--
+--   payout_approvals  gains one kind, `cashout_approved`: the person's own logged,
+--                     personal approval of ONE withdrawal of THEIR OWN money (N9). The
+--                     approver and the recipient are the same person, by CHECK, so it
+--                     can never be read as the project paying someone.
+--   cash_outs         one row per withdrawal a person asked for, written before the
+--                     processor is asked, citing that approval. One approval, one
+--                     withdrawal; one instruction id, one withdrawal.
+--   cash_out_attempts every try at carrying it out and everything the processor said:
+--                     held (a gate or no processor), failed (no answer we can trust),
+--                     refused (the processor said no and made nothing), sent (a payout
+--                     exists), paid (it reached the bank), returned (the bank sent it
+--                     back), cancelled (the person withdrew the request).
+--
+-- A RETRY CANNOT PAY TWICE. Each try has a number, and the processor is called with an
+-- idempotency key made from the withdrawal id and that number. The database computes
+-- the number itself: 1 + the tries the processor has already said created no money
+-- movement (refused) or were sent back (returned). So a timeout, or any answer we
+-- cannot trust, retries with the SAME key and the processor hands back the payout it
+-- already made; a new key exists only once the processor has said the last one did not
+-- pay. While a try is sent and not returned, nothing but paid or returned may follow.
+--
+-- A FAILURE IS A RECORD. A withdrawal that has not reached the bank stays on the
+-- person's list with what happened, in plain words, until it is paid or they cancel it;
+-- the money was never taken from their balance. All three tables are append-only.
+
+BEGIN;
+
+ALTER TABLE payout_approvals DROP CONSTRAINT IF EXISTS payout_approvals_kind_check;
+ALTER TABLE payout_approvals ADD CONSTRAINT payout_approvals_kind_check CHECK (kind IN (
+  'rule_signed', 'rule_narrowed', 'rule_revoked',
+  'run_noticed', 'run_held',
+  'payout_approved', 'grant_signed', 'contract_signed',
+  'cashout_approved'));
+
+ALTER TABLE payout_approvals DROP CONSTRAINT IF EXISTS payout_approvals_shape;
+ALTER TABLE payout_approvals ADD CONSTRAINT payout_approvals_shape CHECK (
+  (kind = 'rule_signed'     AND rule_id IS NULL AND run_key IS NULL AND recipient_id IS NULL AND amount_cents IS NULL AND terms <> '{}'::jsonb) OR
+  (kind = 'rule_narrowed'   AND rule_id IS NOT NULL AND run_key IS NULL AND recipient_id IS NULL AND amount_cents IS NULL AND terms <> '{}'::jsonb) OR
+  (kind = 'rule_revoked'    AND rule_id IS NOT NULL AND run_key IS NULL AND recipient_id IS NULL AND amount_cents IS NULL) OR
+  (kind = 'run_noticed'     AND rule_id IS NOT NULL AND run_key IS NOT NULL AND amount_cents IS NOT NULL AND currency IS NOT NULL) OR
+  (kind = 'run_held'        AND rule_id IS NOT NULL AND run_key IS NOT NULL AND amount_cents IS NULL) OR
+  (kind = 'payout_approved' AND rule_id IS NULL AND recipient_id IS NOT NULL AND amount_cents IS NOT NULL AND currency IS NOT NULL) OR
+  (kind IN ('grant_signed', 'contract_signed') AND rule_id IS NULL AND recipient_id IS NOT NULL AND terms <> '{}'::jsonb) OR
+  -- a person approves taking out their OWN money: approver and recipient are one person
+  (kind = 'cashout_approved' AND rule_id IS NULL AND run_key IS NULL AND recipient_id IS NOT NULL
+                             AND recipient_id = actor_id AND amount_cents IS NOT NULL AND currency IS NOT NULL)
+);
+
+CREATE TABLE IF NOT EXISTS cash_outs (
+  id             bigserial   PRIMARY KEY,
+  builder_id     bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  approval_id    bigint      NOT NULL REFERENCES payout_approvals(id) ON DELETE RESTRICT,
+  from_account   text        NOT NULL CHECK (from_account ~ '^[A-Za-z0-9_.:-]{3,200}$'),
+  amount_cents   bigint      NOT NULL CHECK (amount_cents > 0),
+  currency       text        NOT NULL CHECK (currency ~ '^[A-Z]{3}$'),
+  instruction_id text        NOT NULL CHECK (instruction_id ~ '^[A-Za-z0-9_-]{8,80}$'),
+  created_at     timestamptz NOT NULL DEFAULT now()
+);
+
+-- one approval pays one withdrawal; one press of the button is one withdrawal
+CREATE UNIQUE INDEX IF NOT EXISTS cash_outs_one_per_approval ON cash_outs (approval_id);
+CREATE UNIQUE INDEX IF NOT EXISTS cash_outs_one_per_instruction ON cash_outs (builder_id, instruction_id);
+CREATE INDEX IF NOT EXISTS cash_outs_by_builder ON cash_outs (builder_id, id DESC);
+
+-- The approval a withdrawal cites must be this person's own cash-out approval for this
+-- exact amount: an owner's payout approval, or someone else's, can never be spent here.
+CREATE OR REPLACE FUNCTION cash_outs_check_approval() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE a record;
+BEGIN
+  SELECT kind, actor_id, recipient_id, amount_cents, currency INTO a FROM payout_approvals WHERE id = NEW.approval_id;
+  IF a IS NULL OR a.kind <> 'cashout_approved' OR a.recipient_id <> NEW.builder_id OR a.actor_id <> NEW.builder_id
+     OR a.amount_cents <> NEW.amount_cents OR a.currency <> NEW.currency THEN
+    RAISE EXCEPTION 'a cash-out must cite the person''s own approval of exactly this withdrawal'
+      USING ERRCODE = 'check_violation';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS cash_outs_approval ON cash_outs;
+CREATE TRIGGER cash_outs_approval BEFORE INSERT ON cash_outs
+  FOR EACH ROW EXECUTE FUNCTION cash_outs_check_approval();
+
+CREATE TABLE IF NOT EXISTS cash_out_attempts (
+  id            bigserial   PRIMARY KEY,
+  cash_out_id   bigint      NOT NULL REFERENCES cash_outs(id) ON DELETE RESTRICT,
+  try_no        integer     NOT NULL CHECK (try_no >= 1),
+  outcome       text        NOT NULL CHECK (outcome IN ('held', 'failed', 'refused', 'sent', 'paid', 'returned', 'cancelled')),
+  processor_ref text        CHECK (processor_ref IS NULL OR length(processor_ref) BETWEEN 1 AND 200),
+  reason        text        CHECK (reason IS NULL OR length(reason) BETWEEN 1 AND 300),
+  actor_id      bigint      REFERENCES builders(id) ON DELETE RESTRICT,
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  -- a payout names the processor's payout; anything that did not pay says why
+  CONSTRAINT cash_out_attempts_cause_chk CHECK (
+    (outcome IN ('sent', 'paid') AND processor_ref IS NOT NULL) OR
+    (outcome = 'returned' AND processor_ref IS NOT NULL AND reason IS NOT NULL) OR
+    (outcome IN ('held', 'failed', 'refused', 'cancelled') AND processor_ref IS NULL AND reason IS NOT NULL))
+);
+
+-- one payout per try, one arrival per try, one cancellation, and one processor payout
+-- settles one try of one withdrawal
+CREATE UNIQUE INDEX IF NOT EXISTS cash_out_attempts_one_sent ON cash_out_attempts (cash_out_id, try_no) WHERE outcome = 'sent';
+CREATE UNIQUE INDEX IF NOT EXISTS cash_out_attempts_one_paid ON cash_out_attempts (cash_out_id, try_no) WHERE outcome = 'paid';
+CREATE UNIQUE INDEX IF NOT EXISTS cash_out_attempts_one_returned ON cash_out_attempts (cash_out_id, try_no) WHERE outcome = 'returned';
+CREATE UNIQUE INDEX IF NOT EXISTS cash_out_attempts_one_cancel ON cash_out_attempts (cash_out_id) WHERE outcome = 'cancelled';
+CREATE UNIQUE INDEX IF NOT EXISTS cash_out_attempts_ref_once ON cash_out_attempts (processor_ref) WHERE outcome = 'sent';
+CREATE INDEX IF NOT EXISTS cash_out_attempts_by_cash_out ON cash_out_attempts (cash_out_id, id DESC);
+
+-- The order of a withdrawal, kept by the database whatever code writes here.
+CREATE OR REPLACE FUNCTION cash_out_attempts_check_order() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE
+  cur_try integer;
+  sent_ref text;
+BEGIN
+  -- serialise every write to one withdrawal, so two checks cannot both pass
+  PERFORM 1 FROM cash_outs WHERE id = NEW.cash_out_id FOR UPDATE;
+
+  IF EXISTS (SELECT 1 FROM cash_out_attempts WHERE cash_out_id = NEW.cash_out_id AND outcome = 'cancelled') THEN
+    RAISE EXCEPTION 'this cash-out was cancelled; nothing may follow it' USING ERRCODE = 'check_violation';
+  END IF;
+
+  -- the current try: a new key only after the processor said the last one did not pay
+  SELECT 1 + count(*) INTO cur_try FROM cash_out_attempts
+   WHERE cash_out_id = NEW.cash_out_id AND outcome IN ('refused', 'returned');
+  IF NEW.try_no <> cur_try THEN
+    RAISE EXCEPTION 'a cash-out attempt must be on try % (the processor has not said try % did not pay)', cur_try, NEW.try_no
+      USING ERRCODE = 'check_violation';
+  END IF;
+
+  SELECT processor_ref INTO sent_ref FROM cash_out_attempts
+   WHERE cash_out_id = NEW.cash_out_id AND try_no = cur_try AND outcome = 'sent';
+
+  IF NEW.outcome IN ('paid', 'returned') THEN
+    IF sent_ref IS NULL OR sent_ref <> NEW.processor_ref THEN
+      RAISE EXCEPTION 'only the payout this try sent can arrive or come back' USING ERRCODE = 'check_violation';
+    END IF;
+  ELSIF sent_ref IS NOT NULL THEN
+    -- the try is sent and not returned (a return would have moved cur_try on)
+    RAISE EXCEPTION 'this cash-out is already sent; only its arrival or return may follow' USING ERRCODE = 'check_violation';
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS cash_out_attempts_order ON cash_out_attempts;
+CREATE TRIGGER cash_out_attempts_order BEFORE INSERT ON cash_out_attempts
+  FOR EACH ROW EXECUTE FUNCTION cash_out_attempts_check_order();
+
+CREATE OR REPLACE FUNCTION cash_outs_append_only() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  RAISE EXCEPTION '% is append-only: a cash-out is never edited or deleted, a new attempt is recorded instead', TG_TABLE_NAME
+    USING ERRCODE = 'insufficient_privilege';
+END;
+$$;
+
+DROP TRIGGER IF EXISTS cash_outs_no_rewrite ON cash_outs;
+CREATE TRIGGER cash_outs_no_rewrite BEFORE UPDATE OR DELETE ON cash_outs
+  FOR EACH ROW EXECUTE FUNCTION cash_outs_append_only();
+DROP TRIGGER IF EXISTS cash_out_attempts_no_rewrite ON cash_out_attempts;
+CREATE TRIGGER cash_out_attempts_no_rewrite BEFORE UPDATE OR DELETE ON cash_out_attempts
+  FOR EACH ROW EXECUTE FUNCTION cash_outs_append_only();
+DROP TRIGGER IF EXISTS cash_outs_no_truncate ON cash_outs;
+CREATE TRIGGER cash_outs_no_truncate BEFORE TRUNCATE ON cash_outs
+  FOR EACH STATEMENT EXECUTE FUNCTION cash_outs_append_only();
+DROP TRIGGER IF EXISTS cash_out_attempts_no_truncate ON cash_out_attempts;
+CREATE TRIGGER cash_out_attempts_no_truncate BEFORE TRUNCATE ON cash_out_attempts
+  FOR EACH STATEMENT EXECUTE FUNCTION cash_outs_append_only();
+
+INSERT INTO schema_migrations (version) VALUES ('core_293_cash_outs')
+  ON CONFLICT DO NOTHING;
+
+COMMIT;

package/migrations/core_294_cash_out_attempts_sent_by_time.sql

@@ -0,0 +1,21 @@
+-- core_294_cash_out_attempts_sent_by_time.sql — the daily ledger check reads sent cash-outs
+-- by time without scanning every attempt (task 1004912, goal 1000092 N8).
+--
+-- The economy module's daily check (modules/economy/ledger-check.js) reads each `sent`
+-- cash-out attempt of the last week to compare it with the processor's payouts. The table is
+-- append-only and keeps every try forever, and its only `sent` index is by reference, so the
+-- week's read would scan the whole table. A partial index over just the sent rows by time
+-- lets it read those alone. A core migration because cash_out_attempts is core's table
+-- (core_293), however much the economy module wants the index.
+--
+-- Additive: one index, nothing else.
+
+BEGIN;
+
+CREATE INDEX IF NOT EXISTS cash_out_attempts_sent_by_time
+  ON cash_out_attempts (created_at) WHERE outcome = 'sent';
+
+INSERT INTO schema_migrations (version) VALUES ('core_294_cash_out_attempts_sent_by_time')
+  ON CONFLICT DO NOTHING;
+
+COMMIT;