ekwo-os 0.4.1

package/dist/assets/migrations/20260913104232_foreign_key_indexes.sql

@@ -0,0 +1,144 @@
+-- Ekwo OS — a foreign key without an index is a sequential scan waiting for
+-- a big enough table.
+--
+-- Postgres indexes the *referenced* side of a foreign key, because that side
+-- is a primary key. It indexes nothing on the referencing side. Two things
+-- then read the whole table:
+--
+--   * every delete or key update of the parent, which has to prove no child
+--     points at the row — deleting one contact scans `entry_lines`;
+--   * every join written the natural way, which for an accounting core is
+--     most of them: a document to its lines, an entry to its lines, a line to
+--     its account, its tax, its contact.
+--
+-- On the demo company nothing is slow, which is exactly why this survived 49
+-- migrations. On a company with four years of books it is the difference
+-- between a report and a timeout.
+--
+-- 71 indexes: every foreign key of the socle that had none, and the
+-- `company_id` of the tables that had none either — which the sweep covers,
+-- because `company_id` is itself a foreign key everywhere it appears.
+--
+-- Where a table has both a single-column key and a composite one leading with
+-- the same column — `(account_id)` and `(account_id, company_id)`, the shape
+-- this schema uses to keep a child in its parent's company — one index on the
+-- composite serves both, and that is the one created.
+--
+-- The list is not maintained by hand. `tests/schema.test.ts` asks the
+-- catalogue the same question and fails when the answer is not empty, so a
+-- foreign key added later arrives with its index or the build says so.
+
+
+-- public.accounts
+create index if not exists accounts_currency_idx on accounts (currency_code);
+
+-- public.analytic_values
+create index if not exists analytic_values_axis_company_idx on analytic_values (axis_id, company_id);
+create index if not exists analytic_values_company_idx on analytic_values (company_id);
+
+-- public.bank_accounts
+create index if not exists bank_accounts_account_company_idx on bank_accounts (account_id, company_id);
+create index if not exists bank_accounts_currency_idx on bank_accounts (currency_code);
+create index if not exists bank_accounts_journal_company_idx on bank_accounts (journal_id, company_id);
+
+-- public.bank_statements
+create index if not exists bank_statements_bank_account_company_idx on bank_statements (bank_account_id, company_id);
+create index if not exists bank_statements_company_idx on bank_statements (company_id);
+
+-- public.bank_transactions
+create index if not exists bank_transactions_bank_account_company_idx on bank_transactions (bank_account_id, company_id);
+create index if not exists bank_transactions_contact_company_idx on bank_transactions (contact_id, company_id);
+create index if not exists bank_transactions_currency_idx on bank_transactions (currency_code);
+create index if not exists bank_transactions_entry_company_idx on bank_transactions (entry_id, company_id);
+create index if not exists bank_transactions_statement_company_idx on bank_transactions (statement_id, company_id);
+
+-- public.companies
+create index if not exists companies_default_bank_account_idx on companies (default_bank_account_id);
+create index if not exists companies_default_purchase_account_idx on companies (default_purchase_account_id);
+create index if not exists companies_default_sales_account_idx on companies (default_sales_account_id);
+create index if not exists companies_miscellaneous_journal_idx on companies (miscellaneous_journal_id);
+create index if not exists companies_payable_account_idx on companies (payable_account_id);
+create index if not exists companies_purchase_journal_idx on companies (purchase_journal_id);
+create index if not exists companies_receivable_account_idx on companies (receivable_account_id);
+create index if not exists companies_retained_earnings_account_idx on companies (retained_earnings_account_id);
+create index if not exists companies_rounding_account_idx on companies (rounding_account_id);
+create index if not exists companies_sales_journal_idx on companies (sales_journal_id);
+create index if not exists companies_share_capital_currency_idx on companies (share_capital_currency);
+create index if not exists companies_suspense_account_idx on companies (suspense_account_id);
+
+-- public.contacts
+create index if not exists contacts_currency_idx on contacts (currency_code);
+create index if not exists contacts_payable_account_idx on contacts (payable_account_id);
+create index if not exists contacts_receivable_account_idx on contacts (receivable_account_id);
+
+-- public.document_lines
+create index if not exists document_lines_account_company_idx on document_lines (account_id, company_id);
+create index if not exists document_lines_company_idx on document_lines (company_id);
+create index if not exists document_lines_document_company_idx on document_lines (document_id, company_id);
+create index if not exists document_lines_product_company_idx on document_lines (product_id, company_id);
+create index if not exists document_lines_tax_company_idx on document_lines (tax_id, company_id);
+
+-- public.documents
+create index if not exists documents_contact_company_idx on documents (contact_id, company_id);
+create index if not exists documents_currency_idx on documents (currency_code);
+create index if not exists documents_entry_company_idx on documents (entry_id, company_id);
+create index if not exists documents_journal_company_idx on documents (journal_id, company_id);
+create index if not exists documents_reversed_document_idx on documents (reversed_document_id);
+
+-- public.entries
+create index if not exists entries_currency_idx on entries (currency_code);
+create index if not exists entries_journal_company_idx on entries (journal_id, company_id);
+-- `entries_module_idx` is taken, by `(company_id, module_code)` — which does
+-- not lead with `module_code`, so it does not serve the foreign key to
+-- `modules`.
+create index if not exists entries_module_code_idx on entries (module_code);
+create index if not exists entries_reversed_entry_idx on entries (reversed_entry_id);
+
+-- public.entry_line_analytics
+create index if not exists entry_line_analytics_analytic_value_company_idx on entry_line_analytics (analytic_value_id, company_id);
+create index if not exists entry_line_analytics_company_idx on entry_line_analytics (company_id);
+create index if not exists entry_line_analytics_entry_line_company_idx on entry_line_analytics (entry_line_id, company_id);
+
+-- public.entry_lines
+create index if not exists entry_lines_account_company_idx on entry_lines (account_id, company_id);
+create index if not exists entry_lines_contact_company_idx on entry_lines (contact_id, company_id);
+create index if not exists entry_lines_currency_idx on entry_lines (currency_code);
+create index if not exists entry_lines_entry_company_idx on entry_lines (entry_id, company_id);
+create index if not exists entry_lines_tax_company_idx on entry_lines (tax_id, company_id);
+
+-- public.journals
+create index if not exists journals_bank_account_idx on journals (bank_account_id);
+create index if not exists journals_currency_idx on journals (currency_code);
+create index if not exists journals_default_account_idx on journals (default_account_id);
+create index if not exists journals_suspense_account_idx on journals (suspense_account_id);
+
+-- public.payments
+create index if not exists payments_bank_account_idx on payments (bank_account_id);
+create index if not exists payments_contact_company_idx on payments (contact_id, company_id);
+create index if not exists payments_currency_idx on payments (currency_code);
+create index if not exists payments_entry_company_idx on payments (entry_id, company_id);
+create index if not exists payments_journal_company_idx on payments (journal_id, company_id);
+
+-- public.products
+create index if not exists products_currency_idx on products (currency_code);
+create index if not exists products_purchase_account_company_idx on products (purchase_account_id, company_id);
+create index if not exists products_purchase_tax_company_idx on products (purchase_tax_id, company_id);
+create index if not exists products_sale_account_company_idx on products (sale_account_id, company_id);
+create index if not exists products_sale_tax_company_idx on products (sale_tax_id, company_id);
+
+-- public.reconciliations
+create index if not exists reconciliations_credit_line_company_idx on reconciliations (credit_line_id, company_id);
+create index if not exists reconciliations_debit_line_company_idx on reconciliations (debit_line_id, company_id);
+
+-- public.role_capabilities
+create index if not exists role_capabilities_capability_idx on role_capabilities (capability);
+
+-- public.tax_postings
+create index if not exists tax_postings_account_company_idx on tax_postings (account_id, company_id);
+create index if not exists tax_postings_tax_company_idx on tax_postings (tax_id, company_id);
+
+-- public.taxes
+create index if not exists taxes_cash_basis_transition_account_company_idx on taxes (cash_basis_transition_account_id, company_id);
+
+-- public.user_preferences
+create index if not exists user_preferences_preferred_company_idx on user_preferences (preferred_company_id);

package/dist/assets/migrations/20260913105120_declared_no_reader.sql

@@ -0,0 +1,41 @@
+-- Ekwo OS — five columns a pack fills and nothing reads yet, said out loud.
+--
+-- Each was added deliberately, with the same argument: the alternative is
+-- migrating a table of years of rows a second time. That argument is sound and
+-- none of them is removed here. What was missing is the sentence that tells a
+-- reader of `docs/schema.md` which of them are load-bearing today and which
+-- are a promise — because a column with a plausible name and no reader is read
+-- as behaviour by whoever meets it next, and a pack author fills it expecting
+-- something to happen.
+--
+-- Nothing changes but the comments, and `docs/schema.md` is generated from
+-- them, so the doc says it too.
+--
+-- The one that has to become behaviour rather than stay documented is
+-- `currencies.decimal_places`: "at the currency's decimals" is the rounding
+-- rule this repository now states in `docs/decisions.md`, and every rounding
+-- in the schema and in the three JavaScript copies is at two. That is right
+-- for every currency the packs carry and wrong for the yen and the dinar. It
+-- is its own sub-task and it is not this migration.
+
+comment on column country_defaults.rounding_method is
+  'How a country rounds a tax amount, from the pack. **Declared, no reader yet**: every rounding in the schema is round(x, 2), which is half_up, which is what both packs declare — so the column is recorded and not consulted. It becomes behaviour with the sub-task that makes rounding read the currency''s decimals.';
+
+comment on column country_defaults.cash_rounding_unit is
+  'The smallest coin a cash total is rounded to when it is not the cent — 0.05 in Switzerland, 0.05 in the Netherlands for cash. **Declared, no reader yet**: no cash-payment path exists in the socle, so nothing rounds a total to it. Zero means the cent, which is what both packs declare.';
+
+comment on column country_defaults.bank_statement_formats is
+  'Statement formats a bank of this country sends — coda, camt.053, cfonb120 — from the pack. **Declared, no reader yet**: the socle has no statement importer; this is what one will dispatch on. A client that offers an import today reads it to know what to offer.';
+
+comment on column country_defaults.payment_formats is
+  'Payment file formats a bank of this country accepts — pain.001, cfonb160 — from the pack. **Declared, no reader yet**: the socle writes no payment file. Same shape as bank_statement_formats, and it will be read by the same phase.';
+
+comment on column currencies.decimal_places is
+  'Decimals this currency is written with: 2 for the euro, 0 for the yen, 3 for the dinar. **Declared, no reader yet**: every rounding in the schema and in the format packages is at two decimals, which is right for every currency the packs carry. Making the rounding rule read this column is a sub-task of its own; until it lands, a zero-decimal currency is held correctly and rounded as if it had two.';
+
+-- These two are the opposite case and are recorded here so that nobody
+-- mistakes them for the list above: `reconcile()` writes them, `unreconcile()`
+-- reads `fx_entry_id` to reverse the entry it points at, and the MCP server
+-- returns both on a matching. They are read.
+comment on column reconciliations.fx_entry_id is
+  'The entry that booked the realised exchange difference this matching revealed, or null. Written by reconcile() and read by unreconcile(), which reverses it.';

package/dist/assets/migrations/20260913111407_pack_languages.sql

@@ -0,0 +1,223 @@
+-- Ekwo OS — every label a user reads is translatable, and a pack says which
+-- languages it publishes.
+--
+-- The chart of accounts, the declaration boxes, the financial statements, the
+-- legal mentions of an invoice and the fixed-asset categories already carried
+-- `name_i18n` / `text_i18n`. Journals and taxes did not, so a company keeping
+-- its books in Dutch read "Journal des ventes" and "TVA 21 %" next to a chart
+-- of accounts in Dutch. A label without a translation column is a label that
+-- can only ever be shown in the language whoever wrote the pack happened to
+-- speak, so the two that were missing get theirs here, and the country's own
+-- name gets one too.
+--
+-- The shape is the one the rest of the schema already uses: `name` holds the
+-- label in the language of the pack, `name_i18n` is an object keyed by
+-- language code, and `label_for(name, name_i18n, preferred_languages(company))`
+-- is the only way either is read.
+
+-- ---------------------------------------------------------------------------
+-- The columns
+-- ---------------------------------------------------------------------------
+
+alter table journal_templates add column if not exists name_i18n jsonb not null default '{}'::jsonb;
+alter table journals          add column if not exists name_i18n jsonb not null default '{}'::jsonb;
+alter table tax_templates     add column if not exists name_i18n jsonb not null default '{}'::jsonb;
+alter table taxes             add column if not exists name_i18n jsonb not null default '{}'::jsonb;
+alter table country_defaults  add column if not exists name_i18n jsonb not null default '{}'::jsonb;
+alter table country_defaults  add column if not exists languages text[] not null default '{}'::text[];
+
+comment on column journal_templates.name_i18n is
+  'Label by language, from packs/<cc>/i18n/. The language the pack itself is written in stays in `name`.';
+comment on column journals.name_i18n is
+  'Label by language, copied from the template at install. `name` holds the language the company chose, and a company may rename a journal without losing the other languages.';
+comment on column tax_templates.name_i18n is
+  'Label by language, from packs/<cc>/i18n/. A translation of the same tax, never a different rate or a different rule.';
+comment on column taxes.name_i18n is
+  'Label by language, copied from the template at install. `name` holds the language the company chose.';
+comment on column country_defaults.name_i18n is
+  'The country''s own name by language, from packs/<cc>/i18n/. `name` holds it in English, which is what a country pack manifest is written in.';
+comment on column country_defaults.languages is
+  'Languages this country pack publishes every label in, the language of the pack itself first. An installer offers them; nothing in the schema restricts a company to them.';
+
+-- ---------------------------------------------------------------------------
+-- install_country_template, republished
+--
+-- Two statements change. Journals and taxes now copy `name_i18n` and pick the
+-- language the company keeps its books in through `label_for()`, exactly as
+-- the accounts above them already did. Everything else is the function as it
+-- stood.
+-- ---------------------------------------------------------------------------
+
+create or replace function install_country_template(
+  p_company_id uuid,
+  p_country    char(2),
+  p_language   char(2) default null,
+  p_chart_code text default null
+)
+returns void
+language plpgsql
+as $$
+declare
+  v_defaults country_defaults%rowtype;
+  r          record;
+  v_tax_id   uuid;
+  v_language char(2);
+  v_version  text;
+  v_chart    text;
+  v_charts   text;
+begin
+  if not exists (select 1 from companies where id = p_company_id) then
+    raise exception 'unknown_company: %', p_company_id;
+  end if;
+
+  -- Which chart. The caller names one, or the pack's default stands. A named
+  -- chart that does not exist is an error that lists what does: guessing here
+  -- would install the wrong plan of accounts and nobody would notice for a
+  -- year.
+  if p_chart_code is null then
+    select c.code into v_chart
+      from chart_templates c
+     where c.country = p_country and c.is_default;
+    if v_chart is null then
+      -- No pack for this country, or a pack that names no default chart.
+      raise exception 'unknown_country_template: no chart of accounts seeded for %', p_country;
+    end if;
+  else
+    select c.code into v_chart
+      from chart_templates c
+     where c.country = p_country and c.code = p_chart_code;
+    if v_chart is null then
+      select string_agg(c.code, ', ' order by c.code) into v_charts
+        from chart_templates c where c.country = p_country;
+      raise exception 'unknown_chart: % has no chart %. It has: %',
+        p_country, p_chart_code, coalesce(v_charts, 'none');
+    end if;
+  end if;
+
+  if not exists (
+    select 1 from account_templates
+     where country = p_country and chart_code = v_chart
+  ) then
+    raise exception 'unknown_country_template: chart % of % holds no account', v_chart, p_country;
+  end if;
+
+  -- The language of the copy: what the caller asked for, else what the
+  -- company keeps its books in.
+  select coalesce(p_language, c.language) into v_language
+    from companies c where c.id = p_company_id;
+
+  -- 1. Accounts, without the hierarchy.
+  insert into accounts (company_id, code, name, name_i18n, statement_hint,
+                        account_type, reconcilable)
+  select p_company_id, t.code,
+         label_for(t.name, t.name_i18n, array[v_language]),
+         t.name_i18n, t.statement_hint, t.account_type, t.reconcilable
+    from account_templates t
+   where t.country = p_country
+     and t.chart_code = v_chart
+  on conflict (company_id, code) do nothing;
+
+  -- 2. Hierarchy, now that every code exists.
+  update accounts a
+     set parent_id = p.id
+    from account_templates t
+    join accounts p on p.company_id = p_company_id and p.code = t.parent_code
+   where a.company_id = p_company_id
+     and a.code = t.code
+     and t.country = p_country
+     and t.chart_code = v_chart
+     and t.parent_code is not null
+     and a.parent_id is null;
+
+  -- 3. Journals. Common to every chart of the country.
+  insert into journals (company_id, code, name, name_i18n, journal_type)
+  select p_company_id, t.code,
+         label_for(t.name, t.name_i18n, array[v_language]),
+         t.name_i18n, t.journal_type
+    from journal_templates t
+   where t.country = p_country
+  on conflict (company_id, code) do nothing;
+
+  -- 4. Taxes and their postings. Also common: a chart changes how a company
+  --    presents itself, not what it owes.
+  for r in
+    select * from tax_templates where country = p_country order by sequence, code
+  loop
+    v_tax_id := null;
+    insert into taxes (company_id, code, name, name_i18n, description, amount_type, amount,
+                       applies_to, treatment, country, valid_from, valid_to,
+                       legal_reference, vat_category, exemption_code, sequence,
+                       tax_kind, recoverable, jurisdiction, price_include,
+                       cash_basis, cash_basis_transition_account_id)
+    values (p_company_id, r.code,
+            label_for(r.name, r.name_i18n, array[v_language]),
+            r.name_i18n, r.description, r.amount_type, r.amount,
+            r.applies_to, r.treatment, p_country, r.valid_from, r.valid_to,
+            r.legal_reference, r.vat_category, r.exemption_code, r.sequence,
+            r.tax_kind, r.recoverable, r.jurisdiction, r.price_include,
+            r.cash_basis, account_id_by_code(p_company_id, r.cash_basis_transition_account_code))
+    on conflict (company_id, code) do nothing
+    returning id into v_tax_id;
+
+    if v_tax_id is null then
+      continue;
+    end if;
+
+    insert into tax_postings (tax_id, company_id, document_kind, posting_type,
+                              factor_percent, account_id, declaration_box,
+                              box_factor_percent, report_code, sequence)
+    select v_tax_id, p_company_id, tp.document_kind, tp.posting_type,
+           tp.factor_percent, account_id_by_code(p_company_id, tp.account_code),
+           tp.declaration_box, tp.box_factor_percent, tp.report_code, tp.sequence
+      from tax_posting_templates tp
+     where tp.tax_template_id = r.id
+     order by tp.sequence;
+  end loop;
+
+  -- 5. Roles.
+  select * into v_defaults from country_defaults where country = p_country;
+  if found then
+    update companies c
+       set receivable_account_id       = coalesce(c.receivable_account_id, account_id_by_code(p_company_id, v_defaults.receivable_code)),
+           payable_account_id          = coalesce(c.payable_account_id, account_id_by_code(p_company_id, v_defaults.payable_code)),
+           suspense_account_id         = coalesce(c.suspense_account_id, account_id_by_code(p_company_id, v_defaults.suspense_code)),
+           rounding_account_id         = coalesce(c.rounding_account_id, account_id_by_code(p_company_id, v_defaults.rounding_code)),
+           retained_earnings_account_id = coalesce(c.retained_earnings_account_id, account_id_by_code(p_company_id, v_defaults.retained_earnings_code)),
+           default_sales_account_id    = coalesce(c.default_sales_account_id, account_id_by_code(p_company_id, v_defaults.sales_account_code)),
+           default_purchase_account_id = coalesce(c.default_purchase_account_id, account_id_by_code(p_company_id, v_defaults.purchase_account_code)),
+           sales_journal_id            = coalesce(c.sales_journal_id, (select id from journals where company_id = p_company_id and code = v_defaults.sales_journal_code)),
+           purchase_journal_id         = coalesce(c.purchase_journal_id, (select id from journals where company_id = p_company_id and code = v_defaults.purchase_journal_code)),
+           miscellaneous_journal_id    = coalesce(c.miscellaneous_journal_id, (select id from journals where company_id = p_company_id and code = v_defaults.misc_journal_code))
+     where c.id = p_company_id;
+
+    -- 6. The financial journals point at their account.
+    update journals j
+       set default_account_id = account_id_by_code(p_company_id, v_defaults.bank_account_code)
+     where j.company_id = p_company_id
+       and j.journal_type = 'bank'
+       and j.default_account_id is null
+       and v_defaults.bank_account_code is not null;
+
+    update journals j
+       set default_account_id = account_id_by_code(p_company_id, v_defaults.cash_account_code)
+     where j.company_id = p_company_id
+       and j.journal_type = 'cash'
+       and j.default_account_id is null
+       and v_defaults.cash_account_code is not null;
+  end if;
+
+  -- 7. What was copied, from which version, and on which chart.
+  v_version := coalesce((select version from country_packs where country = p_country), '1.0.0');
+
+  insert into company_packs (company_id, country, version, chart_code)
+  values (p_company_id, p_country, v_version, v_chart)
+  on conflict (company_id, country) do update
+     set version = excluded.version,
+         chart_code = excluded.chart_code,
+         upgraded_at = now()
+   where company_packs.version is distinct from excluded.version
+      or company_packs.chart_code is distinct from excluded.chart_code;
+end;
+$$;
+
+revoke execute on all functions in schema public from public;

package/dist/assets/migrations/20260913112233_schema_comments_for_a_reader.sql

@@ -0,0 +1,27 @@
+-- Ekwo OS — schema comments that a reader outside the project can read.
+--
+-- `comment on` is the schema's documentation: it is what `docs/schema.md` is
+-- generated from and what an assistant reads over the API. Five of those
+-- comments named a milestone of the project's own plan — "column only until
+-- P0-6" — which tells somebody reading the schema for the first time nothing
+-- at all, and which two of them had also outlived: cash-basis VAT has been
+-- implemented since, so a comment saying a column had no reader was simply
+-- false.
+--
+-- Nothing changes in the schema itself. A comment is replaced, not added, so
+-- this migration is safe to apply to an installation of any age.
+
+comment on column tax_postings.report_code is
+  'Declaration form the box belongs to. Copied from the template, and read by vat_return(company, from, to, report_code) to pick out the boxes of one form where a country files more than one.';
+
+comment on column tax_templates.cash_basis is
+  'The tax falls due when the invoice is paid rather than when it is issued, which is how France taxes services. post_document() books it on the transition account below and on no declaration box; reconcile() moves the settled share to the account and the box it is declared on.';
+
+comment on column tax_templates.cash_basis_transition_account_code is
+  'Account the tax waits on between the invoice and its payment, by code in the chart of this country. Only read when cash_basis is true.';
+
+comment on column taxes.cash_basis is
+  'The tax falls due when the invoice is paid rather than when it is issued. The share that has been settled is what reaches the declaration.';
+
+comment on column taxes.cash_basis_transition_account_id is
+  'Account the tax waits on between the invoice and its payment. Only read when cash_basis is true.';