@bongos/core 1.21.113 → 1.21.114

package/modules/government/migrations/government_027_laws.sql

@@ -0,0 +1,143 @@
+-- government_027_laws.sql — standing orders: the project's laws for its AI
+-- agents, changed only by a passed amendment (task 1004706, goal 1000111).
+--
+-- WHAT THIS ADDS
+--
+--   1. government_amendments.kind gains 'laws' — an amendment that enacts new
+--      laws, repeals laws in force, or both. One amendments table, one subject
+--      type, one pass path: a laws amendment is decided by the board IN FORCE
+--      exactly like any other amendment (government_023's pattern).
+--
+--   2. government_laws — ONE ROW PER LAW, ever. A law is a short one-line rule
+--      every AI agent on the project obeys, an optional line saying what it
+--      means for an agent, and the personal settings it LOCKS (a JSON list of
+--      { setting, value } or { setting, max }). Each row records WHO passed it
+--      and WHEN: the board item that passed it (passed_by_item_id — its
+--      snapshotted constitution is the government that decided it, its yes
+--      votes are who said yes), the proposer, and passed_at. A repeal records
+--      the item that repealed it and when; the row stays on the record.
+--
+--   3. A GUARD TRIGGER: a law is written ONLY by a passed laws amendment.
+--        INSERT — passed_by_item_id must be a CLOSED, PASSED constitutional
+--                 amendment whose amendment row is of kind 'laws'; the row is
+--                 born in force (no repeal) and passed_at is the database clock.
+--        UPDATE — only a repeal: a law in force gains repealed_by_item_id (a
+--                 passed laws amendment) and repealed_at; nothing else about
+--                 it may change, and a repealed law never changes again.
+--        DELETE — refused outright. A law leaves force by a repeal, on the record.
+--      There is no route that writes this table, and the trigger makes that
+--      structural: a hand-written INSERT or UPDATE is refused too.
+--
+-- No law is seeded here: the first laws are the owner's to ratify (task
+-- 1004708). Additive and idempotent: a new table, a CHECK that only WIDENS
+-- (dropped and re-added under the same name, the government_020 pattern), and
+-- CREATE OR REPLACE for the trigger function and trigger (Postgres 14+;
+-- production runs 16).
+
+BEGIN;
+
+-- ---------------------------------------------------------------------------
+-- 1. amendments: a third kind
+-- ---------------------------------------------------------------------------
+ALTER TABLE government_amendments
+  DROP CONSTRAINT IF EXISTS government_amendments_kind_check;
+
+ALTER TABLE government_amendments
+  ADD CONSTRAINT government_amendments_kind_check
+  CHECK (kind IN ('constitution', 'decision_rules', 'laws'));
+
+-- ---------------------------------------------------------------------------
+-- 2. the law book
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS government_laws (
+  id                   bigserial   PRIMARY KEY,
+  -- one line: what every agent obeys
+  text                 text        NOT NULL
+                       CHECK (char_length(btrim(text)) BETWEEN 3 AND 100 AND text !~ '[\r\n]'),
+  -- one line: what it means for an agent (display; the session reads it, 1004707)
+  effect_on_ai         text        CHECK (effect_on_ai IS NULL OR (char_length(effect_on_ai) BETWEEN 1 AND 200 AND effect_on_ai !~ '[\r\n]')),
+  -- the personal settings it locks: [{ "setting": k, "value": v } | { "setting": k, "max": m }]
+  locks                jsonb       NOT NULL DEFAULT '[]'::jsonb
+                       CHECK (jsonb_typeof(locks) = 'array' AND jsonb_array_length(locks) <= 8),
+  proposed_by          bigint      REFERENCES builders(id) ON DELETE SET NULL,
+  -- WHO passed it: the passed laws amendment's board item (its constitution
+  -- snapshot is the government that decided it; its yes votes, who said yes)
+  passed_by_item_id    bigint      NOT NULL REFERENCES government_board_items(id) ON DELETE RESTRICT,
+  -- WHEN: the database clock at the close that passed it (set by the trigger)
+  passed_at            timestamptz NOT NULL DEFAULT now(),
+  repealed_by_item_id  bigint      REFERENCES government_board_items(id) ON DELETE RESTRICT,
+  repealed_at          timestamptz,
+
+  CONSTRAINT government_laws_repeal_shape CHECK ((repealed_by_item_id IS NULL) = (repealed_at IS NULL))
+);
+
+-- The laws in force, in the order they passed (the read every session will make).
+CREATE INDEX IF NOT EXISTS government_laws_in_force_idx
+  ON government_laws (passed_at, id) WHERE repealed_at IS NULL;
+
+-- ---------------------------------------------------------------------------
+-- 3. the guard: written only by a passed laws amendment
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION government_laws_passed_laws_item(p_item_id bigint) RETURNS boolean
+LANGUAGE sql STABLE AS $fn$
+  SELECT $1 IS NOT NULL AND EXISTS (
+    SELECT 1
+      FROM government_board_items i
+      JOIN government_amendments a ON a.id = i.subject_id
+     WHERE i.id = $1
+       AND i.subject_type = 'constitutional_amendment'
+       AND i.outcome = 'passed'
+       AND a.kind = 'laws'
+  )
+$fn$;
+
+CREATE OR REPLACE FUNCTION government_laws_guard() RETURNS trigger
+LANGUAGE plpgsql AS $guard$
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    RAISE EXCEPTION 'government_laws: a law cannot be deleted; it leaves force only by a passed repeal'
+      USING ERRCODE = 'check_violation';
+  END IF;
+
+  IF TG_OP = 'INSERT' THEN
+    IF NOT government_laws_passed_laws_item(NEW.passed_by_item_id) THEN
+      RAISE EXCEPTION 'government_laws changes only through a passed laws amendment (board item %)', NEW.passed_by_item_id
+        USING ERRCODE = 'check_violation';
+    END IF;
+    IF NEW.repealed_by_item_id IS NOT NULL OR NEW.repealed_at IS NOT NULL THEN
+      RAISE EXCEPTION 'government_laws: a law is born in force'
+        USING ERRCODE = 'check_violation';
+    END IF;
+    NEW.passed_at := now();
+    RETURN NEW;
+  END IF;
+
+  -- UPDATE: only a repeal of a law in force, by a passed laws amendment.
+  IF OLD.repealed_at IS NOT NULL THEN
+    RAISE EXCEPTION 'government_laws: law % was repealed and is closed to change', OLD.id
+      USING ERRCODE = 'check_violation';
+  END IF;
+  IF NEW.id IS DISTINCT FROM OLD.id
+     OR NEW.text IS DISTINCT FROM OLD.text
+     OR NEW.effect_on_ai IS DISTINCT FROM OLD.effect_on_ai
+     OR NEW.locks IS DISTINCT FROM OLD.locks
+     OR NEW.proposed_by IS DISTINCT FROM OLD.proposed_by
+     OR NEW.passed_by_item_id IS DISTINCT FROM OLD.passed_by_item_id
+     OR NEW.passed_at IS DISTINCT FROM OLD.passed_at THEN
+    RAISE EXCEPTION 'government_laws: a law in force cannot be edited; repeal it and pass a new one'
+      USING ERRCODE = 'check_violation';
+  END IF;
+  IF NOT government_laws_passed_laws_item(NEW.repealed_by_item_id) THEN
+    RAISE EXCEPTION 'government_laws changes only through a passed laws amendment (board item %)', NEW.repealed_by_item_id
+      USING ERRCODE = 'check_violation';
+  END IF;
+  NEW.repealed_at := now();
+  RETURN NEW;
+END
+$guard$;
+
+CREATE OR REPLACE TRIGGER government_laws_amendment_only
+  BEFORE INSERT OR UPDATE OR DELETE ON government_laws
+  FOR EACH ROW EXECUTE FUNCTION government_laws_guard();
+
+COMMIT;

package/modules/government/migrations/government_028_asks.sql

@@ -0,0 +1,57 @@
+-- government_028_asks.sql — THE ASK: one stored shape for every request an AI
+-- agent puts to a person (task 1004703, goal 1000111).
+--
+-- WHAT THIS ADDS
+--
+--   government_asks — ONE ROW PER DOCKET MATTER that carries an ask, keyed by
+--   the matter's docket id (`blockers:12`, `board:34`; docket.js normalizeMatter).
+--   An ask is a question of at most twelve words, two or three tap answers each
+--   with a one-line result, a pick and why, the seat it waits on, and what
+--   happens if nobody answers. The long text an agent first wrote may ride along
+--   as `detail`, never as the ask itself.
+--
+--   The full rule set is checked in modules/government/asks.js before a write
+--   (it names every fix). The CHECKs below are the structural floor under it, so
+--   a hand-written INSERT cannot store slop either: a question over twelve
+--   words, one that does not end in '?', a second line, fewer than two or more
+--   than three answers, a pick that is not one of the answers, a seat outside
+--   the routable grammar, or a missing "if nobody answers".
+--
+-- Additive and idempotent: a new table (IF NOT EXISTS) and its constraints
+-- declared with it. No row is seeded.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS government_asks (
+  -- the docket matter this ask is for: '<source>:<id>'
+  matter_id          text        PRIMARY KEY
+                     CHECK (matter_id ~ '^[a-z][a-z_]{1,39}:[A-Za-z0-9._-]{1,64}$'),
+  -- one question, at most twelve words, ending in a question mark
+  question           text        NOT NULL
+                     CHECK (char_length(question) BETWEEN 2 AND 160
+                            AND question !~ '[\r\n]'
+                            AND question ~ '\?$'
+                            AND array_length(regexp_split_to_array(btrim(question), '\s+'), 1) <= 12),
+  -- two or three tap answers: [{ key, label, result, act? }]
+  options            jsonb       NOT NULL
+                     CHECK (jsonb_typeof(options) = 'array' AND jsonb_array_length(options) BETWEEN 2 AND 3),
+  -- the pick (one of the answers' keys) and why, in one line
+  recommend_key      text        NOT NULL CHECK (recommend_key ~ '^[a-z][a-z0-9_-]{0,23}$'),
+  recommend_why      text        NOT NULL
+                     CHECK (char_length(btrim(recommend_why)) BETWEEN 1 AND 200 AND recommend_why !~ '[\r\n]'),
+  -- the seat it waits on: owner | lead:<building> | committee:<building>.<name> | board:<building>
+  waits_on           text        NOT NULL
+                     CHECK (waits_on ~ '^(owner|(lead|board):(charter|rules|disputes|people|planning|automation|review|release|treasury)|committee:(charter|rules|disputes|people|planning|automation|review|release|treasury)\.[a-z][a-z0-9_]{0,31})$'),
+  -- what happens if nobody answers, in one line
+  if_nobody_answers  text        NOT NULL
+                     CHECK (char_length(btrim(if_nobody_answers)) BETWEEN 1 AND 160 AND if_nobody_answers !~ '[\r\n]'),
+  -- the long text, riding along (never the ask)
+  detail             text        CHECK (detail IS NULL OR char_length(detail) <= 4000),
+  written_by         bigint      REFERENCES builders(id) ON DELETE SET NULL,
+  written_at         timestamptz NOT NULL DEFAULT now(),
+
+  -- the pick is one of the answers offered
+  CONSTRAINT government_asks_pick_offered CHECK (options @> jsonb_build_array(jsonb_build_object('key', recommend_key)))
+);
+
+COMMIT;

package/modules/government/migrations/government_029_leads.sql

@@ -0,0 +1,135 @@
+-- government_029_leads.sql — the Lead of each building, a held position the
+-- government appoints and removes by vote (task 1004709, goal 1000111).
+--
+-- WHAT THIS ADDS
+--
+--   government_leads — ONE ROW PER APPOINTMENT, ever. A building of the nine
+--   has at most one Lead in office (the partial unique index); a Lead carries a
+--   short charter (one line: what the Lead answers for). Each row records WHO
+--   appointed them and WHEN: the passed People matter's board item
+--   (appointed_by_item_id — its snapshotted constitution is the government that
+--   decided it, its yes votes who said yes) and appointed_at. Leaving office
+--   records the item that ended it (removed_by_item_id — a passed People matter
+--   that removed this Lead, or appointed the next one) and removed_at; the row
+--   stays on the record.
+--
+--   A GUARD TRIGGER: a Lead is written ONLY by a passed People matter that says so.
+--     INSERT — appointed_by_item_id must be a CLOSED, PASSED people_matter item
+--              whose matter's action is appoint_lead for exactly this building,
+--              builder and charter; the row is born in office, appointed_at is
+--              the database clock.
+--     UPDATE — only leaving office: a Lead in office gains removed_by_item_id (a
+--              passed people_matter whose action is remove_lead, or appoint_lead,
+--              for the same building) and removed_at; nothing else may change,
+--              and a row that left office never changes again.
+--     DELETE — refused outright. A Lead leaves office by a vote, on the record.
+--   There is no route that writes this table, and the trigger makes that
+--   structural: a hand-written INSERT or UPDATE is refused too.
+--
+-- No Lead is seated here: every building starts unseated, so it falls to the
+-- owner until the government appoints one. Additive and idempotent: a new
+-- table, CREATE OR REPLACE for the functions and the trigger (Postgres 14+;
+-- production runs 16).
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS government_leads (
+  id                    bigserial   PRIMARY KEY,
+  -- the building this Lead answers for (the nine, decision-rules.js AREAS)
+  building              text        NOT NULL
+                        CHECK (building IN ('charter', 'rules', 'disputes', 'people', 'planning',
+                                            'automation', 'review', 'release', 'treasury')),
+  builder_id            bigint      NOT NULL REFERENCES builders(id) ON DELETE RESTRICT,
+  -- the Lead's short charter: one line, what they answer for
+  charter               text        NOT NULL
+                        CHECK (char_length(btrim(charter)) BETWEEN 3 AND 140 AND charter !~ '[\r\n]'),
+  -- WHO appointed them: the passed People matter's board item
+  appointed_by_item_id  bigint      NOT NULL REFERENCES government_board_items(id) ON DELETE RESTRICT,
+  -- WHEN: the database clock when the appointment was carried out (the trigger)
+  appointed_at          timestamptz NOT NULL DEFAULT now(),
+  removed_by_item_id    bigint      REFERENCES government_board_items(id) ON DELETE RESTRICT,
+  removed_at            timestamptz,
+
+  CONSTRAINT government_leads_removal_shape CHECK ((removed_by_item_id IS NULL) = (removed_at IS NULL))
+);
+
+-- One Lead in office per building.
+CREATE UNIQUE INDEX IF NOT EXISTS government_leads_in_office_uniq
+  ON government_leads (building) WHERE removed_at IS NULL;
+
+-- An appointment is carried out once: one row per passed appointing item.
+CREATE UNIQUE INDEX IF NOT EXISTS government_leads_appointed_by_uniq
+  ON government_leads (appointed_by_item_id);
+
+-- The action of the passed People matter a board item decided, or NULL when the
+-- item is not a closed, passed people_matter.
+CREATE OR REPLACE FUNCTION government_leads_passed_people_action(p_item_id bigint) RETURNS jsonb
+LANGUAGE sql STABLE AS $fn$
+  SELECT m.action
+    FROM government_board_items i
+    JOIN government_matters m ON m.id = i.subject_id
+   WHERE i.id = $1
+     AND i.subject_type = 'people_matter'
+     AND i.outcome = 'passed'
+     AND m.area = 'people'
+$fn$;
+
+CREATE OR REPLACE FUNCTION government_leads_guard() RETURNS trigger
+LANGUAGE plpgsql AS $guard$
+DECLARE
+  act jsonb;
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    RAISE EXCEPTION 'government_leads: a Lead cannot be deleted; they leave office only by a passed People matter'
+      USING ERRCODE = 'check_violation';
+  END IF;
+
+  IF TG_OP = 'INSERT' THEN
+    act := government_leads_passed_people_action(NEW.appointed_by_item_id);
+    IF act IS NULL
+       OR act->>'type' IS DISTINCT FROM 'appoint_lead'
+       OR act->>'building' IS DISTINCT FROM NEW.building
+       OR act->>'builder_id' IS DISTINCT FROM NEW.builder_id::text
+       OR act->>'charter' IS DISTINCT FROM NEW.charter THEN
+      RAISE EXCEPTION 'government_leads changes only through a passed People matter that appoints this Lead (board item %)', NEW.appointed_by_item_id
+        USING ERRCODE = 'check_violation';
+    END IF;
+    IF NEW.removed_by_item_id IS NOT NULL OR NEW.removed_at IS NOT NULL THEN
+      RAISE EXCEPTION 'government_leads: a Lead is born in office'
+        USING ERRCODE = 'check_violation';
+    END IF;
+    NEW.appointed_at := now();
+    RETURN NEW;
+  END IF;
+
+  -- UPDATE: only leaving office, by a passed People matter for this building.
+  IF OLD.removed_at IS NOT NULL THEN
+    RAISE EXCEPTION 'government_leads: appointment % has ended and is closed to change', OLD.id
+      USING ERRCODE = 'check_violation';
+  END IF;
+  IF NEW.id IS DISTINCT FROM OLD.id
+     OR NEW.building IS DISTINCT FROM OLD.building
+     OR NEW.builder_id IS DISTINCT FROM OLD.builder_id
+     OR NEW.charter IS DISTINCT FROM OLD.charter
+     OR NEW.appointed_by_item_id IS DISTINCT FROM OLD.appointed_by_item_id
+     OR NEW.appointed_at IS DISTINCT FROM OLD.appointed_at THEN
+    RAISE EXCEPTION 'government_leads: a Lead in office cannot be edited; remove them and appoint again'
+      USING ERRCODE = 'check_violation';
+  END IF;
+  act := government_leads_passed_people_action(NEW.removed_by_item_id);
+  IF act IS NULL
+     OR act->>'type' NOT IN ('remove_lead', 'appoint_lead')
+     OR act->>'building' IS DISTINCT FROM OLD.building THEN
+    RAISE EXCEPTION 'government_leads changes only through a passed People matter for this building (board item %)', NEW.removed_by_item_id
+      USING ERRCODE = 'check_violation';
+  END IF;
+  NEW.removed_at := now();
+  RETURN NEW;
+END
+$guard$;
+
+CREATE OR REPLACE TRIGGER government_leads_matter_only
+  BEFORE INSERT OR UPDATE OR DELETE ON government_leads
+  FOR EACH ROW EXECUTE FUNCTION government_leads_guard();
+
+COMMIT;

package/modules/government/migrations/government_030_buildouts.sql

@@ -0,0 +1,111 @@
+-- government_030_buildouts.sql — a Lead's build-outs: the structure a building
+-- grows under its holder, as data (task 1004711, goal 1000111; ADR 0378).
+--
+-- WHAT THIS ADDS
+--
+--   government_buildouts — ONE ROW PER BUILD-OUT, ever: a committee room, a new
+--   floor, an annex, or growing the building into a district, added to one of
+--   the nine buildings, with a short name and one line saying what it is for.
+--   A row is never edited and never deleted: each is one change to the city, on
+--   the record. It records WHO asked (built_by, the building's holder) and HOW it
+--   was allowed — exactly one of:
+--     * authorised_by_item_id — a closed, PASSED matter whose action is
+--       build_out for exactly this building, capsule, name and line (the vote
+--       path); or
+--     * ground + why — the build-rights rule that let its holder build at once
+--       (modules/government/build-rights.js: 'form', 'goal' or 'building'). The
+--       server asks that rule before writing; this table cannot run it, so it
+--       holds the shape: a district is never built at once (its ground is
+--       'city', always a vote).
+--   started_at is the database clock; the hall draws a build-out as a live site
+--   for a day from then (buildouts.js BUILD_HOURS), then as built.
+--
+--   A GUARD TRIGGER refuses an INSERT whose vote a passed matter did not say,
+--   any at-once row without its ground, every UPDATE and every DELETE.
+--
+-- Nothing is seeded. Additive and idempotent: a new table, CREATE OR REPLACE for
+-- the functions and the trigger (Postgres 14+; production runs 16).
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS government_buildouts (
+  id                     bigserial   PRIMARY KEY,
+  -- the building it is added to (the nine, decision-rules.js AREAS)
+  building               text        NOT NULL
+                         CHECK (building IN ('charter', 'rules', 'disputes', 'people', 'planning',
+                                             'automation', 'review', 'release', 'treasury')),
+  -- which build-out (build-rights.js CAPSULES)
+  capsule                text        NOT NULL
+                         CHECK (capsule IN ('committee', 'floor', 'annex', 'district')),
+  name                   text        NOT NULL
+                         CHECK (char_length(btrim(name)) BETWEEN 2 AND 40 AND name !~ '[\r\n]'),
+  line                   text        NOT NULL DEFAULT ''
+                         CHECK (char_length(line) <= 140 AND line !~ '[\r\n]'),
+  -- WHO asked: the building's holder
+  built_by               bigint      REFERENCES builders(id) ON DELETE SET NULL,
+  -- HOW it was allowed: a passed vote ...
+  authorised_by_item_id  bigint      REFERENCES government_board_items(id) ON DELETE RESTRICT,
+  -- ... or the rule that let its holder build at once
+  ground                 text        CHECK (ground IS NULL OR ground IN ('form', 'goal', 'building')),
+  why                    text        CHECK (why IS NULL OR char_length(why) <= 300),
+  started_at             timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT government_buildouts_one_path CHECK ((authorised_by_item_id IS NULL) <> (ground IS NULL)),
+  CONSTRAINT government_buildouts_district_votes CHECK (capsule <> 'district' OR authorised_by_item_id IS NOT NULL)
+);
+
+-- A passed vote builds once.
+CREATE UNIQUE INDEX IF NOT EXISTS government_buildouts_item_uniq
+  ON government_buildouts (authorised_by_item_id) WHERE authorised_by_item_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS government_buildouts_building_idx
+  ON government_buildouts (building, started_at);
+
+-- The action of the passed matter a board item decided, or NULL when the item
+-- is not a closed, passed matter.
+CREATE OR REPLACE FUNCTION government_buildouts_passed_action(p_item_id bigint) RETURNS jsonb
+LANGUAGE sql STABLE AS $fn$
+  SELECT m.action
+    FROM government_board_items i
+    JOIN government_matters m ON m.id = i.subject_id
+   WHERE i.id = $1
+     AND i.subject_type = m.area || '_matter'
+     AND i.outcome = 'passed'
+$fn$;
+
+CREATE OR REPLACE FUNCTION government_buildouts_guard() RETURNS trigger
+LANGUAGE plpgsql AS $guard$
+DECLARE
+  act jsonb;
+BEGIN
+  IF TG_OP <> 'INSERT' THEN
+    RAISE EXCEPTION 'government_buildouts: a build-out is on the record; it is never edited or deleted'
+      USING ERRCODE = 'check_violation';
+  END IF;
+
+  IF NEW.authorised_by_item_id IS NOT NULL THEN
+    act := government_buildouts_passed_action(NEW.authorised_by_item_id);
+    IF act IS NULL
+       OR act->>'type' IS DISTINCT FROM 'build_out'
+       OR act->>'building' IS DISTINCT FROM NEW.building
+       OR act->>'capsule' IS DISTINCT FROM NEW.capsule
+       OR act->>'name' IS DISTINCT FROM NEW.name
+       OR act->>'line' IS DISTINCT FROM NEW.line THEN
+      RAISE EXCEPTION 'government_buildouts: board item % is not a passed matter that builds this', NEW.authorised_by_item_id
+        USING ERRCODE = 'check_violation';
+    END IF;
+  ELSIF NEW.ground IS NULL OR NEW.why IS NULL OR NEW.capsule = 'district' THEN
+    RAISE EXCEPTION 'government_buildouts: built at once only on a build-rights ground, and never a district'
+      USING ERRCODE = 'check_violation';
+  END IF;
+
+  NEW.started_at := now();
+  RETURN NEW;
+END
+$guard$;
+
+CREATE OR REPLACE TRIGGER government_buildouts_on_the_record
+  BEFORE INSERT OR UPDATE OR DELETE ON government_buildouts
+  FOR EACH ROW EXECUTE FUNCTION government_buildouts_guard();
+
+COMMIT;

package/modules/government/migrations/government_031_treasury.sql

@@ -0,0 +1,107 @@
+-- government_031_treasury.sql — THE TREASURY: a pot per goal, the reserve, and
+-- the borrow a dry pot asks for (task 1004712, goal 1000111; ADR 0379).
+--
+-- The project's AI spend is its treasury. Owner rulings (2026-10-09): there is
+-- NO spend limit by default (a cap is an optional project setting, off by
+-- default: project_settings['treasury.spend_cap_usd'], no row = off); a goal
+-- may have a pot; when a pot runs dry its agent asks to borrow from the
+-- reserve, and that borrow is a treasury matter the government decides.
+--
+-- This is the project's own accounting over its REAL spend (cost_log). Nothing
+-- here moves money or talks to a payment provider: a pot's spend is read from
+-- cost_log through each task's goal, every time; only the budget a goal is
+-- given and the loans the treasury made are stored.
+--
+-- WHAT THIS ADDS
+--
+--   government_pots — ONE ROW PER GOAL THAT HAS A POT: the monthly budget the
+--   Treasury's holder gave it. A goal without a row has no pot. The budget is
+--   a setting, so it may be changed or taken away (the row deleted).
+--
+--   government_pot_borrows — ONE ROW PER BORROW ASK, ever: a dry pot asking
+--   the reserve for money in one calendar month ('YYYY-MM'), how much, what the
+--   pot stood at when it asked, and how the treasury answered. It is filed
+--   'open' (its ask is stored in government_asks under the docket id
+--   'treasury_spending:<id>' and routed to the Treasury's holder) and answered
+--   once: 'lent' (lent_usd is what was lent: all or half) or 'refused'. A GUARD
+--   TRIGGER refuses an answer on a row already answered, any change to what
+--   was asked, and every DELETE: a loan is on the record.
+--
+-- Nothing is seeded. Additive and idempotent: new tables, CREATE OR REPLACE for
+-- the function and the trigger (Postgres 14+; production runs 16).
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS government_pots (
+  goal_id      bigint        PRIMARY KEY REFERENCES goals(id) ON DELETE CASCADE,
+  -- dollars a month; no default and no ceiling beyond sanity
+  budget_usd   numeric(12,2) NOT NULL CHECK (budget_usd > 0 AND budget_usd <= 1000000),
+  set_by       bigint        REFERENCES builders(id) ON DELETE SET NULL,
+  set_at       timestamptz   NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS government_pot_borrows (
+  id           bigserial     PRIMARY KEY,
+  goal_id      bigint        NOT NULL REFERENCES goals(id) ON DELETE RESTRICT,
+  month        text          NOT NULL CHECK (month ~ '^[0-9]{4}-(0[1-9]|1[0-2])$'),
+  -- what it asks for, and what the pot stood at when it asked
+  amount_usd   numeric(12,2) NOT NULL CHECK (amount_usd > 0 AND amount_usd <= 1000000),
+  budget_usd   numeric(12,2) NOT NULL CHECK (budget_usd >= 0),
+  spent_usd    numeric(12,2) NOT NULL CHECK (spent_usd >= 0),
+  filed_at     timestamptz   NOT NULL DEFAULT now(),
+  -- how the treasury answered
+  state        text          NOT NULL DEFAULT 'open' CHECK (state IN ('open', 'lent', 'refused')),
+  lent_usd     numeric(12,2) CHECK (lent_usd IS NULL OR (lent_usd > 0 AND lent_usd <= amount_usd)),
+  answer_key   text          CHECK (answer_key IS NULL OR answer_key IN ('lend', 'half', 'no')),
+  answered_by  bigint        REFERENCES builders(id) ON DELETE SET NULL,
+  answered_at  timestamptz,
+
+  CONSTRAINT government_pot_borrows_answered CHECK (
+    (state = 'open'    AND lent_usd IS NULL AND answer_key IS NULL AND answered_at IS NULL) OR
+    (state = 'lent'    AND lent_usd IS NOT NULL AND answer_key IN ('lend', 'half') AND answered_at IS NOT NULL) OR
+    (state = 'refused' AND lent_usd IS NULL AND answer_key = 'no' AND answered_at IS NOT NULL))
+);
+
+-- A pot asks once at a time: one open borrow per goal.
+CREATE UNIQUE INDEX IF NOT EXISTS government_pot_borrows_one_open
+  ON government_pot_borrows (goal_id) WHERE state = 'open';
+
+CREATE INDEX IF NOT EXISTS government_pot_borrows_month_idx
+  ON government_pot_borrows (month, goal_id);
+
+CREATE OR REPLACE FUNCTION government_pot_borrows_guard() RETURNS trigger
+LANGUAGE plpgsql AS $guard$
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    RAISE EXCEPTION 'government_pot_borrows: a borrow is on the record; it is never deleted'
+      USING ERRCODE = 'check_violation';
+  END IF;
+  IF TG_OP = 'INSERT' THEN
+    IF NEW.state <> 'open' THEN
+      RAISE EXCEPTION 'government_pot_borrows: a borrow is filed open and answered after'
+        USING ERRCODE = 'check_violation';
+    END IF;
+    NEW.filed_at := now();
+    RETURN NEW;
+  END IF;
+  -- UPDATE: only the one answer, on an open row; what was asked never changes
+  IF OLD.state <> 'open' THEN
+    RAISE EXCEPTION 'government_pot_borrows: borrow % was already answered', OLD.id
+      USING ERRCODE = 'check_violation';
+  END IF;
+  IF NEW.goal_id IS DISTINCT FROM OLD.goal_id OR NEW.month IS DISTINCT FROM OLD.month
+     OR NEW.amount_usd IS DISTINCT FROM OLD.amount_usd OR NEW.budget_usd IS DISTINCT FROM OLD.budget_usd
+     OR NEW.spent_usd IS DISTINCT FROM OLD.spent_usd OR NEW.filed_at IS DISTINCT FROM OLD.filed_at THEN
+    RAISE EXCEPTION 'government_pot_borrows: what a borrow asked for is never edited'
+      USING ERRCODE = 'check_violation';
+  END IF;
+  NEW.answered_at := now();
+  RETURN NEW;
+END
+$guard$;
+
+CREATE OR REPLACE TRIGGER government_pot_borrows_on_the_record
+  BEFORE INSERT OR UPDATE OR DELETE ON government_pot_borrows
+  FOR EACH ROW EXECUTE FUNCTION government_pot_borrows_guard();
+
+COMMIT;

package/modules/government/module.json

@@ -15,7 +15,8 @@
       "rank-sync"
     ],
     "pollers": [
-      "board-expiry"
+      "board-expiry",
+      "treasury-borrow"
     ]
   },
   "provides": [

package/modules/government/pollers/treasury-borrow.js

@@ -0,0 +1,62 @@
+'use strict';
+
+// modules/government/pollers/treasury-borrow.js — A DRY POT ASKS TO BORROW (task
+// 1004712, goal 1000111; ADR 0379).
+//
+// The owner's ruling: when a goal's pot runs dry, it asks to borrow from the
+// reserve, and that borrow is a treasury matter the government decides. This is
+// the treasury's own agent: every sweep it reads the treasury (real spend, the
+// stored pots and loans) and files a borrow for every dry pot that has nothing
+// open and was not told no this month (treasury-db.fileBorrows). The ask lands on
+// the docket as treasury_spending:<id>, waiting on the Treasury's holder.
+//
+// It never stops work and never moves money: there is no spend limit by default,
+// and a borrow is accounting. A project with no pots files nothing.
+//
+// THE SWEEP SHAPE is board-expiry's: a first sweep shortly after boot, then on an
+// interval, quiet when there is nothing to file, one line per borrow filed, and a
+// read that fails is logged and retried next sweep.
+
+const api = require('../../../src/module-api');
+const treasuryDb = require('../treasury-db');
+
+const logger = api.logger('government');
+
+const INTERVAL_MS = Number(process.env.TREASURY_BORROW_SWEEP_MS) || 15 * 60_000;
+const FIRST_SWEEP_DELAY_MS = Number(process.env.TREASURY_BORROW_FIRST_MS) || 60_000;
+
+let intervalTimer = null;
+let firstTimer = null;
+
+async function runSweep({ fileFn = treasuryDb.fileBorrows, now = Date.now, log = (m) => logger.info(m), error = (m) => logger.error(m) } = {}) {
+  let filed;
+  try {
+    filed = await fileFn({ now: now() });
+  } catch (e) {
+    error(`[treasury-borrow] sweep failed (next sweep retries): ${e && e.message}`);
+    return { filed: 0, failed: true };
+  }
+  for (const f of filed || []) log(`[treasury-borrow] goal ${f.goal_id}'s pot is dry → borrow ${f.borrow_id} asks the reserve for $${f.amount_usd}`);
+  return { filed: (filed || []).length, failed: false };
+}
+
+function start(deps = {}) {
+  if (process.env.TREASURY_BORROW_DISABLED === '1') {
+    logger.info('[treasury-borrow] disabled (TREASURY_BORROW_DISABLED=1)');
+    return;
+  }
+  if (intervalTimer) return;
+  const tick = () => { runSweep(deps).catch((e) => logger.error(`[treasury-borrow] sweep crashed: ${e && e.message}`)); };
+  firstTimer = setTimeout(tick, FIRST_SWEEP_DELAY_MS);
+  if (firstTimer.unref) firstTimer.unref();
+  intervalTimer = setInterval(tick, INTERVAL_MS);
+  if (intervalTimer.unref) intervalTimer.unref();
+  logger.info(`[treasury-borrow] started (every ${Math.round(INTERVAL_MS / 60000)}m; first sweep in ${Math.round(FIRST_SWEEP_DELAY_MS / 1000)}s)`);
+}
+
+function stop() {
+  if (firstTimer) { clearTimeout(firstTimer); firstTimer = null; }
+  if (intervalTimer) { clearInterval(intervalTimer); intervalTimer = null; }
+}
+
+module.exports = { start, stop, runSweep, INTERVAL_MS };