ekwo-os 0.4.1

package/dist/assets/migrations/20260911130100_instance_members.sql

@@ -0,0 +1,224 @@
+-- Ekwo OS — the instance-level role.
+--
+-- `member_role` is now one vocabulary for the whole installation:
+-- `instance_admin` at instance level, `owner` / `accountant` / `viewer` per
+-- company. The storage is split because the keys differ — a company role is
+-- keyed by (company, user), an instance role by user alone — and a nullable
+-- company in `company_members` would break its primary key and its meaning.
+-- Two check constraints keep each table to the roles it may carry.
+--
+-- Users live in the customer's own Supabase Auth. `user_id` holds an
+-- `auth.users.id` from their project; Ekwo never holds an account.
+
+create table instance_members (
+  user_id    uuid primary key,
+  role       member_role not null default 'instance_admin',
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  -- The only instance-level role today. Widening this is a deliberate act.
+  constraint instance_members_role_is_instance_level check (role = 'instance_admin')
+);
+
+comment on table instance_members is
+  'Instance administrators: they create companies and invite members. user_id is an auth.users id from the customer''s own Supabase project.';
+comment on column instance_members.user_id is
+  'An auth.users.id in the customer''s Supabase Auth. No foreign key, so the schema installs on a plain Postgres and seeds never write into auth.';
+
+create trigger instance_members_set_updated_at
+  before update on instance_members
+  for each row execute function set_updated_at();
+
+-- A company role is a company role.
+alter table company_members
+  add constraint company_members_role_is_company_level check (role <> 'instance_admin');
+
+-- ---------------------------------------------------------------------------
+-- Helpers
+-- ---------------------------------------------------------------------------
+
+-- SECURITY DEFINER so the policy on instance_members does not recurse into
+-- the table it protects.
+create or replace function is_instance_admin()
+returns boolean
+language sql
+stable
+security definer
+set search_path = public, pg_temp
+as $$
+  select exists (
+    select 1 from instance_members m
+     where m.user_id = auth.uid() and m.role = 'instance_admin'
+  );
+$$;
+
+comment on function is_instance_admin() is
+  'Whether the current user administers this installation.';
+
+create or replace function instance_has_no_admin()
+returns boolean
+language sql
+stable
+security definer
+set search_path = public, pg_temp
+as $$
+  select not exists (select 1 from instance_members);
+$$;
+
+-- ---------------------------------------------------------------------------
+-- Installation
+-- ---------------------------------------------------------------------------
+
+create or replace function init_instance(
+  p_organization_name text,
+  p_country           char(2),
+  p_edition           instance_edition default 'community'
+)
+returns instance
+language plpgsql
+as $$
+declare
+  v_row instance%rowtype;
+begin
+  if exists (select 1 from instance) then
+    raise exception 'instance_already_initialised: this installation is already set up';
+  end if;
+
+  insert into instance (id, organization_name, country, edition, schema_version)
+  values (1, p_organization_name, upper(p_country), p_edition, ekwo_schema_version())
+  returning * into v_row;
+
+  return v_row;
+end;
+$$;
+
+comment on function init_instance(text, char, instance_edition) is
+  'Records the installation. Called once, by the installer. Leaves the registration fields empty.';
+
+-- The first user to ask takes the instance. After that, only an existing
+-- administrator can appoint another.
+create or replace function claim_instance_admin(p_user_id uuid default auth.uid())
+returns instance_members
+language plpgsql
+as $$
+declare
+  v_row instance_members%rowtype;
+begin
+  if p_user_id is null then
+    raise exception 'no_user: claim_instance_admin needs a signed-in user or an explicit id';
+  end if;
+
+  if exists (select 1 from instance_members) and not is_instance_admin() then
+    raise exception 'instance_already_claimed: only an instance administrator can appoint another';
+  end if;
+
+  insert into instance_members (user_id, role)
+  values (p_user_id, 'instance_admin')
+  on conflict (user_id) do update set role = 'instance_admin'
+  returning * into v_row;
+
+  return v_row;
+end;
+$$;
+
+comment on function claim_instance_admin(uuid) is
+  'Makes a user an instance administrator. The first claim is open; afterwards only an administrator may appoint one.';
+
+-- Opt-in registration with Ekwo. Nothing calls this on its own.
+create or replace function register_instance(p_contact_email text)
+returns instance
+language plpgsql
+as $$
+declare
+  v_row instance%rowtype;
+begin
+  if not is_instance_admin() then
+    raise exception 'not_instance_admin: only an instance administrator can register this installation';
+  end if;
+
+  update instance
+     set contact_email = p_contact_email,
+         registered_at = now()
+   where id = 1
+  returning * into v_row;
+
+  if not found then
+    raise exception 'instance_not_initialised: call init_instance() first';
+  end if;
+
+  return v_row;
+end;
+$$;
+
+comment on function register_instance(text) is
+  'Opt-in: records an address and a date so Ekwo can reach the operator. Never required, and reversible with unregister_instance().';
+
+create or replace function unregister_instance()
+returns instance
+language plpgsql
+as $$
+declare
+  v_row instance%rowtype;
+begin
+  if not is_instance_admin() then
+    raise exception 'not_instance_admin: only an instance administrator can unregister this installation';
+  end if;
+
+  update instance set contact_email = null, registered_at = null where id = 1
+  returning * into v_row;
+
+  return v_row;
+end;
+$$;
+
+comment on function unregister_instance() is
+  'Undoes register_instance(). Opting in is reversible, or it is not a choice.';
+
+-- ---------------------------------------------------------------------------
+-- Row level security
+-- ---------------------------------------------------------------------------
+
+alter table instance_members enable row level security;
+
+create policy instance_members_select on instance_members
+  for select using (auth.uid() is not null);
+create policy instance_members_insert on instance_members
+  for insert with check (is_instance_admin() or instance_has_no_admin());
+create policy instance_members_update on instance_members
+  for update using (is_instance_admin()) with check (is_instance_admin());
+create policy instance_members_delete on instance_members
+  for delete using (is_instance_admin());
+
+create policy instance_write on instance
+  for all using (is_instance_admin()) with check (is_instance_admin());
+
+-- Creating a company is an instance-level act. The select policy has to
+-- follow: `insert ... returning` is checked against it too, so without this
+-- an administrator would create a company and still get an error back.
+drop policy companies_insert on companies;
+create policy companies_insert on companies
+  for insert with check (is_instance_admin());
+
+drop policy companies_select on companies;
+create policy companies_select on companies
+  for select using (is_company_member(id) or is_instance_admin());
+
+-- An instance administrator may invite members into any company.
+drop policy company_members_insert on company_members;
+create policy company_members_insert on company_members
+  for insert with check (
+    is_company_owner(company_id)
+    or is_instance_admin()
+    or company_has_no_member(company_id)
+  );
+
+drop policy company_members_select on company_members;
+create policy company_members_select on company_members
+  for select using (
+    user_id = auth.uid() or is_company_member(company_id) or is_instance_admin()
+  );
+
+-- ... and an instance administrator may administer a company they are not in.
+drop policy companies_update on companies;
+create policy companies_update on companies
+  for update using (is_company_owner(id) or is_instance_admin())
+  with check (is_company_owner(id) or is_instance_admin());

package/dist/assets/migrations/20260911140000_instance_admins.sql

@@ -0,0 +1,112 @@
+-- Ekwo OS — instance administrators, final shape.
+--
+-- Three changes on top of the previous migration, additive as always:
+--
+--   1. `instance_members` becomes `instance_admins`. The table name carries
+--      the role, so the `role` column carried nothing.
+--   2. `user_id` gets a real foreign key to `auth.users`. An administrator is
+--      necessarily a signed-in user, so there is no invite-before-signup case
+--      to accommodate here. `company_members` deliberately keeps no such key:
+--      inviting someone into a company before they have an account is a
+--      normal thing to want.
+--   3. Reading the instance row is for people who are actually on this
+--      installation — a member of at least one company, or an administrator —
+--      rather than anyone holding a token.
+
+alter table instance_members rename to instance_admins;
+
+alter policy instance_members_select on instance_admins rename to instance_admins_select;
+alter policy instance_members_insert on instance_admins rename to instance_admins_insert;
+alter policy instance_members_update on instance_admins rename to instance_admins_update;
+alter policy instance_members_delete on instance_admins rename to instance_admins_delete;
+
+alter table instance_admins drop constraint instance_members_role_is_instance_level;
+alter table instance_admins drop column role;
+
+alter table instance_admins
+  add constraint instance_admins_user_fkey
+    foreign key (user_id) references auth.users(id) on delete cascade;
+
+comment on table instance_admins is
+  'Instance administrators: they create companies and invite members. One row per user, keyed on auth.users of the customer''s own Supabase project.';
+comment on column instance_admins.user_id is
+  'An auth.users.id in the customer''s Supabase Auth. Ekwo holds no account and no directory.';
+
+-- ---------------------------------------------------------------------------
+-- Helpers, against the renamed table
+-- ---------------------------------------------------------------------------
+
+create or replace function is_instance_admin()
+returns boolean
+language sql
+stable
+security definer
+set search_path = public, pg_temp
+as $$
+  select exists (select 1 from instance_admins a where a.user_id = auth.uid());
+$$;
+
+create or replace function instance_has_no_admin()
+returns boolean
+language sql
+stable
+security definer
+set search_path = public, pg_temp
+as $$
+  select not exists (select 1 from instance_admins);
+$$;
+
+-- Whether the current user is on the books of at least one company here.
+create or replace function is_any_company_member()
+returns boolean
+language sql
+stable
+security definer
+set search_path = public, pg_temp
+as $$
+  select exists (select 1 from company_members m where m.user_id = auth.uid());
+$$;
+
+comment on function is_any_company_member() is
+  'Whether the current user belongs to at least one company of this installation.';
+
+drop function if exists claim_instance_admin(uuid);
+
+create or replace function claim_instance_admin(p_user_id uuid default auth.uid())
+returns instance_admins
+language plpgsql
+as $$
+declare
+  v_row instance_admins%rowtype;
+begin
+  if p_user_id is null then
+    raise exception 'no_user: claim_instance_admin needs a signed-in user or an explicit id';
+  end if;
+
+  if exists (select 1 from instance_admins) and not is_instance_admin() then
+    raise exception 'instance_already_claimed: only an instance administrator can appoint another';
+  end if;
+
+  insert into instance_admins (user_id)
+  values (p_user_id)
+  on conflict (user_id) do nothing
+  returning * into v_row;
+
+  if v_row.user_id is null then
+    select * into v_row from instance_admins where user_id = p_user_id;
+  end if;
+
+  return v_row;
+end;
+$$;
+
+comment on function claim_instance_admin(uuid) is
+  'Makes a user an instance administrator. The first claim is open; afterwards only an administrator may appoint one.';
+
+-- ---------------------------------------------------------------------------
+-- Reading the instance row
+-- ---------------------------------------------------------------------------
+
+drop policy instance_select on instance;
+create policy instance_select on instance
+  for select using (is_any_company_member() or is_instance_admin());

package/dist/assets/migrations/20260911160000_tax_posting_templates_unique.sql

@@ -0,0 +1,17 @@
+-- Ekwo OS — one natural key for tax posting templates.
+--
+-- `tax_posting_templates` had a surrogate primary key and a partial unique
+-- index on the base line only, so re-applying a seed inserted every tax line
+-- a second time and then failed on the base. Found on the first real
+-- installation, when `ekwo init` was run twice on the same project.
+--
+-- A posting template is identified by the tax, the kind of document, the
+-- posting type and its sequence. Making that a unique index gives the seeds a
+-- conflict target and makes them idempotent, which `supabase/seed/README.md`
+-- had promised all along.
+
+create unique index tax_posting_templates_natural_key_idx
+  on tax_posting_templates (tax_template_id, document_kind, posting_type, sequence);
+
+comment on index tax_posting_templates_natural_key_idx is
+  'The natural key of a posting template; the conflict target of the seeds.';

package/dist/assets/migrations/20260911170000_document_amount_paid.sql

@@ -0,0 +1,82 @@
+-- Ekwo OS — a document's settlement is derived from its matching.
+--
+-- `documents.amount_paid` was a column somebody had to remember to write, while
+-- the truth of what has been settled lived in `reconciliations`. That is the
+-- rule of this schema broken on its own terms: totals are derived, never keyed
+-- in. Matching a third-party line now moves the document, and `payment_state`
+-- follows from there as it already did.
+--
+-- The recomputation is folded into the existing reconciliation trigger rather
+-- than added as a second one, because two AFTER ROW triggers on the same table
+-- fire in name order, and this one has to run after the line residuals have
+-- been updated, not before.
+
+create or replace function documents_refresh_amount_paid(p_document_id uuid)
+returns void
+language plpgsql
+as $$
+begin
+  -- The statement names amount_paid so that documents_refresh_payment_state,
+  -- which watches that column, fires in turn.
+  update documents d
+     set amount_paid = coalesce((
+           select sum(l.matched_amount)
+             from entry_lines l
+             join accounts a on a.id = l.account_id
+            where l.entry_id = d.entry_id
+              and a.reconcilable
+              and a.account_type in ('asset_receivable', 'liability_payable')
+         ), 0)
+   where d.id = p_document_id
+     and d.entry_id is not null;
+end;
+$$;
+
+comment on function documents_refresh_amount_paid(uuid) is
+  'Recomputes what a document has been settled by, from the matched amounts on its third-party lines.';
+
+comment on column documents.amount_paid is
+  'Derived from reconciliations on the third-party lines of the document''s entry. A value written by hand is replaced at the next matching.';
+
+create or replace function reconciliations_refresh_lines()
+returns trigger
+language plpgsql
+as $$
+declare
+  v_ids uuid[];
+  v_id  uuid;
+  v_doc uuid;
+begin
+  v_ids := array_remove(array[
+    coalesce(new.debit_line_id, old.debit_line_id),
+    coalesce(new.credit_line_id, old.credit_line_id)
+  ], null);
+
+  foreach v_id in array v_ids loop
+    update entry_lines l
+       set matched_amount = coalesce((
+             select sum(r.amount) from reconciliations r
+              where r.debit_line_id = l.id or r.credit_line_id = l.id
+           ), 0),
+           matching_number = (
+             select r.matching_number from reconciliations r
+              where r.debit_line_id = l.id or r.credit_line_id = l.id
+              order by r.created_at
+              limit 1
+           )
+     where l.id = v_id;
+  end loop;
+
+  -- Then the documents those lines belong to, now that the residuals are right.
+  for v_doc in
+    select distinct d.id
+      from entry_lines l
+      join documents d on d.entry_id = l.entry_id
+     where l.id = any (v_ids)
+  loop
+    perform documents_refresh_amount_paid(v_doc);
+  end loop;
+
+  return null;
+end;
+$$;

package/dist/assets/migrations/20260911173000_post_payment.sql

@@ -0,0 +1,122 @@
+-- Ekwo OS — booking a payment.
+--
+-- `post_document` turned an invoice into an entry from the first release;
+-- money moving had no equivalent, so every client had to assemble the two
+-- ledger lines of a payment itself. That is the one thing a client must never
+-- do: the moment a caller writes `entry_lines`, the rules about sides,
+-- accounts and locks live in whichever client happens to be writing them, and
+-- there are as many answers as there are clients. So the rule moves here,
+-- next to the other one.
+--
+-- What it books, and nothing else:
+--
+--   inbound  — money in.  debit the bank, credit the receivable.
+--   outbound — money out. credit the bank, debit the payable.
+--
+-- The third-party account is resolved by role, the same way `post_document`
+-- resolves it: the contact's override first, the company default second,
+-- never by matching a code prefix. The bank side comes from the payment's
+-- bank account, or from the default account of its journal.
+--
+-- What it deliberately does not do: match anything. A payment is money
+-- arriving; which invoices it settles is a separate decision, taken by
+-- `reconcile`, and conflating the two is how a payment ends up silently
+-- allocated to the wrong invoice.
+
+create or replace function post_payment(p_payment_id uuid)
+returns entries
+language plpgsql
+as $$
+declare
+  v_pay        payments%rowtype;
+  v_entry      entries%rowtype;
+  v_money      uuid;
+  v_third      uuid;
+  v_contact    uuid;
+  v_inbound    boolean;
+  v_label      text;
+begin
+  select * into v_pay from payments where id = p_payment_id for update;
+  if not found then
+    raise exception 'unknown_payment: payment % does not exist', p_payment_id;
+  end if;
+  if v_pay.entry_id is not null then
+    raise exception 'payment_already_booked: payment % already points at entry %',
+      p_payment_id, v_pay.entry_id;
+  end if;
+  if v_pay.state = 'cancelled' then
+    raise exception 'payment_cancelled: payment % cannot be booked', p_payment_id;
+  end if;
+
+  v_inbound := v_pay.direction = 'inbound';
+
+  -- The bank side: the account behind the payment's bank account, or the
+  -- default account of the journal it goes through.
+  select b.account_id into v_money
+    from bank_accounts b
+   where b.id = v_pay.bank_account_id;
+
+  if v_money is null then
+    select coalesce(j.default_account_id, b.account_id) into v_money
+      from journals j
+      left join bank_accounts b on b.id = j.bank_account_id
+     where j.id = v_pay.journal_id;
+  end if;
+
+  -- A bank account wired to the journal from its own side counts too: that is
+  -- the direction an operator fills in first.
+  if v_money is null then
+    select b.account_id into v_money
+      from bank_accounts b
+     where b.journal_id = v_pay.journal_id
+       and b.active
+       and b.account_id is not null
+     order by b.created_at
+     limit 1;
+  end if;
+
+  if v_money is null then
+    raise exception 'no_bank_account: set bank_account_id on the payment, or default_account_id on journal %',
+      v_pay.journal_id;
+  end if;
+
+  -- The third-party side, by role.
+  v_contact := commercial_entity(v_pay.contact_id);
+  v_third   := resolve_counterpart_account(v_pay.company_id, v_contact, v_inbound);
+
+  v_label := coalesce(v_pay.reference, v_pay.memo, 'payment');
+
+  insert into entries (company_id, journal_id, fiscal_year_id, entry_date, reference,
+                       description, state, currency_code)
+  values (v_pay.company_id, v_pay.journal_id,
+          fiscal_year_at(v_pay.company_id, v_pay.payment_date), v_pay.payment_date,
+          v_pay.reference, v_label, 'draft', v_pay.currency_code)
+  returning * into v_entry;
+
+  insert into entry_lines (entry_id, company_id, account_id, sequence, name,
+                           debit, credit, currency_code)
+  values (v_entry.id, v_pay.company_id, v_money, 10, v_label,
+          case when v_inbound then v_pay.amount else 0 end,
+          case when v_inbound then 0 else v_pay.amount end,
+          v_pay.currency_code);
+
+  insert into entry_lines (entry_id, company_id, account_id, sequence, name,
+                           debit, credit, contact_id, currency_code)
+  values (v_entry.id, v_pay.company_id, v_third, 20, v_label,
+          case when v_inbound then 0 else v_pay.amount end,
+          case when v_inbound then v_pay.amount else 0 end,
+          v_contact, v_pay.currency_code);
+
+  v_entry := post_entry(v_entry.id);
+
+  update payments
+     set entry_id = v_entry.id,
+         state    = 'posted'
+   where id = p_payment_id;
+
+  return v_entry;
+end;
+$$;
+
+comment on function post_payment(uuid) is
+  'Books a payment: the bank side from the payment''s bank account or its journal, the third-party side by role. Matches nothing.';

package/dist/assets/migrations/20260911173100_sequence_counters_under_rls.sql

@@ -0,0 +1,84 @@
+-- Ekwo OS — the counters have to work for the person doing the booking.
+--
+-- `journal_sequences` and `matching_sequences` carry a select policy and no
+-- other, which is right: nobody should be able to write a counter by hand.
+-- But `next_entry_number()` and `next_matching_number()` write them, and they
+-- ran as the caller — so posting an entry or drawing a matching letter
+-- succeeded for the table owner and failed for every signed-in user with
+-- "new row violates row-level security policy for table journal_sequences".
+--
+-- It went unnoticed because the tests exercised the schema as the owner, the
+-- installer holds an owner connection, and until now nothing else wrote to
+-- this database. The first client that signs in as a user — the MCP server —
+-- hits it on the first invoice.
+--
+-- The counters are infrastructure, not user data: they exist so two
+-- concurrent bookings do not draw the same number. So both functions become
+-- SECURITY DEFINER, and each one checks first that the caller may write the
+-- company it is counting for. A definer function that skipped that check
+-- would be a way to burn numbers in somebody else's journal.
+
+create or replace function next_entry_number(p_journal_id uuid, p_date date)
+returns text
+language plpgsql
+security definer
+set search_path = public, pg_temp
+as $$
+declare
+  v_code    text;
+  v_company uuid;
+  v_year    smallint := extract(year from p_date)::smallint;
+  v_number  integer;
+begin
+  select j.code, j.company_id into v_code, v_company from journals j where j.id = p_journal_id;
+  if v_code is null then
+    raise exception 'unknown_journal: journal % does not exist', p_journal_id;
+  end if;
+
+  -- The caller is about to write an entry in this company; they have to be
+  -- allowed to. auth.uid() is null on an owner connection, where row level
+  -- security is bypassed anyway and the installer is the caller.
+  if auth.uid() is not null and not can_write_company(v_company) then
+    raise exception 'not_allowed: you may not book in this company'
+      using errcode = '42501';
+  end if;
+
+  insert into journal_sequences (journal_id, year, last_number)
+  values (p_journal_id, v_year, 1)
+  on conflict (journal_id, year)
+    do update set last_number = journal_sequences.last_number + 1
+  returning last_number into v_number;
+
+  return v_code || '/' || v_year::text || '/' || lpad(v_number::text, 4, '0');
+end;
+$$;
+
+comment on function next_entry_number(uuid, date) is
+  'Next number for a journal and year, as CODE/YYYY/NNNN. Atomic: the counter row is locked, not the journal. Definer, because the counter is infrastructure and nobody writes it by hand.';
+
+create or replace function next_matching_number(p_company_id uuid)
+returns text
+language plpgsql
+security definer
+set search_path = public, pg_temp
+as $$
+declare
+  v_number integer;
+begin
+  if auth.uid() is not null and not can_write_company(p_company_id) then
+    raise exception 'not_allowed: you may not match in this company'
+      using errcode = '42501';
+  end if;
+
+  insert into matching_sequences (company_id, last_number)
+  values (p_company_id, 1)
+  on conflict (company_id)
+    do update set last_number = matching_sequences.last_number + 1
+  returning last_number into v_number;
+
+  return 'A' || lpad(v_number::text, 4, '0');
+end;
+$$;
+
+comment on function next_matching_number(uuid) is
+  'Next reconciliation letter for a company, as A0001. Definer, for the same reason as next_entry_number.';