ekwo-os 0.4.1

package/dist/assets/migrations/20260918141605_an_invoice_reads_whole_from_the_views.sql

@@ -0,0 +1,313 @@
+-- Ekwo OS — what an invoice says is in the three views it is read through.
+--
+-- `packages/formats/README.md` tells a brick to read `document_header`,
+-- `document_line_items` and `document_tax_summary` and nothing else. The first
+-- brick that wrote a sendable invoice from them had to go behind them four
+-- times: for the tax point, for the delivery address, for the buyer's
+-- electronic address, and for the reason a tax charges nothing. Each was in
+-- the schema and none was in a view. A contract that needs a join to the
+-- tables under it is not the contract.
+--
+-- **The header gains what `documents`, `contacts` and now `companies` already
+-- know.** BT-7, the four columns of BG-15 this schema has, and the two
+-- electronic addresses. Nothing is invented: the delivery address has no
+-- second line and no region because `documents` has neither, and a delivery
+-- to a *named party* (BT-70) or a *location identifier* (BT-71) has no column
+-- anywhere. They are absent rather than approximated.
+--
+-- **The breakdown says why a group charges nothing, in a code and in a
+-- sentence.** BT-121 is `taxes.exemption_code`, which the lines view already
+-- published and the breakdown did not — although it is the breakdown the
+-- standard puts it on.
+--
+-- BT-120, the reason in words, is the decision of this file. The tax has a
+-- `legal_reference`, and it is the obvious candidate and the wrong one: it is
+-- the pack's *argument* — which article, why this code and not another, what
+-- the pack chose not to do — written for whoever reviews the pack. Some are a
+-- citation of six words and some are a paragraph that discusses this
+-- repository. None was written to be read by a customer. The sentence a
+-- country wants on an invoice that charges no tax exists already, per country,
+-- translated, dated: `legal_mention_templates`. "Reverse charge: the customer
+-- is to account for the VAT" is what BT-120 is for, and it is printed at the
+-- foot of the same invoice by `document_legal_mentions`.
+--
+-- So `exemption_reason` is the mention of the tax's treatment, in the language
+-- of the document, valid on its date — and null where the pack has no
+-- sentence for that treatment, which includes every tax that charges
+-- something. `legal_reference` is published beside it under its own name for
+-- a reader who wants the citation, and is not called a reason.
+--
+-- **One place says which treatments a condition covers.** The view that
+-- prints the mentions decided it in a `case`; a second copy here would drift
+-- the first time a treatment is added. `legal_mention_treatments()` holds it
+-- and both views read it. `document_legal_mentions` is otherwise
+-- `20260915191200` to the letter: same columns, same order.
+--
+-- What is still missing, and is a gap of the vocabulary rather than of a view:
+-- `applies_when` has no condition for a supply that is outside the scope of
+-- the tax, so a category-O group has no sentence and, where the pack gives it
+-- no code either, breaks BR-O-10.
+--
+-- Columns are appended, which is all `create or replace view` allows and what
+-- keeps the grants, the comment and `security_invoker` of the object replaced.
+
+-- ---------------------------------------------------------------------------
+-- 1. The treatments behind a condition
+-- ---------------------------------------------------------------------------
+
+create or replace function legal_mention_treatments(p_applies_when text)
+returns text[]
+language sql
+immutable
+set search_path = public, pg_temp
+as $$
+  select case p_applies_when
+           when 'reverse_charge'    then array['domestic_reverse_charge',
+                                               'foreign_services_received',
+                                               'intracom_triangular']
+           when 'intra_eu_goods'    then array['intracom_goods', 'intracom_acquisition_goods']
+           when 'intra_eu_services' then array['intracom_services', 'intracom_acquisition_services']
+           when 'export'            then array['export']
+           when 'exempt'            then array['exempt']
+         end;
+$$;
+
+comment on function legal_mention_treatments(text) is
+  'The tax treatments a condition of legal_mention_templates.applies_when covers, or null for a condition that is not about a treatment (always, late_payment, cash_basis, small_business). The one place that says so: document_legal_mentions reads it to print the sentence, document_tax_summary to give a VAT group its reason.';
+
+revoke execute on function legal_mention_treatments(text) from public, anon;
+grant execute on function legal_mention_treatments(text) to authenticated, service_role;
+
+create or replace view document_legal_mentions
+  with (security_invoker = true) as
+  with document_taxes as (
+    select d.id             as document_id,
+           d.company_id,
+           c.fiscal_country as country,
+           d.document_date,
+           d.doc_type,
+           d.language,
+           coalesce(
+             array_agg(distinct t.treatment::text) filter (where t.treatment is not null),
+             array[]::text[]
+           )                                 as treatments,
+           coalesce(bool_or(t.cash_basis), false) as on_cash_basis
+      from documents d
+      join companies c           on c.id = d.company_id
+      left join document_lines l on l.document_id = d.id
+      left join taxes t          on t.id = l.tax_id
+     group by d.id, d.company_id, c.fiscal_country, d.document_date, d.doc_type, d.language
+  )
+  select dt.document_id,
+         dt.company_id,
+         m.country,
+         m.code,
+         m.applies_when,
+         dt.language,
+         label_for(m.text, m.text_i18n,
+                   preferred_languages(dt.language, dt.company_id)) as text,
+         m.text_i18n,
+         m.sequence,
+         m.legal_reference
+    from document_taxes dt
+    join legal_mention_templates m
+      on m.country = dt.country
+     and m.valid_from <= dt.document_date
+     and (m.valid_to is null or m.valid_to >= dt.document_date)
+   where case m.applies_when
+           when 'always'       then true
+           when 'cash_basis'   then dt.on_cash_basis
+           when 'late_payment' then dt.doc_type in ('sale_invoice', 'sale_credit_note')
+           else coalesce(dt.treatments && legal_mention_treatments(m.applies_when), false)
+         end;
+
+grant select on table document_legal_mentions to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- 2. The breakdown, with its reason
+--
+-- `20260918141107` and three columns. `d.id` and `t.id` are primary keys and
+-- both are grouped on, so the columns of a document and of a tax may be read
+-- without being aggregated. A reader that does not select the reason does not
+-- pay for it: the planner drops an unread scalar subquery from a view, and
+-- `documents_refresh_totals()` reads two sums.
+-- ---------------------------------------------------------------------------
+
+create or replace view document_tax_summary
+  with (security_invoker = true) as
+  select l.document_id,
+         l.company_id,
+         d.doc_type,
+         l.tax_id,
+         t.code    as tax_code,
+         t.name    as tax_name,
+         l.vat_category,
+         l.vat_rate::numeric(12, 4) as tax_rate,
+         sum(l.amount_untaxed) as base_amount,
+         -- Gross tax: what the VAT return reports.
+         round_amount(
+           case when bool_and(l.unit_price_includes_tax)
+                then sum(l.amount_incl_tax)
+                     - sum(l.amount_incl_tax) / (1 + coalesce(l.vat_rate, 0) / 100)
+                else sum(l.amount_untaxed) * coalesce(l.vat_rate, 0) / 100
+           end,
+           rounding_of(l.company_id, d.currency_code)) as tax_amount,
+         -- Charged tax: what the other party actually pays. Zero when the tax
+         -- postings net out, which is exactly what self-assessment means.
+         round_amount(
+           case when bool_and(l.unit_price_includes_tax)
+                then sum(l.amount_incl_tax)
+                     - sum(l.amount_incl_tax) / (1 + coalesce(l.vat_rate, 0) / 100)
+                else sum(l.amount_untaxed) * coalesce(l.vat_rate, 0) / 100
+           end
+           * coalesce((
+               select sum(tp.factor_percent)
+                 from tax_postings tp
+                where tp.tax_id = t.id
+                  and tp.posting_type in ('tax', 'tax_on_base')
+                  and tp.document_kind = case
+                        when d.doc_type in ('sale_credit_note', 'purchase_credit_note')
+                          then 'credit_note'::tax_document_kind
+                        else 'invoice'::tax_document_kind
+                      end
+             ), 100) / 100,
+           rounding_of(l.company_id, d.currency_code)) as tax_charged,
+         t.exemption_code,                                          -- BT-121
+         -- BT-120: the sentence the country puts on an invoice for the
+         -- treatment of this tax, in the language of the document. Several
+         -- sentences for one treatment are several sentences, in their order.
+         (select string_agg(
+                   label_for(m.text, m.text_i18n, preferred_languages(d.language, d.company_id)),
+                   ' ' order by m.sequence, m.code)
+            from legal_mention_templates m
+            join companies c on c.id = d.company_id
+           where m.country = c.fiscal_country
+             and m.valid_from <= d.document_date
+             and (m.valid_to is null or m.valid_to >= d.document_date)
+             and t.treatment::text = any (legal_mention_treatments(m.applies_when))
+         )                             as exemption_reason,
+         t.legal_reference
+    from document_lines l
+    join documents d on d.id = l.document_id
+    left join taxes t on t.id = l.tax_id
+   where l.line_type = 'product'
+   group by l.document_id, l.company_id, d.id, l.tax_id, t.id, l.vat_category, l.vat_rate;
+
+comment on view document_tax_summary is
+  'VAT breakdown of a document, one row per tax, rounded once on the group (EN 16931 BR-CO-14) — on the group''s base, or on the gross it was quoted at where the price includes the tax. The category and the rate are the ones the lines carry: the tax of today for a draft, the tax as it stood for a document that was posted. Where the tax charges nothing it says why: exemption_code is BT-121 as the pack codes it, exemption_reason is BT-120 — the sentence the country puts on an invoice for that treatment, in the language of the document, null where the pack has none. legal_reference is the article the tax rests on, written for whoever reviews the pack and not for a customer.';
+
+grant select on table document_tax_summary to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- 3. The header, with what it left in the tables
+-- ---------------------------------------------------------------------------
+
+create or replace view document_header
+  with (security_invoker = true) as
+  select d.id                             as document_id,
+         d.company_id,
+         d.doc_type,
+         d.state,
+         d.payment_state,
+         d.number,
+         d.supplier_reference,
+         d.document_date,
+         d.accounting_date,
+         d.due_date,
+         d.delivery_date,
+         d.currency_code,
+         d.amount_untaxed,
+         d.amount_tax,
+         d.amount_total,
+         d.amount_paid,
+         d.amount_residual,
+         d.payment_terms,
+         d.payment_means_code,
+         d.payment_reference,
+         d.buyer_reference,
+         d.order_reference,
+         d.contract_reference,
+         d.project_reference,
+         d.note,
+         coalesce(d.payee_iban, seller_bank.iban) as payee_iban,
+         seller_bank.bic                          as payee_bic,
+
+         -- The seller: this company.
+         coalesce(c.trade_name, c.name)   as seller_name,
+         c.legal_name                     as seller_legal_name,
+         c.legal_form                     as seller_legal_form,
+         c.vat_number                     as seller_vat_number,
+         c.registration_number            as seller_registration_number,
+         c.address_line1                  as seller_address_line1,
+         c.address_line2                  as seller_address_line2,
+         c.postal_code                    as seller_postal_code,
+         c.city                           as seller_city,
+         c.country                        as seller_country,
+         c.region                         as seller_region,
+         c.email                          as seller_email,
+         c.phone                          as seller_phone,
+         c.website                        as seller_website,
+         c.logo_url                       as seller_logo_url,
+         c.share_capital                  as seller_share_capital,
+         c.share_capital_currency         as seller_share_capital_currency,
+         c.activity_code                  as seller_activity_code,
+         c.activity_scheme                as seller_activity_scheme,
+         c.document_template,
+
+         -- The buyer: the contact the document is written against.
+         ct.id                            as buyer_id,
+         ct.name                          as buyer_name,
+         ct.vat_number                    as buyer_vat_number,
+         ct.registration_number           as buyer_registration_number,
+         ct.address_line1                 as buyer_address_line1,
+         ct.address_line2                 as buyer_address_line2,
+         ct.postal_code                   as buyer_postal_code,
+         ct.city                          as buyer_city,
+         ct.country                       as buyer_country,
+         ct.region                        as buyer_region,
+         ct.email                         as buyer_email,
+
+         -- What the country of the document requires. Its country is the
+         -- company's fiscal_country — the country whose VAT rules apply — and
+         -- not its address, which is the same distinction
+         -- document_legal_mentions makes.
+         c.fiscal_country                 as country,
+         cd.number_format,
+         cd.numbering_gapless,
+         cd.legal_payment_days,
+         cd.late_payment_reference,
+         cd.tax_point_rule,
+         cd.einvoice_profile,
+         cd.einvoice_mandatory_from,
+         cd.party_scheme,
+         cd.vat_scheme,
+
+         -- What the document is written in. Not the reader's preference and
+         -- not the customer's of today: the document's own, as of the day it
+         -- was issued.
+         d.language,
+
+         -- The day the tax fell due, where somebody stated one (BT-7), and
+         -- where the goods went (BG-15), as far as `documents` records it.
+         d.tax_point_date,
+         d.delivery_address_line1,
+         d.delivery_postal_code,
+         d.delivery_city,
+         d.delivery_country,
+
+         -- Where the network delivers: BT-34 for the seller, BT-49 for the
+         -- buyer. A scheme and a value each, both or neither.
+         c.peppol_scheme                  as seller_peppol_scheme,
+         c.peppol_identifier              as seller_peppol_identifier,
+         ct.peppol_scheme                 as buyer_peppol_scheme,
+         ct.peppol_identifier             as buyer_peppol_identifier
+    from documents d
+    join companies c                on c.id = d.company_id
+    join contacts ct                on ct.id = d.contact_id
+    left join bank_accounts seller_bank on seller_bank.id = c.default_bank_account_id
+    left join country_defaults cd   on cd.country = c.fiscal_country;
+
+comment on view document_header is
+  'One document with everything printed above its lines: the seller, the buyer, the amounts, where it is paid, what its country requires, the language it is written in, the tax point and the delivery where they were stated, and the electronic address of both parties. The lines are document_line_items and the sentences are document_legal_mentions.';
+
+grant select on table document_header to authenticated, service_role;

package/dist/assets/migrations/20260918141627_a_policy_asks_once.sql

@@ -0,0 +1,132 @@
+-- Ekwo OS — a policy asks once per statement, not once per row.
+--
+-- Found by `tests/load/`, the first test of this repository that reads books
+-- of more than fifteen documents, and reads them as a signed-in member rather
+-- than as the owner of the database.
+--
+-- Every table of a company carried the policy
+--
+--     using (has_capability(company_id, 'entries.read'))
+--
+-- and `has_capability()` is `stable`. It was read here — and written down on
+-- the roadmap — as "evaluated once per query". That is not what `stable`
+-- means. It promises Postgres that the function gives the same answer for the
+-- same arguments within one statement; it does not make Postgres remember
+-- the answer. With a column as its argument the function is called for every
+-- row the scan visits, and being SECURITY DEFINER it cannot be inlined: each
+-- call is a function entry and one or two index probes of its own.
+--
+-- Measured on PGlite, five companies of 10 000 documents, one of them read:
+--
+--                     as the owner   as a member   calls of has_capability()
+--   general_ledger          15 ms        133 ms               about  11 700
+--   trial_balance           72 ms      3 266 ms               about 359 000
+--   aged_balance            25 ms        233 ms               about  20 100
+--   vat_return              44 ms        460 ms               about  40 000
+--
+-- The plans were the same on both sides — the same indexes, no sequential
+-- scan — so nothing about the shape of a plan would ever have shown it. The
+-- whole difference is the policy, and it is nine to forty-five times the cost
+-- of the query it guards.
+--
+-- ---------------------------------------------------------------------------
+-- What changes
+--
+-- `companies_with_capability(capability)` answers the same question the other
+-- way round: not "may the caller do this in that company" but "in which
+-- companies may the caller do this", as an array. A policy then reads
+--
+--     using (company_id = any ((select companies_with_capability('entries.read'))::uuid[]))
+--
+-- and the sub-select, which depends on no column, is an InitPlan: Postgres
+-- runs it once per statement and compares every row against the result. As a
+-- bonus the comparison is an ordinary `=` on an indexed column, which the
+-- planner may use to reach the rows, where a function call could only ever
+-- filter them.
+--
+-- **One definition of who may do what.** The new function does not restate
+-- the rules of `has_capability()` — revoked beats granted, a key is consulted
+-- only where there is no member answer. It lists the only companies where the
+-- answer can be yes — those the caller is a member of, and the one a presented
+-- key belongs to — and asks `has_capability()` about each. A change to the
+-- rules changes both, and `tests/capabilities.test.ts` compares the two over
+-- every preset, every capability and a machine key.
+--
+-- **Which policies.** Those whose expression is exactly
+-- `has_capability(company_id, '<capability>')`, in `public`: fifty-two of
+-- them, a select and a write policy on twenty-six tables. They are rewritten
+-- by reading the catalogue rather than by fifty-two statements, so that the
+-- capability each policy names is carried over and cannot be mistyped here.
+-- The block refuses to finish if it found none, or if one of that shape is
+-- left.
+--
+-- `with check` is left as it was. It is evaluated once per row *written*,
+-- which is what a check is for, and a statement that writes ten thousand rows
+-- is an import, not a report.
+--
+-- Left alone, and said so: the policies that combine the test with another
+-- (`attachments`, `api_keys`, `company_members`), the ones that reach the
+-- company through a parent row (`journal_sequences`, `tax_filing_boxes`,
+-- `tax_filing_deposits`), and the modules, whose policies also ask
+-- `module_enabled()`. None of them guards a table a report walks.
+-- `docs/decisions.md` records them.
+
+create or replace function companies_with_capability(p_capability text)
+returns uuid[]
+language sql
+stable
+security definer
+set search_path = public, pg_temp
+as $$
+  select coalesce(array_agg(x.company_id), '{}'::uuid[])
+    from (
+      select m.company_id
+        from company_members m
+       where m.user_id = auth.uid()
+      union
+      select k.company_id
+        from api_keys k
+       where k.key_hash = nullif(current_setting('ekwo.api_key', true), '')
+    ) x
+   where has_capability(x.company_id, p_capability);
+$$;
+
+comment on function companies_with_capability(text) is
+  'The companies in which the current caller may do one named thing — the question has_capability() answers, asked once for all of them. It is what a row level security policy compares company_id against, inside a sub-select, so that the answer is worked out once per statement instead of once per row.';
+
+revoke execute on function companies_with_capability(text) from public, anon;
+grant execute on function companies_with_capability(text) to authenticated, service_role;
+
+do $$
+declare
+  r         record;
+  v_shape   constant text := '^has_capability\(company_id, (''[a-z_.]+'')::text\)$';
+  v_changed integer := 0;
+  v_left    integer;
+begin
+  for r in
+    select p.schemaname, p.tablename, p.policyname,
+           (regexp_match(p.qual, v_shape))[1] as capability
+      from pg_policies p
+     where p.schemaname = 'public'
+       and p.qual ~ v_shape
+     order by p.tablename, p.policyname
+  loop
+    execute format(
+      'alter policy %I on %I.%I using (company_id = any ((select companies_with_capability(%s))::uuid[]))',
+      r.policyname, r.schemaname, r.tablename, r.capability);
+    v_changed := v_changed + 1;
+  end loop;
+
+  if v_changed = 0 then
+    raise exception 'no policy of the shape has_capability(company_id, …) was found: either this ran twice, or the policies changed shape and this migration has to be read again';
+  end if;
+
+  select count(*) into v_left
+    from pg_policies p
+   where p.schemaname = 'public' and p.qual ~ v_shape;
+  if v_left > 0 then
+    raise exception '% policies still call has_capability() once per row', v_left;
+  end if;
+end;
+$$;

package/dist/assets/migrations/20260918143352_a_suggestion_reads_the_words_once.sql

@@ -0,0 +1,204 @@
+-- Ekwo OS — a suggestion looks at the contacts it could be, not at all of them.
+--
+-- Found by `tests/load/`: `suggest_contacts()` over one month of bank
+-- statement — 167 lines, a company of 500 contacts — took 3.5 seconds on
+-- PGlite, twenty milliseconds a line, when the five reports beside it answer
+-- in tens of milliseconds over the whole ledger. With this migration the same
+-- month takes 0.24 seconds, and gives the same answer line for line: the old
+-- body and the new were run side by side over the 167 lines and their 974
+-- suggestions compared — contact, score, method, sentence and alternatives.
+--
+-- Nothing is wrong with its plan. `contacts` is reached through its company
+-- index and no large table is scanned. The cost is what it does to each row:
+-- for every active contact of the company it calls `significant_words()` on
+-- the name — a SQL function with an aggregate in it, which Postgres cannot
+-- inline and so enters once per contact — and then intersects two arrays up
+-- to three times to score the pair. Five hundred contacts is five hundred of
+-- those per statement line, and every one of them but a handful ends in
+-- `score is null`: the names have no word in common. It was written down as a
+-- risk when the function shipped — "O(contacts) per line, fine interactively,
+-- heavy for a year of statements" — and this is the measure of it.
+--
+-- ---------------------------------------------------------------------------
+-- What changes
+--
+-- `contacts.name_words`: the words of the name, stored, worked out by the same
+-- `significant_words()` so the two can never split a name differently. It is a
+-- generated column, so nothing has to remember to maintain it.
+--
+-- It holds **every** word, not only the significant ones. How long a word has
+-- to be to count is a setting of the company (`matching_settings`), and a
+-- stored column cannot depend on a setting; a word of any length is the
+-- superset every setting selects from.
+--
+-- `suggest_contacts()` is replaced whole, with one line added to `by_name`:
+-- `c.name_words && v_words`. That is a filter before the scoring and never a
+-- change to it, because every score the function gives requires a shared
+-- word already:
+--
+--   - 0.900 and the graded 0.650–0.900 are defined on the intersection of the
+--     contact's significant words with the statement's, which is inside the
+--     intersection of *all* the contact's words with the statement's;
+--   - 0.950 is the two names being equal once trimmed and lowercased. The
+--     statement's words are the significant words of that same text, and the
+--     function only reaches this point when there is at least one — so the
+--     contact's name contains it.
+--
+-- So no contact that scored before is set aside now, and the scores, the
+-- sentences and the count of alternatives are computed by the lines that
+-- computed them yesterday. `tests/contact_matching.test.ts` is unchanged and
+-- passes; `tests/load/` reports the time.
+--
+-- ---------------------------------------------------------------------------
+-- What is deliberately not here: an index on `name_words`.
+--
+-- A GIN index on the column is the obvious companion, and it was tried. With
+-- 2 500 contacts in the instance, 500 of them in the company, the planner does
+-- pick it — and the month of statement goes from 238 ms to 217 ms. The time
+-- was never in finding the rows of a company, which `contacts_company_name_idx`
+-- already does; it was in the function calls made on each of them. A tenth of
+-- the time is not worth an index that every write of a contact has to
+-- maintain, so it waits for an instance whose contacts are counted in tens of
+-- thousands, and for a plan that asks for it.
+
+alter table contacts
+  add column name_words text[] generated always as (significant_words(name, 1)) stored;
+
+comment on column contacts.name_words is
+  'Every word of the name, lowercased and deduplicated by significant_words(). Generated. Read by suggest_contacts() to set aside, with one array operator, the contacts whose name shares no word with a statement line — before it scores the ones that do.';
+
+create or replace function suggest_contacts(p_transaction_id uuid)
+returns table (
+  contact_id   uuid,
+  score        numeric,
+  method       text,
+  because      text,
+  alternatives integer
+)
+language plpgsql
+stable
+security invoker
+as $$
+declare
+  v_tx     bank_transactions;
+  v_policy matching_policy;
+  v_words  text[];
+begin
+  -- Row level security answers this select, so a member of another company
+  -- gets nothing and is told nothing.
+  select * into v_tx from bank_transactions t where t.id = p_transaction_id;
+  if not found then
+    raise exception 'not_found: bank transaction %', p_transaction_id
+      using errcode = 'no_data_found';
+  end if;
+
+  v_policy := matching_policy_of(v_tx.company_id);
+  v_words  := significant_words(
+                coalesce(v_tx.counterpart_name, v_tx.description),
+                v_policy.minimum_word_length);
+
+  return query
+  with
+  -- 1. The account the money moved from or to. An account identifier is not a
+  --    resemblance: either the statement carried the one recorded against the
+  --    contact, or it did not. Hence a score of 1, and the only evidence that
+  --    needs no threshold.
+  by_account as (
+    select c.id, 1::numeric as score, 'account'::text as method,
+           format('the statement carries the account recorded against %s', c.name) as because
+    from contacts c
+    where c.company_id = v_tx.company_id
+      and v_tx.counterpart_iban is not null
+      and c.iban is not null
+      and upper(replace(c.iban, ' ', '')) = upper(replace(v_tx.counterpart_iban, ' ', ''))
+    union
+    select p.contact_id, 1::numeric, 'account',
+           format('a motif of %s carries this account', c.name)
+    from contact_patterns p
+    join contacts c on c.id = p.contact_id
+    where p.company_id = v_tx.company_id
+      and p.active
+      and p.kind = 'counterparty_account'
+      and v_tx.counterpart_iban is not null
+      and upper(replace(p.value, ' ', '')) = upper(replace(v_tx.counterpart_iban, ' ', ''))
+  ),
+  -- 2. A motif that was learned or declared. Its score is its confidence: what
+  --    it has been worth so far, and nothing else.
+  by_pattern as (
+    select p.contact_id as id, p.confidence as score,
+           ('pattern:' || p.kind::text)::text as method,
+           format('%s, a motif of %s confirmed %s of %s times',
+                  coalesce(p.value, format('%s to %s', p.amount_min, p.amount_max)),
+                  c.name, p.success_count, p.usage_count) as because
+    from contact_patterns p
+    join contacts c on c.id = p.contact_id
+    where p.company_id = v_tx.company_id
+      and p.active
+      and case p.kind
+            when 'name_variation' then
+              v_tx.counterpart_name is not null
+              and lower(trim(v_tx.counterpart_name)) = lower(trim(p.value))
+            when 'description_keyword' then
+              v_tx.description is not null
+              and position(lower(p.value) in lower(v_tx.description)) > 0
+              and not exists (
+                select 1 from unnest(coalesce(p.exclude_words, '{}'::text[])) as x(word)
+                where position(lower(x.word) in lower(v_tx.description)) > 0
+              )
+            when 'amount_range' then
+              p.currency_code = v_tx.currency_code
+              and abs(v_tx.amount) between p.amount_min and p.amount_max
+            else false
+          end
+  ),
+  -- 3. The name, compared word by word. Three shapes, from the one that says
+  --    the most to the one that says the least, and the last of them is why
+  --    `alternatives` exists.
+  by_name as (
+    select c.id, s.score, 'name'::text as method, s.because
+    from contacts c
+    cross join lateral (
+      select significant_words(c.name, v_policy.minimum_word_length) as words
+    ) w
+    cross join lateral (
+      select
+        case
+          when lower(trim(c.name)) = lower(trim(coalesce(v_tx.counterpart_name, ''))) then 0.950
+          when cardinality(w.words) > 0 and w.words <@ v_words then 0.900
+          when cardinality(w.words) > 0 and v_words <@ w.words then 0.900
+          when cardinality(array(select unnest(w.words) intersect select unnest(v_words))) > 0 then
+            0.650 + 0.250 * (
+              cardinality(array(select unnest(w.words) intersect select unnest(v_words)))::numeric
+              / least(cardinality(w.words), cardinality(v_words))
+            )
+          else null
+        end as score,
+        format('the name on the statement shares %s with %s',
+               array_to_string(array(select unnest(w.words) intersect select unnest(v_words)), ', '),
+               c.name) as because
+    ) s
+    where c.company_id = v_tx.company_id
+      and c.active
+      and cardinality(v_words) > 0
+      -- The one line this migration adds. A contact whose name shares no word
+      -- with the statement scores nothing below, so it is set aside here, by
+      -- an array operator on a stored column, before anything is worked out
+      -- about it.
+      and c.name_words && v_words
+      and s.score is not null
+      and s.score >= v_policy.name_threshold
+  ),
+  all_candidates as (
+    select * from by_account
+    union all select * from by_pattern
+    union all select * from by_name
+  )
+  select a.id, a.score, a.method, a.because,
+         count(*) over (partition by a.method)::integer
+  from all_candidates a
+  order by a.score desc, a.method;
+end;
+$$;
+
+comment on function suggest_contacts(uuid) is
+  'Who this statement line could be, with the score, the evidence in a sentence, and how many contacts that same evidence reached. It writes nothing and decides nothing: a caller that applies a match on its own is expected to require alternatives = 1. Only the contacts whose name shares a word with the line are scored, through contacts.name_words.';