ekwo-os 0.4.1

package/dist/assets/migrations/20260913102758_no_currency_default.sql

@@ -0,0 +1,138 @@
+-- Ekwo OS — a euro written into the schema is a country written into the core.
+--
+-- Seven columns were declared `char(3) not null default 'EUR'` and one
+-- `char(2) not null default 'fr'`. They date from before "a country is data"
+-- was a rule, and they are the same mistake the country literals were: a
+-- Canadian installation that forgets to name a currency does not get an
+-- error, it gets euros — in its documents, its payments, its catalogue, its
+-- bank accounts and its statements — and finds out at the first report.
+--
+-- The defaults go. What replaces them is not another default but the answer
+-- that was always the right one, taken from the row above:
+--
+--   * a company's currency and language come from **the pack of its fiscal
+--     country** or from whoever creates it. `create_company()` already
+--     refuses both by name when the pack is silent (`no_currency`,
+--     `no_language`) and `ekwo init` asks; for every other writer a trigger
+--     reads `country_defaults`, so a silent pack leaves the column null and
+--     the NOT NULL refuses the insert. Silence is an error again, where it
+--     used to be euros;
+--   * a document, a payment, a catalogue item and a bank account take the
+--     currency of **their company**, and a statement line takes the currency
+--     of **its bank account**, which is a stronger answer than the company's
+--     and falls back to it. One trigger, one place, no literal;
+--   * `country_defaults.currency_code` is pack data and the compiled seed of
+--     every country fills it. A default there would have meant a pack that
+--     says nothing about its own currency silently claims the euro.
+--
+-- The trigger fills only what the caller left empty, so a foreign-currency
+-- document still says so and nothing that used to work stops working. What
+-- changes is what happens when *nobody* answers: it used to be euros, and it
+-- is now the company, which is an answer the installation actually chose.
+
+alter table companies         alter column currency_code drop default;
+alter table companies         alter column language      drop default;
+alter table country_defaults  alter column currency_code drop default;
+alter table documents         alter column currency_code drop default;
+alter table payments          alter column currency_code drop default;
+alter table products          alter column currency_code drop default;
+alter table bank_accounts     alter column currency_code drop default;
+alter table bank_transactions alter column currency_code drop default;
+
+-- ---------------------------------------------------------------------------
+-- Where a currency comes from when the caller names none
+--
+-- A BEFORE INSERT trigger rather than a column default, because a default can
+-- only be a constant and the answer is a lookup. It runs before the NOT NULL
+-- is checked, which is what lets the column stay NOT NULL with no default at
+-- all: leave it out and the company answers; leave the company out and the
+-- insert is refused by the foreign key, as it already was.
+-- ---------------------------------------------------------------------------
+
+create or replace function currency_of_company()
+returns trigger
+language plpgsql
+as $$
+begin
+  if new.currency_code is null then
+    select c.currency_code into new.currency_code
+      from companies c where c.id = new.company_id;
+  end if;
+  return new;
+end;
+$$;
+
+comment on function currency_of_company() is
+  'Fills currency_code from the company when the caller named none. The one place the question is answered for a table that belongs to a company.';
+
+-- A company has no company above it: its answer is its country's pack. A
+-- pack that names neither leaves the column null, and NOT NULL refuses the
+-- row — which is the whole point of dropping the default.
+create or replace function locale_of_country_pack()
+returns trigger
+language plpgsql
+as $$
+declare
+  v_defaults country_defaults%rowtype;
+begin
+  if new.currency_code is null or new.language is null then
+    select * into v_defaults
+      from country_defaults
+     where country = coalesce(new.fiscal_country, new.country);
+    new.currency_code := coalesce(new.currency_code, v_defaults.currency_code);
+    new.language      := coalesce(new.language, v_defaults.language_default);
+  end if;
+  return new;
+end;
+$$;
+
+comment on function locale_of_country_pack() is
+  'Fills a company''s currency and language from the pack of its fiscal country when the caller named neither. A pack that says nothing leaves them null, and NOT NULL refuses the row.';
+
+create trigger companies_locale_of_country_pack
+  before insert on companies
+  for each row execute function locale_of_country_pack();
+
+create trigger documents_currency_of_company
+  before insert on documents
+  for each row execute function currency_of_company();
+
+create trigger payments_currency_of_company
+  before insert on payments
+  for each row execute function currency_of_company();
+
+create trigger products_currency_of_company
+  before insert on products
+  for each row execute function currency_of_company();
+
+create trigger bank_accounts_currency_of_company
+  before insert on bank_accounts
+  for each row execute function currency_of_company();
+
+-- A statement line is in the currency of the account it came off, which is
+-- not always the company's. The account answers first, the company after.
+create or replace function currency_of_bank_account()
+returns trigger
+language plpgsql
+as $$
+begin
+  if new.currency_code is null then
+    select b.currency_code into new.currency_code
+      from bank_accounts b where b.id = new.bank_account_id;
+  end if;
+  if new.currency_code is null then
+    select c.currency_code into new.currency_code
+      from companies c where c.id = new.company_id;
+  end if;
+  return new;
+end;
+$$;
+
+comment on function currency_of_bank_account() is
+  'Fills a statement line''s currency_code from its bank account, and from the company as a last resort.';
+
+create trigger bank_transactions_currency_of_bank_account
+  before insert on bank_transactions
+  for each row execute function currency_of_bank_account();
+
+revoke execute on all functions in schema public from public;

package/dist/assets/migrations/20260913103355_cash_basis_needs_a_box.sql

@@ -0,0 +1,453 @@
+-- Ekwo OS — a tax that waits for a box that does not exist waits for ever.
+--
+-- `settle_cash_basis_tax()` is what moves a cash-basis tax off the transition
+-- account when the invoice is paid. It finds the lines still waiting with
+--
+--   where t.cash_basis and q.declaration_box is null and q.box_amount is not null
+--
+-- and `post_document()` writes `box_amount` only when the posting names a
+-- `declaration_box`:
+--
+--   v_box_amount := case when p.declaration_box is null then null else … end
+--
+-- So a cash-basis tax whose posting names no box books its amount onto the
+-- transition account, is never seen as waiting, never settles, and never
+-- reaches a declaration. Nothing raises. The balance simply grows, and it is
+-- discovered — if it is discovered — years later by somebody reconciling a
+-- transition account against nothing. The `no_cash_basis_box` exception that
+-- was written for exactly this case sits inside the loop that already
+-- excluded the line, so it could not fire.
+--
+-- The rule belongs upstream of the ledger, twice over, and both are cheap:
+--
+--   * `ekwo pack check` refuses a cash-basis tax whose tax posting names no
+--     box, in the same place it already refuses one that names no transition
+--     account, no more than one tax posting, or a non-deductible share;
+--   * `post_document()` raises `no_cash_basis_box` before it writes the
+--     entry, next to `no_cash_basis_account` and `cash_basis_split_tax` —
+--     because a pack can be written by hand and installed without the CLI.
+--
+-- The unreachable check in `settle_cash_basis_tax()` stays where it is. It is
+-- the last line of defence for a posting whose box was removed after a
+-- document was booked, and with the two above in front of it that is the only
+-- way to reach it.
+
+create or replace function post_document(p_document_id uuid)
+returns entries
+language plpgsql
+as $$
+declare
+  v_doc        documents%rowtype;
+  v_entry      entries%rowtype;
+  v_journal    uuid;
+  v_date       date;
+  v_is_sale    boolean;
+  v_is_credit  boolean;
+  v_kind       tax_document_kind;
+  v_base_credit boolean;
+  v_seq        integer := 0;
+  v_contact    uuid;
+  v_maturity   date;
+  v_terms      smallint;
+  v_counterpart uuid;
+  v_diff       numeric(16, 2);
+  v_diff_cur   numeric(16, 2);
+  v_amount     numeric(16, 2);
+  v_book       numeric(16, 2);
+  v_box_amount numeric(16, 2);
+  v_share      numeric(16, 2);
+  v_share_book numeric(16, 2);
+  v_share_box  numeric(16, 2);
+  v_left       numeric(16, 2);
+  v_left_box   numeric(16, 2);
+  v_side_left     numeric(16, 2);
+  v_side_left_neg numeric(16, 2);
+  v_side_credit boolean;
+  v_label      text;
+  v_rate       numeric(18, 8);
+  v_home       char(3);
+  v_foreign    boolean;
+  v_total_cur  numeric(16, 2);
+  v_cash       boolean;
+  v_transition uuid;
+  v_postings   integer;
+  r            record;
+  p            record;
+  g            record;
+begin
+  select * into v_doc from documents where id = p_document_id for update;
+  if not found then
+    raise exception 'unknown_document: document % does not exist', p_document_id;
+  end if;
+  if v_doc.state = 'posted' then
+    raise exception 'document_already_posted: document % is already posted', p_document_id;
+  end if;
+  if v_doc.state = 'cancelled' then
+    raise exception 'document_cancelled: document % cannot be posted', p_document_id;
+  end if;
+  if v_doc.entry_id is not null then
+    raise exception 'document_already_booked: document % already points at entry %',
+      p_document_id, v_doc.entry_id;
+  end if;
+
+  if v_doc.doc_type in ('sale_quote', 'purchase_order') then
+    raise exception 'document_not_accountable: a % is not booked', v_doc.doc_type;
+  end if;
+
+  v_is_sale   := v_doc.doc_type in ('sale_invoice', 'sale_credit_note');
+  v_is_credit := v_doc.doc_type in ('sale_credit_note', 'purchase_credit_note');
+  v_kind      := case when v_is_credit then 'credit_note' else 'invoice' end::tax_document_kind;
+  -- Sale invoice and purchase credit note credit the base; the other two debit it.
+  v_base_credit := (v_is_sale <> v_is_credit);
+
+  v_date := coalesce(v_doc.accounting_date, v_doc.document_date);
+
+  if not exists (
+    select 1 from document_lines
+     where document_id = p_document_id and line_type = 'product' and amount_untaxed <> 0
+  ) then
+    raise exception 'document_empty: document % has no billable line', p_document_id;
+  end if;
+
+  -- A fixed-amount tax has no basis to spread over lines; refuse rather than
+  -- guess.
+  if exists (
+    select 1 from document_lines l join taxes t on t.id = l.tax_id
+     where l.document_id = p_document_id and t.amount_type <> 'percent'
+  ) then
+    raise exception 'unsupported_tax_amount_type: only percentage taxes can be posted';
+  end if;
+
+  -- Every tax used must be in force on the accounting date.
+  for r in
+    select distinct t.id, t.code, t.valid_from, t.valid_to
+      from document_lines l join taxes t on t.id = l.tax_id
+     where l.document_id = p_document_id
+  loop
+    if v_date < r.valid_from or (r.valid_to is not null and v_date > r.valid_to) then
+      raise exception 'tax_not_in_force: tax % is not applicable on %', r.code, v_date;
+    end if;
+  end loop;
+
+  -- Totals are derived; make sure they reflect the lines as they stand now.
+  perform documents_refresh_totals(p_document_id);
+  select * into v_doc from documents where id = p_document_id;
+
+  select c.currency_code into v_home from companies c where c.id = v_doc.company_id;
+  v_rate    := v_doc.exchange_rate;
+  v_foreign := v_doc.currency_code <> v_home;
+
+  v_journal := coalesce(
+    v_doc.journal_id,
+    case when v_is_sale
+      then (select sales_journal_id from companies where id = v_doc.company_id)
+      else (select purchase_journal_id from companies where id = v_doc.company_id)
+    end
+  );
+  if v_journal is null then
+    raise exception 'no_journal: set journal_id on the document or a default journal on the company';
+  end if;
+
+  perform assert_period_open(v_doc.company_id, v_date, true);
+
+  v_label := coalesce(v_doc.number, v_doc.supplier_reference, 'document');
+
+  insert into entries (company_id, journal_id, fiscal_year_id, entry_date, reference,
+                       description, state, document_id, currency_code)
+  values (v_doc.company_id, v_journal, fiscal_year_at(v_doc.company_id, v_date), v_date,
+          coalesce(v_doc.number, v_doc.supplier_reference),
+          v_label || case when v_doc.supplier_reference is not null and v_doc.number is not null
+                          then ' / ' || v_doc.supplier_reference else '' end,
+          'draft', p_document_id, v_doc.currency_code)
+  returning * into v_entry;
+
+  -- ------------------------------------------------------------------ bases
+  for r in
+    select l.account_id,
+           l.tax_id,
+           sum(l.amount_untaxed) as base_amount,
+           min(l.sequence)       as seq,
+           string_agg(distinct l.name, ', ') as label
+      from document_lines l
+     where l.document_id = p_document_id
+       and l.line_type = 'product'
+     group by l.account_id, l.tax_id
+    having sum(l.amount_untaxed) <> 0
+     order by 4
+  loop
+    select tp.declaration_box, tp.factor_percent, tp.box_factor_percent,
+           coalesce(t.cash_basis, false) as cash_basis
+      into p
+      from tax_postings tp
+      join taxes t on t.id = tp.tax_id
+     where tp.tax_id = r.tax_id
+       and tp.document_kind = v_kind
+       and tp.posting_type = 'base'
+     limit 1;
+
+    v_amount := round(r.base_amount * coalesce(p.factor_percent, 100) / 100, 2);
+    v_book   := round(v_amount / v_rate, 2);
+    v_seq := v_seq + 10;
+
+    insert into entry_lines (entry_id, company_id, account_id, sequence, name,
+                             debit, credit, tax_id, tax_line,
+                             declaration_box, box_amount, currency_code, amount_currency)
+    values (v_entry.id, v_doc.company_id, r.account_id, v_seq, left(r.label, 200),
+            case when v_base_credit then 0 else v_book end,
+            case when v_base_credit then v_book else 0 end,
+            r.tax_id, false,
+            case when coalesce(p.cash_basis, false) then null else p.declaration_box end,
+            case when p.declaration_box is null then null
+                 else round(r.base_amount * coalesce(p.box_factor_percent, 100) / 100 / v_rate, 2) end,
+            v_doc.currency_code,
+            case when v_foreign then v_amount end);
+  end loop;
+
+  -- ------------------------------------------------------------------ taxes
+  for r in
+    select s.tax_id, s.tax_code, s.tax_name, s.tax_amount
+      from document_tax_summary s
+     where s.document_id = p_document_id
+       and s.tax_id is not null
+       and s.tax_amount <> 0
+     order by s.tax_code
+  loop
+    select t.cash_basis, t.cash_basis_transition_account_id
+      into v_cash, v_transition
+      from taxes t where t.id = r.tax_id;
+
+    if v_cash then
+      -- A tax that waits needs somewhere to wait. Refuse by name rather than
+      -- book it on the account it is due on, which would make it due.
+      if v_transition is null then
+        raise exception 'no_cash_basis_account: tax % falls due on collection and names no transition account',
+          r.tax_code;
+      end if;
+      -- One posting per side, or the transition lines of a document cannot be
+      -- told apart when the matching sends each of them on. A tax whose
+      -- postings net out has nothing waiting to collect anyway.
+      select count(*) into v_postings
+        from tax_postings tp
+       where tp.tax_id = r.tax_id and tp.document_kind = v_kind
+         and tp.posting_type = 'tax';
+      if v_postings > 1 then
+        raise exception 'cash_basis_split_tax: tax % falls due on collection and has % tax postings; it takes one',
+          r.tax_code, v_postings;
+      end if;
+      if exists (select 1 from tax_postings tp
+                  where tp.tax_id = r.tax_id and tp.document_kind = v_kind
+                    and tp.posting_type = 'tax_on_base') then
+        raise exception 'cash_basis_tax_on_base: tax % falls due on collection and carries a non-deductible share; a cost is not deferred',
+          r.tax_code;
+      end if;
+      -- And it needs a box to fall due *into*. `settle_cash_basis_tax()` only
+      -- ever looks at lines that carry a `box_amount`, and a posting with no
+      -- `declaration_box` produces none — so the amount would sit on the
+      -- transition account for ever, settled by nothing and reported by
+      -- nothing, with no error anywhere. Refuse it here, where the pack can
+      -- still be corrected, rather than discover it in a balance years later.
+      if not exists (select 1 from tax_postings tp
+                      where tp.tax_id = r.tax_id and tp.document_kind = v_kind
+                        and tp.posting_type = 'tax'
+                        and tp.declaration_box is not null) then
+        raise exception 'no_cash_basis_box: tax % falls due on collection and its posting names no declaration box; the amount would wait on the transition account and never settle',
+          r.tax_code;
+      end if;
+    end if;
+
+    -- The postings of one side share out the tax of the group; the last of
+    -- each side takes what is left. Until `tax_on_base` there was never more
+    -- than one posting per side, so this changes no existing tax by a cent —
+    -- and it is what keeps a 50/50 split honest: 0.63 becomes 0.32 and 0.31,
+    -- where rounding each half on its own would book 0.64 against a document
+    -- that totals 0.63.
+    v_side_left     := null;
+    v_side_left_neg := null;
+
+    for p in
+      select tp.posting_type, tp.factor_percent, tp.account_id,
+             tp.declaration_box, tp.box_factor_percent,
+             case when tp.factor_percent >= 0 then 1 else -1 end as side,
+             sum(abs(tp.factor_percent))
+               over (partition by case when tp.factor_percent >= 0 then 1 else -1 end)
+               as side_factor,
+             row_number() over (
+               partition by case when tp.factor_percent >= 0 then 1 else -1 end
+               order by tp.sequence, tp.id)
+             = count(*) over (
+               partition by case when tp.factor_percent >= 0 then 1 else -1 end)
+               as is_last_of_side
+        from tax_postings tp
+       where tp.tax_id = r.tax_id
+         and tp.document_kind = v_kind
+         and tp.posting_type in ('tax', 'tax_on_base')
+       order by tp.sequence, tp.id
+    loop
+      -- The tax of the group was rounded once, in the view. Every posting is
+      -- a share of that one figure, never of a re-derived one.
+      if p.side >= 0 then
+        if v_side_left is null then
+          v_side_left := round(r.tax_amount * p.side_factor / 100, 2);
+        end if;
+        if p.is_last_of_side then
+          v_amount := v_side_left;
+        else
+          v_amount    := round(r.tax_amount * abs(p.factor_percent) / 100, 2);
+          v_side_left := v_side_left - v_amount;
+        end if;
+      else
+        if v_side_left_neg is null then
+          v_side_left_neg := round(r.tax_amount * p.side_factor / 100, 2);
+        end if;
+        if p.is_last_of_side then
+          v_amount := v_side_left_neg;
+        else
+          v_amount        := round(r.tax_amount * abs(p.factor_percent) / 100, 2);
+          v_side_left_neg := v_side_left_neg - v_amount;
+        end if;
+      end if;
+
+      if v_amount = 0 then
+        continue;
+      end if;
+      -- A positive factor keeps the side of the base, a negative one flips it.
+      v_side_credit := case when p.factor_percent >= 0 then v_base_credit else not v_base_credit end;
+      -- The box keeps its own rounding: `box_factor_percent` was always
+      -- independent from `factor_percent`, because a declaration figure is
+      -- not a ledger figure and only the ledger has to balance.
+      v_box_amount := case when p.declaration_box is null then null
+                           else round(r.tax_amount * p.box_factor_percent / 100 / v_rate, 2) end;
+      v_book := round(v_amount / v_rate, 2);
+
+      if p.posting_type = 'tax' then
+        v_seq := v_seq + 10;
+
+        insert into entry_lines (entry_id, company_id, account_id, sequence, name,
+                                 debit, credit, tax_id, tax_line,
+                                 declaration_box, box_amount, currency_code, amount_currency)
+        values (v_entry.id, v_doc.company_id,
+                case when v_cash then v_transition else p.account_id end,
+                v_seq, r.tax_name,
+                case when v_side_credit then 0 else v_book end,
+                case when v_side_credit then v_book else 0 end,
+                r.tax_id, true,
+                case when v_cash then null else p.declaration_box end,
+                v_box_amount, v_doc.currency_code,
+                case when v_foreign then v_amount end);
+        continue;
+      end if;
+
+      -- `tax_on_base`: the tax is a cost, so it lands on the accounts of the
+      -- lines it taxes, split in proportion to their base. The last share
+      -- takes whatever is left, so the shares add up to the amount that was
+      -- rounded once on the group and the entry still balances to the cent.
+      v_left     := v_amount;
+      v_left_box := v_box_amount;
+
+      for g in
+        select account_id,
+               base_amount,
+               seq,
+               sum(base_amount) over ()                                   as total_base,
+               row_number() over (order by seq) = count(*) over ()         as is_last
+          from (
+            select l.account_id,
+                   sum(l.amount_untaxed) as base_amount,
+                   min(l.sequence)       as seq
+              from document_lines l
+             where l.document_id = p_document_id
+               and l.line_type = 'product'
+               and l.tax_id = r.tax_id
+             group by l.account_id
+            having sum(l.amount_untaxed) <> 0
+          ) as groups
+         order by seq
+      loop
+        if g.is_last then
+          v_share     := v_left;
+          v_share_box := v_left_box;
+        else
+          v_share     := round(v_amount * g.base_amount / g.total_base, 2);
+          v_share_box := case when v_box_amount is null then null
+                              else round(v_box_amount * g.base_amount / g.total_base, 2) end;
+          v_left      := v_left - v_share;
+          v_left_box  := v_left_box - v_share_box;
+        end if;
+
+        if v_share = 0 then
+          continue;
+        end if;
+
+        v_seq := v_seq + 10;
+        v_share_book := round(v_share / v_rate, 2);
+
+        -- `tax_line` stays false: the amount is on a base account and belongs
+        -- to the base side of the declaration, which is why the Belgian grids
+        -- 82 and 83 report it together with the base.
+        insert into entry_lines (entry_id, company_id, account_id, sequence, name,
+                                 debit, credit, tax_id, tax_line,
+                                 declaration_box, box_amount, currency_code, amount_currency)
+        values (v_entry.id, v_doc.company_id, g.account_id, v_seq, r.tax_name,
+                case when v_side_credit then 0 else v_share_book end,
+                case when v_side_credit then v_share_book else 0 end,
+                r.tax_id, false,
+                p.declaration_box, v_share_box, v_doc.currency_code,
+                case when v_foreign then v_share end);
+      end loop;
+    end loop;
+  end loop;
+
+  -- ------------------------------------------------------------ counterpart
+  select total_debit - total_credit into v_diff from entries where id = v_entry.id;
+  select coalesce(sum(case when l.debit > 0 then l.amount_currency else -l.amount_currency end), 0)
+    into v_diff_cur
+    from entry_lines l where l.entry_id = v_entry.id;
+
+  if v_diff = 0 then
+    raise exception 'document_counterpart_zero: document % produced a nil counterpart', p_document_id;
+  end if;
+
+  v_contact := commercial_entity(v_doc.contact_id);
+  v_counterpart := resolve_counterpart_account(v_doc.company_id, v_contact, v_is_sale);
+
+  select payment_terms_days into v_terms from contacts where id = v_contact;
+  v_maturity := coalesce(v_doc.due_date, v_doc.document_date + coalesce(v_terms, 30));
+
+  v_amount := abs(v_diff);
+  -- The counterpart balances the entry in both currencies. The total it is
+  -- checked against is the document's own, which is the currency
+  -- `amount_total` is stated in.
+  v_total_cur := case when v_foreign then abs(v_diff_cur) else v_amount end;
+  v_seq := v_seq + 10;
+
+  insert into entry_lines (entry_id, company_id, account_id, sequence, name,
+                           debit, credit, contact_id, date_maturity, currency_code,
+                           amount_currency)
+  values (v_entry.id, v_doc.company_id, v_counterpart, v_seq, v_label,
+          case when v_diff > 0 then 0 else v_amount end,
+          case when v_diff > 0 then v_amount else 0 end,
+          v_contact, v_maturity, v_doc.currency_code,
+          case when v_foreign then v_total_cur end);
+
+  -- The ledger is right by construction. If the header disagrees, the header
+  -- is what is wrong, and we say so instead of quietly patching a line.
+  if abs(v_total_cur - abs(v_doc.amount_total)) > 0.005 then
+    raise exception 'document_total_mismatch: document % totals % but its lines book %',
+      p_document_id, v_doc.amount_total, v_total_cur;
+  end if;
+
+  -- --------------------------------------------------------------- posting
+  v_entry := post_entry(v_entry.id);
+
+  update documents
+     set state  = 'posted',
+         number = coalesce(number, v_entry.number),
+         entry_id = v_entry.id,
+         accounting_date = v_date
+   where id = p_document_id;
+
+  return v_entry;
+end;
+$$;
+
+revoke execute on all functions in schema public from public;

package/dist/assets/migrations/20260913104014_aged_balance_named_group.sql

@@ -0,0 +1,79 @@
+-- Ekwo OS — "not payable" is not the same as "receivable".
+--
+-- `aged_balance(company, at, group)` tested the group twice, both times as
+-- `case when p_group = 'payable' then … else …`. So every value that is not
+-- exactly `'payable'` was silently the receivable ageing: `'supplier'`,
+-- `'creditors'`, `'Payable'`, a typo, a column name passed by mistake. The
+-- caller gets a full, plausible, wrong report — the one failure mode a report
+-- must never have, because nothing about it looks like an error.
+--
+-- Two named groups, and anything else is refused by name. The body is
+-- unchanged; it moves to plpgsql only so that it can raise.
+
+create or replace function aged_balance(
+  p_company_id uuid,
+  p_at         date default current_date,
+  p_group      text default 'receivable'
+)
+returns table (
+  contact_id   uuid,
+  contact_name text,
+  account_id   uuid,
+  account_code text,
+  not_due      numeric,
+  days_1_30    numeric,
+  days_31_60   numeric,
+  days_61_90   numeric,
+  days_over_90 numeric,
+  total        numeric
+)
+language plpgsql
+stable
+as $$
+begin
+  if p_group is null or p_group not in ('receivable', 'payable') then
+    raise exception 'invalid_group: % is not an ageing group; it is receivable or payable', coalesce(p_group, 'null');
+  end if;
+
+  return query
+  with open_lines as (
+    select l.contact_id,
+           l.account_id,
+           case when p_group = 'payable' then -l.balance else l.balance end
+             * (case when abs(l.balance) = 0 then 0
+                     else (abs(l.balance) - l.matched_amount) / abs(l.balance) end) as residual,
+           coalesce(l.date_maturity, e.entry_date) as due_date
+      from entry_lines l
+      join entries e on e.id = l.entry_id
+      join accounts a on a.id = l.account_id
+     where l.company_id = p_company_id
+       and e.state = 'posted'
+       and e.entry_date <= p_at
+       and a.reconcilable
+       and a.account_type = case when p_group = 'payable'
+                                 then 'liability_payable'::account_type
+                                 else 'asset_receivable'::account_type end
+       and abs(l.balance) - l.matched_amount > 0.005
+  )
+  select o.contact_id,
+         c.name,
+         o.account_id,
+         a.code,
+         round(sum(o.residual) filter (where o.due_date >= p_at), 2),
+         round(sum(o.residual) filter (where p_at - o.due_date between 1 and 30), 2),
+         round(sum(o.residual) filter (where p_at - o.due_date between 31 and 60), 2),
+         round(sum(o.residual) filter (where p_at - o.due_date between 61 and 90), 2),
+         round(sum(o.residual) filter (where p_at - o.due_date > 90), 2),
+         round(sum(o.residual), 2)
+    from open_lines o
+    left join contacts c on c.id = o.contact_id
+    join accounts a on a.id = o.account_id
+   group by o.contact_id, c.name, o.account_id, a.code
+   order by c.name nulls last;
+end;
+$$;
+
+comment on function aged_balance(uuid, date, text) is
+  'Ageing of what is still open, read from the ledger and from the matching. Two groups, receivable and payable; anything else is refused by name rather than reported as receivable.';
+
+revoke execute on all functions in schema public from public;