ekwo-os 0.4.1

package/dist/assets/migrations/20260918114322_two_definer_functions_check_their_caller.sql

@@ -0,0 +1,75 @@
+-- Ekwo OS — two definer functions checked nobody.
+--
+-- Both were found by `tests/client_preset.test.ts`, which calls every volatile
+-- function a signed-in person may execute, as a guest of the company, and
+-- compares the whole database before and after. Two of them returned quietly.
+--
+-- **`catch_up_journal_sequence()`.** It is SECURITY DEFINER because
+-- `journal_sequences` has a select policy and no other, and its header said
+-- "the caller has already been checked by `post_entry()`". That is true of the
+-- call `post_entry()` makes and of no other: the function is executable by
+-- `authenticated`, takes a journal id, and advanced the counter of that
+-- journal to whatever number it was handed — for a member who only reads, and
+-- for somebody who is not a member of the company at all. `greatest()` kept it
+-- from going backwards, so what it allowed was a hole: the next entry of that
+-- journal numbered 9999 after 0042, in a country whose law forbids exactly
+-- that. It is the sentence `next_entry_number()` was given a guard for on 11
+-- September — "a way to burn numbers in somebody else's journal" — left open
+-- on the function beside it.
+--
+-- It now asks what `next_entry_number()` asks, in the same words: the
+-- installer, or `entries.post` on the company of the journal. Whoever posts an
+-- imported entry holds it, since posting is what calls this. Revoking EXECUTE
+-- instead was not possible: `post_entry()` runs as its caller.
+--
+-- **`touch_api_key()`.** Called by `use_api_key()`, which is definer, so the
+-- inner call runs as the owner and needs no grant of its own. It had one
+-- anyway, from the default privileges of the schema, and stamped
+-- `last_used_at` on any key whose id it was given. The id is not secret the
+-- way the key is, but "this key has not been used for a year" is the signal an
+-- operator withdraws keys on, and anybody signed in could reset it. Nobody but
+-- `use_api_key()` has a reason to call it, so nobody else may.
+
+create or replace function catch_up_journal_sequence(p_journal_id uuid, p_date date, p_number text)
+returns void
+language plpgsql
+security definer
+set search_path = public, pg_temp
+as $$
+declare
+  v_company uuid;
+  v_format  text;
+  v_period  smallint;
+  v_counter integer;
+begin
+  select j.company_id into v_company from journals j where j.id = p_journal_id;
+  if v_company is null then
+    return;
+  end if;
+
+  if not is_installer() and not has_capability(v_company, 'entries.post') then
+    raise exception 'not_allowed: moving a counter in this company needs entries.post'
+      using errcode = '42501';
+  end if;
+
+  select number_format into v_format from numbering_rules(v_company);
+  v_counter := number_counter(v_format, p_number);
+  if v_counter is null then
+    return;
+  end if;
+
+  v_period := case when v_format ~ '\{(YYYY|YY)\}'
+                   then extract(year from p_date)::smallint
+                   else 0::smallint end;
+
+  insert into journal_sequences (journal_id, year, last_number)
+  values (p_journal_id, v_period, v_counter)
+  on conflict (journal_id, year)
+    do update set last_number = greatest(journal_sequences.last_number, excluded.last_number);
+end;
+$$;
+
+comment on function catch_up_journal_sequence(uuid, date, text) is
+  'Advances the counter of a journal to the counter inside a number that was written by hand, so the next automatic number continues the series. Definer, because nobody writes `journal_sequences` directly — and guarded like `next_entry_number()`: the installer, or entries.post on the company of the journal.';
+
+revoke execute on function touch_api_key(uuid) from public, anon, authenticated;

package/dist/assets/migrations/20260918130000_every_company_somebody_keeps.sql

@@ -0,0 +1,177 @@
+-- Ekwo OS — every company somebody keeps, read at once.
+--
+-- `upcoming_filings()` and `filings_touched_since()` take a company. Several
+-- companies inside one instance is the normal case — a firm with its clients —
+-- and a firm that keeps forty of them does not ask "what is due" forty times.
+-- It asks once: *all the companies I keep, what falls due in the fortnight,
+-- and what moved after it went.*
+--
+-- **There is no firm in this file, and no list of clients.** The portfolio is
+-- not an object: it is what the caller may read. Both functions walk the
+-- companies on which the caller holds `filings.read`, and that one sentence is
+-- the whole model — an accountant of forty companies gets forty, the person
+-- who runs one of them gets one, and a group that keeps three of its own gets
+-- three without anybody having been called a firm.
+--
+-- **Both are `security invoker`.** They read nothing a caller could not have
+-- read by asking company by company: row level security on `tax_filings`, on
+-- `company_filing_periods` and on the ledger does the sorting, as it does for
+-- the two functions these are built on. The one thing the policies do not
+-- settle is *which companies to walk* — `companies` is readable by a member
+-- who has had `filings.read` taken away, and by the administrator of the
+-- instance, who creates companies and keeps none of their books. Walking those
+-- would list a calendar with every state empty, which reads as "nothing has
+-- been prepared" and means "you may not know". So the list is filtered on the
+-- capability, in the open, and the test takes the capability away to see the
+-- company leave.
+--
+-- **Silence is not an output.** A reading that leaves a company out when it
+-- has nothing to say cannot be told from a reading that never looked at it, and
+-- over forty companies that is the difference that matters. So every company
+-- of the portfolio is in every answer, and a row with no date says why:
+--
+--   no_deadline_rule  the pack names no day for this form — a country whose
+--                     schedule depends on who is filing — and the period is
+--                     listed without one rather than dropped
+--   nothing_due       the company files, and nothing of it falls in the window
+--   no_form           no cadence recorded and no periodic return the
+--                     installation could name for its fiscal country
+--
+-- **The window is on the day a return is due**, which is the question a
+-- portfolio is asked, and not on the period as `upcoming_filings()` reads it.
+-- A period whose pack names no day has no date to test, so it is listed while
+-- the month that follows it overlaps the window — the only place either rule
+-- of the closed vocabulary ever puts a date.
+
+-- ---------------------------------------------------------------------------
+-- portfolio_upcoming_filings
+-- ---------------------------------------------------------------------------
+
+create or replace function portfolio_upcoming_filings(
+  p_from date,
+  p_to   date
+)
+returns table (
+  company_id   uuid,
+  company_name text,
+  report_code  text,
+  period_start date,
+  period_end   date,
+  due_date     date,
+  state        tax_filing_state,
+  filing_id    uuid,
+  reason       text
+)
+language sql
+stable
+security invoker
+as $$
+  with portfolio as (
+    select c.id, c.name
+      from companies c
+     where has_capability(c.id, 'filings.read')
+  ),
+  -- A return is due in the month that follows its period, plus the days an
+  -- administration grants. So the periods that can fall due from `p_from` on
+  -- ended at most two months and that many days before it, and the calendar
+  -- of a company is asked for once, from there.
+  reach as (
+    select (p_from - interval '2 month'
+            - make_interval(days => coalesce(max(t.deadline_plus_days), 0)))::date as start
+      from tax_report_templates t
+  ),
+  listed as (
+    select p.id as company_id, u.*
+      from portfolio p
+      cross join reach r
+      cross join lateral upcoming_filings(p.id, r.start, p_to) u
+     where case
+             when u.due_date is not null then u.due_date between p_from and p_to
+             else u.period_end < p_to
+                  and (date_trunc('month', u.period_end + interval '2 month')
+                       - interval '1 day')::date >= p_from
+           end
+  )
+  select p.id,
+         p.name,
+         l.report_code,
+         l.period_start,
+         l.period_end,
+         l.due_date,
+         l.state,
+         l.filing_id,
+         case
+           when l.company_id is not null and l.due_date is null then 'no_deadline_rule'
+           when l.company_id is not null then null
+           when periodic_return_code(p.id) is null
+                and not exists (select 1 from company_filing_periods f
+                                 where f.company_id = p.id) then 'no_form'
+           else 'nothing_due'
+         end
+    from portfolio p
+    left join listed l on l.company_id = p.id
+   order by l.due_date nulls last, l.period_end nulls last, p.name, p.id, l.report_code;
+$$;
+
+comment on function portfolio_upcoming_filings(date, date) is
+  'What falls due between two dates in every company the caller holds filings.read on, and in no other: the periods upcoming_filings() produces, kept when the day they are due is in the window. Every company of the portfolio is in the answer at least once, and a row without a date says why in `reason` — no_deadline_rule where the pack names no day for the form, nothing_due where nothing of the company falls in the window, no_form where the installation carries no return for it. Invoker: it reads what the caller could have read company by company.';
+
+revoke execute on function portfolio_upcoming_filings(date, date) from public, anon;
+grant execute on function portfolio_upcoming_filings(date, date) to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- portfolio_filings_touched_since
+--
+-- `filed` is how many declarations of the company had gone and were looked
+-- at, so that a company with no row of disturbance still says what was
+-- examined: six returns and none moved is not the same news as no return.
+-- ---------------------------------------------------------------------------
+
+create or replace function portfolio_filings_touched_since(
+  p_from date default null,
+  p_to   date default null
+)
+returns table (
+  company_id    uuid,
+  company_name  text,
+  filed         integer,
+  filing_id     uuid,
+  report_code   text,
+  period_start  date,
+  period_end    date,
+  state         tax_filing_state,
+  filed_at      timestamptz,
+  entries       integer,
+  last_entry_at timestamptz,
+  boxes_moved   integer
+)
+language sql
+stable
+security invoker
+as $$
+  with portfolio as (
+    select c.id, c.name
+      from companies c
+     where has_capability(c.id, 'filings.read')
+  )
+  select p.id,
+         p.name,
+         (select count(*)::integer
+            from tax_filings f
+           where f.company_id = p.id
+             and f.filed_at is not null
+             and f.state <> 'superseded'
+             and (p_from is null or f.period_end >= p_from)
+             and (p_to is null or f.period_start <= p_to)),
+         t.filing_id, t.report_code, t.period_start, t.period_end, t.state,
+         t.filed_at, t.entries, t.last_entry_at, t.boxes_moved
+    from portfolio p
+    left join lateral filings_touched_since(p.id, p_from, p_to) t on true
+   order by t.last_entry_at desc nulls last, p.name, p.id, t.period_start, t.report_code;
+$$;
+
+comment on function portfolio_filings_touched_since(date, date) is
+  'Declarations that have gone and whose period the ledger moved afterwards, in every company the caller holds filings.read on, and in no other — filings_touched_since() with the company named, the latest disturbance first. Every company of the portfolio is in the answer at least once: one that was not disturbed is a row with no filing, and `filed` says how many of its declarations were looked at. Invoker: it reads what the caller could have read company by company.';
+
+revoke execute on function portfolio_filings_touched_since(date, date) from public, anon;
+grant execute on function portfolio_filings_touched_since(date, date) to authenticated, service_role;

package/dist/assets/migrations/20260918140000_a_session_nobody_prepared.sql

@@ -0,0 +1,40 @@
+-- ---------------------------------------------------------------------------
+-- A session nobody prepared is not the installer
+-- ---------------------------------------------------------------------------
+-- `is_installer()` ended on `current_setting('ekwo.installing', true) = 'on'`.
+-- A setting that was set and emptied answers '', and '' = 'on' is false. A
+-- setting that was NEVER set answers NULL, and NULL = 'on' is NULL — so on a
+-- new connection the function answered NULL, and every guard written
+--
+--     if not is_installer() and not has_capability(…) then raise …
+--
+-- evaluated `NULL and true`, which is NULL, which `if` does not take. The
+-- guard was skipped. A person always carries a `sub` and is answered by
+-- `has_capability()`; the caller with neither a session nor a key — the
+-- `service_role` through PostgREST, a direct connection — walked through
+-- create_company(), the counters, the API keys and the module switches.
+--
+-- The migration that introduced the function was the one about guards that
+-- could answer NULL, and its tests never saw this one: the harness always set
+-- the variable, to 'on' for the owner and to '' for a person. A test now
+-- reloads the database into an instance where nothing was ever set
+-- (tests/fresh_session.test.ts) and asks every argument-less boolean helper
+-- the same question.
+--
+-- `service_role` bypasses row level security on Supabase, by design of the
+-- platform. It does not bypass a function that raises — which is why the
+-- functions are where an installation's rules are, and why this mattered.
+-- ---------------------------------------------------------------------------
+
+create or replace function is_installer()
+returns boolean
+language sql
+stable
+as $$
+  select auth.uid() is null
+     and nullif(current_setting('ekwo.api_key', true), '') is null
+     and coalesce(current_setting('ekwo.installing', true) = 'on', false);
+$$;
+
+comment on function is_installer() is
+  'Whether the caller is the installation itself — the migration runner, the seeds, the CLI — rather than a person or a machine key. Set by the runner on its own connection; a session or a key can never be it, and neither can a connection where the setting was never made: the answer is false there, never NULL, because the guards negate it.';

package/dist/assets/migrations/20260918141107_a_line_keeps_the_tax_it_was_posted_with.sql

@@ -0,0 +1,256 @@
+-- Ekwo OS — a line keeps the category and the rate it was posted with.
+--
+-- `document_lines.vat_category` and `.vat_rate` have been there since the
+-- table was, and three migrations have cited them as the precedent for a
+-- snapshot: `20260915191200` for the language of a document, `20260915195000`
+-- for a price that holds its tax, `20260915181000` for a territory. Nothing
+-- ever wrote them. Every line of every golden year has them null, the view
+-- publishes them as BT-151 and BT-152 all the same, and the first reader that
+-- needed them — the brick that writes a Peppol invoice — found nothing and
+-- went round by `tax_id`. `tests/vat_category.test.ts` had found it earlier
+-- and said so in a comment: "Nothing in the core writes it."
+--
+-- The two ways out were to fill the columns or to take them out of the view.
+-- They are filled, and the reason is the one those three migrations gave
+-- while believing it already true: **what is posted does not move.** A tax
+-- belongs to a company and a pack upgrade rewrites it in place — `amount`,
+-- `vat_category` and the rest, in one `update taxes` — so a view that reads
+-- the category and the rate of a sent invoice through `tax_id` reads what the
+-- pack says today. A rate that changes on 1 January would restate every
+-- invoice of December the first time anybody rendered one.
+--
+-- Four decisions.
+--
+-- **Derived, never keyed.** The category and the rate are facts about the tax
+-- and not choices of the line, which is what `unit_price_includes_tax` is
+-- already: a caller that writes them is overwritten while the document is a
+-- draft. `vat_rate` is a percentage, so a tax that is a fixed amount leaves it
+-- null — BT-152 has no room for an amount, and `post_document()` refuses such
+-- a tax anyway.
+--
+-- **A draft follows its tax; a posted line refuses to move.** The same shape
+-- as `documents_guard_language`: the line trigger reads the tax on every write
+-- of a draft, a tax that changes reaches the drafts that carry it, and from
+-- the moment the document is no longer a draft a change to either column is
+-- refused by name, `document_line_tax_frozen`. Refused rather than quietly
+-- ignored, because the one caller with a reason to write these columns is an
+-- application that used to do the core's job, and it should learn that it no
+-- longer has to.
+--
+-- **The breakdown reads the line, not the tax.** `document_tax_summary` is
+-- BT-118 and BT-119, and it is also where `documents_refresh_totals()` and
+-- `post_document()` take their figures. Reading the category and the rate
+-- from the tax there while the lines carry a snapshot would have made the two
+-- halves of one invoice disagree the day a rate moves — and would have kept
+-- the older hazard, which is that touching a line of a posted document
+-- recomputes its totals at today's rate. The view now groups on what the lines
+-- carry. For a draft that is the tax, by construction; for a posted document
+-- it is the tax as it stood. Same columns, same order, same types.
+--
+-- **The lines already here take the tax of today, once.** Nobody knows what
+-- rate a tax had on the day an old invoice was posted: the ledger kept the
+-- amounts and not the percentage. The tax as it stands is the only evidence
+-- the installation holds, it is what every read of these documents has
+-- answered until now, and it is what the totals were last computed from — so
+-- the backfill changes no figure. It is a guess for the same reason the
+-- backfill of `documents.language` was, and from here on nothing is guessed.
+-- A line somebody's application had already stamped keeps its stamp.
+--
+-- What this does not close, and says so: the *share* of a tax that reaches the
+-- other party (`tax_charged`) is still read from `tax_postings` as they stand,
+-- and the exemption code and the legal reference of a tax are still read from
+-- the tax. None of the three changes a base or a rate; all three are a pack
+-- correcting itself under a document already sent. And no trigger refuses a
+-- change of `quantity`, `unit_price` or `tax_id` on a posted line: the ledger
+-- is immutable and the document that produced it is only partly so. That is
+-- older than this file and wider than it.
+
+-- ---------------------------------------------------------------------------
+-- 1. What the lines already here carry
+--
+-- Before the guard exists, because it would refuse exactly this. The row
+-- triggers fire, as they did for the backfill of `documents.language`: the
+-- totals they recompute are read from the same tax the snapshot is being
+-- taken from, so they come back unchanged.
+-- ---------------------------------------------------------------------------
+
+update document_lines l
+   set vat_category = t.vat_category,
+       vat_rate     = case when t.amount_type = 'percent' then t.amount end
+  from taxes t, documents d
+ where t.id = l.tax_id
+   and d.id = l.document_id
+   and l.line_type = 'product'
+   and (d.state = 'draft' or (l.vat_category is null and l.vat_rate is null))
+   and (l.vat_category is distinct from t.vat_category
+        or l.vat_rate is distinct from case when t.amount_type = 'percent' then t.amount end);
+
+-- ---------------------------------------------------------------------------
+-- 2. Writing it, and refusing to rewrite it
+-- ---------------------------------------------------------------------------
+
+create or replace function document_lines_snapshot_tax()
+returns trigger
+language plpgsql
+as $$
+declare
+  v_state  doc_state;
+  v_number text;
+begin
+  select d.state, d.number into v_state, v_number
+    from documents d where d.id = new.document_id;
+
+  if tg_op = 'UPDATE' and v_state <> 'draft' then
+    if new.vat_category is distinct from old.vat_category
+       or new.vat_rate is distinct from old.vat_rate then
+      raise exception 'document_line_tax_frozen: line % of % was posted under category % at % per cent, and keeps both. A document already issued is not rewritten because its tax changed; credit it and issue another.',
+        new.sequence, coalesce(v_number, new.document_id::text),
+        coalesce(old.vat_category, 'none'), coalesce(old.vat_rate::text, 'no')
+        using errcode = '55006';
+    end if;
+    return new;
+  end if;
+
+  if new.line_type <> 'product' or new.tax_id is null then
+    new.vat_category := null;
+    new.vat_rate     := null;
+    return new;
+  end if;
+
+  select t.vat_category,
+         case when t.amount_type = 'percent' then t.amount end
+    into new.vat_category, new.vat_rate
+    from taxes t where t.id = new.tax_id;
+  return new;
+end;
+$$;
+
+comment on function document_lines_snapshot_tax() is
+  'Writes BT-151 and BT-152 on a line from its tax for as long as the document is a draft, and refuses document_line_tax_frozen on a change to either once it is not.';
+
+create trigger document_lines_snapshot_tax
+  before insert or update on document_lines
+  for each row execute function document_lines_snapshot_tax();
+
+-- A trigger body is invoked by its table, never called.
+revoke execute on function document_lines_snapshot_tax() from public, anon, authenticated, service_role;
+
+comment on column document_lines.vat_category is
+  'EN 16931 BT-151 as the line carries it. Derived from the tax while the document is a draft and frozen when it is posted, so a pack upgrade that recategorises a tax cannot rewrite an invoice that has been sent. Never keyed.';
+
+comment on column document_lines.vat_rate is
+  'EN 16931 BT-152 as the line carries it: the percentage of the tax, derived while the document is a draft and frozen when it is posted, so a later change of rate cannot rewrite an invoice that has been sent. Null where the tax is not a percentage. Never keyed.';
+
+-- ---------------------------------------------------------------------------
+-- 3. A tax that changes, and the drafts that carry it
+--
+-- The other half of "a draft follows its tax": a draft nobody touches again
+-- would keep an answer that is no longer the tax's. Bounded to the draft lines
+-- of that one tax — `document_lines_tax_idx` is the index it reads — and the
+-- write goes through the line's own triggers, so the totals of those drafts
+-- follow the new rate too, which until now they did not until somebody edited
+-- a line.
+--
+-- `price_include` is deliberately not among the columns that fire it. The
+-- lines are rewritten one at a time, and a group caught half way between a
+-- price with its tax and a price without is what `mixed_price_include`
+-- refuses: the flag would make the correction of a tax fail on the first
+-- draft with two lines. That snapshot keeps the rule it was published with.
+--
+-- `security definer`, for the reason `contacts_language_reaches_drafts` gives:
+-- whoever may correct a tax is not thereby allowed to write a document, and
+-- should not be refused because a draft sits behind a policy they do not
+-- satisfy. What is written is derived data on rows nothing has issued yet.
+-- ---------------------------------------------------------------------------
+
+create or replace function taxes_reach_draft_lines()
+returns trigger
+language plpgsql
+security definer
+set search_path = public, pg_temp
+as $$
+begin
+  update document_lines l
+     set vat_category = new.vat_category
+    from documents d
+   where l.tax_id = new.id
+     and d.id = l.document_id
+     and d.state = 'draft';
+  return null;
+end;
+$$;
+
+comment on function taxes_reach_draft_lines() is
+  'A tax whose category, rate or kind of amount changes rewrites the snapshot of the draft lines that carry it, and nothing else: a posted line keeps what it was posted with.';
+
+create trigger taxes_reach_draft_lines
+  after update of vat_category, amount, amount_type on taxes
+  for each row
+  when (new.vat_category is distinct from old.vat_category
+        or new.amount is distinct from old.amount
+        or new.amount_type is distinct from old.amount_type)
+  execute function taxes_reach_draft_lines();
+
+revoke execute on function taxes_reach_draft_lines() from public, anon, authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- 4. The breakdown groups on what the lines carry
+--
+-- `20260915195000` unchanged but for where the category and the rate come
+-- from. `tax_rate` keeps the type it had — a view column cannot change type
+-- under `create or replace` — and the arithmetic reads the same figure it
+-- publishes. `security_invoker`, the comment and the grants are those of the
+-- object it replaces; the grants are restated because saying so again is
+-- cheaper than trusting it.
+-- ---------------------------------------------------------------------------
+
+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
+    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.doc_type, d.currency_code, l.tax_id,
+            t.id, t.code, t.name, 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.';
+
+grant select on table document_tax_summary to authenticated, service_role;

package/dist/assets/migrations/20260918141342_a_company_has_an_electronic_address.sql

@@ -0,0 +1,66 @@
+-- Ekwo OS — the company that sends an invoice has an address to send it from.
+--
+-- `contacts` has carried `peppol_scheme` and `peppol_identifier` since the
+-- first day: the electronic address of the buyer, BT-49. The seller had
+-- neither. BT-34 is mandatory on the network, so the first brick that wrote a
+-- Peppol invoice had to be *told* the seller's address by its caller, and the
+-- end-to-end test registered the company under its VAT number and said that
+-- it was the test's choice. It is nobody's choice: which identifier a
+-- participant is registered under is a fact of its registration with an access
+-- point, and the only party that knows it is the company.
+--
+-- **The same two columns, under the same two names.** A scheme and a value,
+-- which is the shape `docs/international.md` asks every identifier of this
+-- schema to take. `peppol_` is the name `contacts` already uses and a second
+-- name for the same thing would be a join somebody has to remember; the scheme
+-- is a code of the Electronic Address Scheme list (EAS) that EN 16931 cites
+-- for BT-34-1 and BT-49-1, whichever network delivers.
+--
+-- **No list of schemes.** `contacts` has none and the core gets none here: the
+-- list is published by the Connecting Europe Facility, revised twice a year,
+-- and differs between EN 16931 and Peppol — the brick that writes the file
+-- carries both and names the rule a scheme breaks. A list here would be a
+-- third copy, and the one most likely to be stale.
+--
+-- **One constraint `contacts` does not have: the pair is whole or absent.** A
+-- scheme without an identifier addresses nobody and an identifier without a
+-- scheme cannot be written at all (BR-62). The columns are new on `companies`,
+-- so the check refuses nothing that exists. On `contacts` they are not, and
+-- an installation may hold half a pair somebody typed in 2026; a constraint
+-- added there would either refuse this migration or, `not valid`, refuse the
+-- next unrelated edit of that contact. It is left for the release that can
+-- look at the data first.
+--
+-- **Who may write it** is who may write the company: `companies_update`
+-- judges the row, `company.write`, and there is nothing in an electronic
+-- address that a member allowed to change the VAT number should not change.
+--
+-- The second half of this file corrects two comments. `party_scheme` and
+-- `vat_scheme` were documented as "ISO 6523 ICD", and the packs — rightly —
+-- fill them with codes of the EAS list, which contains the ICD list and more:
+-- the VAT schemes of the 99xx range are not ISO 6523 identifiers at all. Read
+-- as documented, `party_scheme` was taken for the scheme a registration number
+-- is written in (BT-30-1) and produced BR-CL-11 for two packs out of four.
+
+alter table companies
+  add column if not exists peppol_scheme     text,
+  add column if not exists peppol_identifier text;
+
+alter table companies
+  add constraint companies_electronic_address_whole
+  check ((peppol_scheme is null) = (peppol_identifier is null));
+
+comment on column companies.peppol_scheme is
+  'Scheme of the electronic address this company receives and sends under (EN 16931 BT-34-1): a code of the Electronic Address Scheme list, e.g. 0088 for a GLN. A fact of the company''s registration with its access point, never derived from its VAT or registration number. Null together with peppol_identifier.';
+comment on column companies.peppol_identifier is
+  'The electronic address itself (EN 16931 BT-34), in the scheme peppol_scheme names.';
+
+comment on column contacts.peppol_scheme is
+  'Scheme of the electronic address this party is reached at (EN 16931 BT-49-1): a code of the Electronic Address Scheme list. A fact of the party''s registration, never derived from its VAT or registration number.';
+comment on column contacts.peppol_identifier is
+  'The electronic address itself (EN 16931 BT-49), in the scheme peppol_scheme names.';
+
+comment on column country_defaults.party_scheme is
+  'The Electronic Address Scheme (EAS) code under which a party of this country is usually *addressed* on the network — the scheme of an electronic address, BT-34-1 and BT-49-1. Four characters; the pack carries the value and the core never guesses one. It is a default an application may propose, not the address of anybody: that is companies.peppol_scheme and contacts.peppol_scheme. And it is not the scheme a registration number is written in (BT-30-1, BT-47-1), which has to be an ISO 6523 ICD: several EAS codes are not.';
+comment on column country_defaults.vat_scheme is
+  'The Electronic Address Scheme (EAS) code under which a party of this country is addressed by its VAT number, where the network allows it. Distinct from party_scheme: a company is addressed by its registration number or by its VAT number, and they are not the same identifier. Not an ISO 6523 ICD in general — the VAT schemes of the EAS list are outside that standard.';