ekwo-os 0.4.1

package/dist/assets/migrations/20260913085932_api_keys.sql

@@ -0,0 +1,303 @@
+-- Ekwo OS — a key for a machine, and what it is deliberately not.
+--
+-- Everything in this schema answers to `auth.uid()`, which comes from a JWT
+-- the customer's own GoTrue issued. That is right for a person and impossible
+-- for a script: a nightly import, a till, a bank feed has no browser to sign
+-- in with, and the two usual answers are both wrong. Handing it the
+-- `service_role` key gives it every company of the installation and every
+-- table in it. Creating a fake user for it puts a password in a crontab and
+-- makes the audit trail say a person did it.
+--
+-- So a key is a **third kind of caller**, and it is narrower than both by
+-- construction:
+--
+--   * it belongs to one company and can never reach another;
+--   * it carries an explicit list of capabilities, which the person who
+--     issued it must hold themselves — nobody mints a key stronger than they
+--     are;
+--   * it expires when it is told to, and it is withdrawn by one update;
+--   * it is stored as a sha256 and shown once, like an invitation token.
+--
+-- **How a key authenticates, and why it is this way.** A holder calls
+-- `use_api_key(secret)` at the start of a transaction. That function checks
+-- the hash, refuses a withdrawn or expired key, records the use, and puts the
+-- key's fingerprint in `ekwo.api_key` — transaction-locally, so it is gone
+-- when the transaction ends. `has_capability()` then answers for the key as
+-- well as for the user, and every policy in the schema follows without being
+-- rewritten.
+--
+-- The alternative considered was exchanging a key for a GoTrue session. It
+-- needs GoTrue to know about our keys, which means either a fake user per key
+-- — the thing this is here to avoid — or a service that mints tokens, which
+-- is a second secret to hold. The setting is simpler and its blast radius is
+-- one transaction.
+--
+-- **What it cannot do, stated rather than discovered.** A key is not a
+-- session. `auth.uid()` stays null, so the policies that ask for a signed-in
+-- user rather than for a capability — the reference tables, the company row
+-- itself — stay closed to it. And because PostgREST runs each request in its
+-- own transaction, `use_api_key()` cannot be a separate request over that
+-- route: a key is for a client that holds a connection and opens a
+-- transaction, which is the self-hosted route the MCP server already has.
+--
+-- **The setting cannot be forged into a privilege.** What goes into
+-- `ekwo.api_key` is the hash, not the id, and the hash is only readable by
+-- somebody who already holds `members.manage` on that company — who can
+-- simply issue a key. There is nothing to escalate to.
+
+create table api_keys (
+  id           uuid primary key default gen_random_uuid(),
+  company_id   uuid not null references companies(id) on delete cascade,
+  name         text not null,
+  -- The visible half, so a list of keys can be read by a human and a leaked
+  -- secret can be matched to the row it belongs to.
+  prefix       text not null,
+  key_hash     text not null unique,
+  capabilities text[] not null,
+  created_by   uuid,
+  created_at   timestamptz not null default now(),
+  expires_at   timestamptz,
+  last_used_at timestamptz,
+  revoked_at   timestamptz,
+  constraint api_keys_has_capability check (cardinality(capabilities) > 0),
+  constraint api_keys_expiry check (expires_at is null or expires_at > created_at)
+);
+
+comment on table api_keys is
+  'Machine access to one company. Hashed at rest, scoped to an explicit list of capabilities, and never wider than the person who issued it.';
+comment on column api_keys.prefix is
+  'The readable head of the secret. It identifies a key without being one.';
+comment on column api_keys.capabilities is
+  'Exactly what this key may do. Not a role: a machine has a job, not a job title.';
+comment on column api_keys.created_by is
+  'auth.users.id of whoever issued it. No foreign key, for the same reason company_members has none.';
+
+create index api_keys_company_idx on api_keys (company_id, created_at desc);
+create index api_keys_prefix_idx on api_keys (prefix);
+
+-- ---------------------------------------------------------------------------
+-- Issuing one
+-- ---------------------------------------------------------------------------
+
+create or replace function create_api_key(
+  p_company_id   uuid,
+  p_name         text,
+  p_capabilities jsonb,
+  p_expires_at   timestamptz default null
+)
+returns table (api_key_id uuid, secret text, prefix text, expires_at timestamptz)
+language plpgsql
+security definer
+set search_path = public, pg_temp
+as $$
+declare
+  v_caps   text[] := coalesce(
+    (select array_agg(value) from jsonb_array_elements_text(coalesce(p_capabilities, '[]'::jsonb)) as value),
+    '{}');
+  v_prefix text := left(replace(gen_random_uuid()::text, '-', ''), 12);
+  v_secret text;
+  v_cap    text;
+  v_row    api_keys%rowtype;
+begin
+  if auth.uid() is not null and not has_capability(p_company_id, 'members.manage') then
+    raise exception 'not_allowed: issuing a key for this company needs members.manage'
+      using errcode = '42501';
+  end if;
+
+  if cardinality(v_caps) = 0 then
+    raise exception 'api_key_without_capability: name what this key may do; a key that may do nothing is a secret to look after for no reason';
+  end if;
+
+  foreach v_cap in array v_caps loop
+    if v_cap not in (select code from capabilities) then
+      raise exception 'unknown_capability: % is not a capability of this installation', v_cap;
+    end if;
+    -- Nobody mints a key stronger than they are. An owner issuing a key is
+    -- bounded by their own capabilities, which is also what makes revoking a
+    -- person's capability revoke the keys they left behind.
+    if auth.uid() is not null and not has_capability(p_company_id, v_cap) then
+      raise exception 'not_allowed: you do not hold % yourself, so you cannot put it on a key', v_cap
+        using errcode = '42501';
+    end if;
+  end loop;
+
+  v_secret := 'ekwo_' || v_prefix || '_' ||
+              replace(gen_random_uuid()::text, '-', '') ||
+              replace(gen_random_uuid()::text, '-', '');
+
+  insert into api_keys (company_id, name, prefix, key_hash, capabilities, created_by, expires_at)
+  values (p_company_id, p_name, v_prefix,
+          encode(sha256(convert_to(v_secret, 'UTF8')), 'hex'),
+          v_caps, auth.uid(), p_expires_at)
+  returning * into v_row;
+
+  return query select v_row.id, v_secret, v_row.prefix, v_row.expires_at;
+end;
+$$;
+
+comment on function create_api_key(uuid, text, jsonb, timestamptz) is
+  'Issues a machine key on one company and returns the secret once. Only the hash is stored, and no capability can be put on a key that the person issuing it does not hold.';
+
+-- ---------------------------------------------------------------------------
+-- Recording that a key was used
+--
+-- Its own function because it is its own act: `use_api_key()` calls it, and a
+-- caller that wants to record a use it made through another path can too.
+-- Definer and unconditional — a key that is in use records it whether or not
+-- the call it is about to make succeeds.
+-- ---------------------------------------------------------------------------
+
+create or replace function touch_api_key(p_api_key_id uuid)
+returns void
+language sql
+security definer
+set search_path = public, pg_temp
+as $$
+  update api_keys set last_used_at = now() where id = p_api_key_id;
+$$;
+
+comment on function touch_api_key(uuid) is
+  'Records that a key was used just now. A key that has never been used, and one that has not been used for a year, are both things an operator should be able to see.';
+
+-- ---------------------------------------------------------------------------
+-- Presenting one
+-- ---------------------------------------------------------------------------
+
+create or replace function use_api_key(p_secret text)
+returns api_keys
+language plpgsql
+security definer
+set search_path = public, pg_temp
+as $$
+declare
+  v_row api_keys%rowtype;
+begin
+  select * into v_row
+    from api_keys
+   where key_hash = encode(sha256(convert_to(coalesce(p_secret, ''), 'UTF8')), 'hex');
+
+  if v_row.id is null then
+    raise exception 'unknown_api_key: that is not a key of this installation'
+      using errcode = '42501';
+  end if;
+  if v_row.revoked_at is not null then
+    raise exception 'api_key_revoked: that key was withdrawn on %', v_row.revoked_at
+      using errcode = '42501';
+  end if;
+  if v_row.expires_at is not null and v_row.expires_at <= now() then
+    raise exception 'api_key_expired: that key expired on %', v_row.expires_at
+      using errcode = '42501';
+  end if;
+
+  -- Transaction-local: the key is presented for the work at hand and not for
+  -- the life of a connection somebody else may inherit from a pool.
+  perform set_config('ekwo.api_key', v_row.key_hash, true);
+  perform touch_api_key(v_row.id);
+
+  return v_row;
+end;
+$$;
+
+comment on function use_api_key(text) is
+  'Presents a machine key for the current transaction: has_capability() answers for it until the transaction ends. Refuses a key that is unknown, withdrawn or expired.';
+
+create or replace function current_api_key()
+returns api_keys
+language sql
+stable
+security definer
+set search_path = public, pg_temp
+as $$
+  select k.* from api_keys k
+   where k.key_hash = nullif(current_setting('ekwo.api_key', true), '')
+     and k.revoked_at is null
+     and (k.expires_at is null or k.expires_at > now());
+$$;
+
+comment on function current_api_key() is
+  'The key presented in this transaction, or nothing. What a client reads back to know what it may do.';
+
+create or replace function revoke_api_key(p_api_key_id uuid)
+returns api_keys
+language plpgsql
+security definer
+set search_path = public, pg_temp
+as $$
+declare
+  v_row api_keys%rowtype;
+begin
+  select * into v_row from api_keys where id = p_api_key_id;
+  if v_row.id is null then
+    raise exception 'unknown_api_key: no key with that id';
+  end if;
+  if auth.uid() is not null and not has_capability(v_row.company_id, 'members.manage') then
+    raise exception 'not_allowed: withdrawing a key needs members.manage'
+      using errcode = '42501';
+  end if;
+
+  update api_keys set revoked_at = coalesce(revoked_at, now())
+   where id = p_api_key_id
+  returning * into v_row;
+
+  return v_row;
+end;
+$$;
+
+comment on function revoke_api_key(uuid) is
+  'Withdraws a key. There is no un-withdraw: a secret that has been out of the building is issued again, not brought back.';
+
+-- ---------------------------------------------------------------------------
+-- has_capability, which now answers for a key as well as for a user
+--
+-- The member answer first, because that is the common case and it is the one
+-- a policy on a table of a company is written for. A key is consulted only
+-- when there is no member answer, so presenting a key can never take away
+-- what the signed-in person already had.
+-- ---------------------------------------------------------------------------
+
+create or replace function has_capability(p_company_id uuid, p_capability text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = public, pg_temp
+as $$
+  select coalesce(
+    (select case
+              when p_capability = any (m.capabilities_revoked) then false
+              when p_capability = any (m.capabilities_granted) then true
+              else exists (
+                select 1 from role_capabilities rc
+                 where rc.role = m.role and rc.capability = p_capability
+              )
+            end
+       from company_members m
+      where m.company_id = p_company_id
+        and m.user_id = auth.uid()),
+    (select p_capability = any (k.capabilities)
+       from api_keys k
+      where k.key_hash = nullif(current_setting('ekwo.api_key', true), '')
+        and k.company_id = p_company_id
+        and k.revoked_at is null
+        and (k.expires_at is null or k.expires_at > now())),
+    false);
+$$;
+
+comment on function has_capability(uuid, text) is
+  'Whether the current caller may do one named thing in one company — a signed-in member by their preset and their adjustments, or a machine key by its own list. Revoked beats granted, and a non-member holding no key holds nothing.';
+
+-- ---------------------------------------------------------------------------
+-- Row level security
+--
+-- Reading the keys of a company is administering its members, and nothing
+-- writes the table through the API: the four functions above are the way in.
+-- ---------------------------------------------------------------------------
+
+alter table api_keys enable row level security;
+
+create policy api_keys_select on api_keys
+  for select using (
+    has_capability(company_id, 'members.manage') or is_instance_admin()
+  );
+
+revoke execute on all functions in schema public from public;

package/dist/assets/migrations/20260913090216_fiscal_year_bounds.sql

@@ -0,0 +1,159 @@
+-- Ekwo OS — the first financial year is a parameter too.
+--
+-- `ekwo init` opened the first year on 1 January and closed it on 31
+-- December, in two string literals. That is right for Belgium and for France
+-- and wrong for the United Kingdom, for India, for Australia and for every
+-- company whose year does not follow the calendar — and the country model has
+-- carried the answer since P0-7: `country_defaults.fiscal_year_default`, one
+-- of `calendar`, `april`, `july` or `october`, with no default of its own.
+--
+-- This is its reader. It is in the schema rather than in the CLI because
+-- three callers ask the same question — `ekwo init`, the MCP server creating
+-- a company, and whoever adds the year after that — and three answers to it
+-- is how a company ends up with two overlapping first years.
+--
+-- **A day, not a duration.** The bounds are the opening day and the day
+-- before the same day next year, so a year opened on 1 April closes on 31
+-- March, and a leap day changes nothing. The 52/53-week year some retailers
+-- keep is not this function's business: `fiscal_years` takes any two dates,
+-- and a company that keeps one names them.
+--
+-- **No fallback.** A pack that says nothing gets `no_fiscal_year_default`,
+-- naming the field it has to fill and the flag that answers for it. Opening
+-- somebody's first year on a date nobody chose is the kind of wrong that is
+-- found a year later, in a closing.
+
+create or replace function fiscal_year_bounds(
+  p_country    char(2),
+  p_year       integer,
+  p_start      date default null,
+  out start_date date,
+  out end_date   date
+)
+language plpgsql
+stable
+as $$
+declare
+  v_opening text;
+  v_month   integer;
+begin
+  if p_start is not null then
+    start_date := p_start;
+  else
+    select fiscal_year_default into v_opening
+      from country_defaults where country = p_country;
+
+    if v_opening is null then
+      raise exception 'no_fiscal_year_default: the % pack declares no defaults.fiscal_year_default, so there is no month to open the first year on. Name the first day instead', p_country;
+    end if;
+
+    v_month := case v_opening
+                 when 'calendar' then 1
+                 when 'april'    then 4
+                 when 'july'     then 7
+                 when 'october'  then 10
+               end;
+    if v_month is null then
+      raise exception 'unknown_fiscal_year_default: % is not one of calendar, april, july, october', v_opening;
+    end if;
+
+    start_date := make_date(p_year, v_month, 1);
+  end if;
+
+  end_date := (start_date + interval '1 year' - interval '1 day')::date;
+end;
+$$;
+
+comment on function fiscal_year_bounds(char, integer, date) is
+  'The first and last day of a financial year opening in a given calendar year, on the month the country pack declares — or on a day the caller names. Raises rather than assuming January.';
+
+-- ---------------------------------------------------------------------------
+-- create_company — a company, its owner, its chart and its first year
+--
+-- The four statements a client had to get right in the right order, with the
+-- two that carry a rule delegated rather than restated:
+-- `install_country_template()` copies the chart, the journals and the taxes,
+-- and `fiscal_year_bounds()` decides the two dates. What is left here is the
+-- sequence.
+--
+-- `ekwo init` keeps its own sequence, and deliberately: the installer is
+-- check-then-act — it reports "already there" for every step and can be run
+-- twice on a half-finished project — where this function creates or raises.
+-- What they share is every rule; what differs is what they do when the thing
+-- already exists.
+--
+-- Creating a company is an instance-level act, which is the policy on
+-- `companies` and the doctrine behind it: an administrator creates companies
+-- and invites members, and is not thereby on anybody's books. So the creator
+-- is made the first member here, explicitly, because being able to create a
+-- company is not being able to read one.
+-- ---------------------------------------------------------------------------
+
+create or replace function create_company(
+  p_name              text,
+  p_country           char(2),
+  p_currency_code     char(3) default null,
+  p_language          char(2) default null,
+  p_chart_code        text    default null,
+  p_fiscal_year       integer default null,
+  p_fiscal_year_start date    default null,
+  p_owner_user_id     uuid    default null
+)
+returns companies
+language plpgsql
+as $$
+declare
+  v_defaults country_defaults%rowtype;
+  v_currency char(3);
+  v_language char(2);
+  v_owner    uuid := coalesce(p_owner_user_id, auth.uid());
+  v_year     integer := coalesce(p_fiscal_year, extract(year from coalesce(p_fiscal_year_start, current_date))::integer);
+  v_bounds   record;
+  v_company  companies%rowtype;
+begin
+  if auth.uid() is not null and not is_instance_admin() then
+    raise exception 'not_instance_admin: creating a company is an instance-level act'
+      using errcode = '42501';
+  end if;
+
+  select * into v_defaults from country_defaults where country = p_country;
+
+  -- The currency and the language have to be settled before the insert: both
+  -- columns are not null with a default, so there is no later moment at which
+  -- they are empty and the pack could fill them. The pack answers, or the
+  -- caller does, and there is no third answer written here.
+  v_currency := upper(coalesce(p_currency_code, v_defaults.currency_code));
+  if v_currency is null then
+    raise exception 'no_currency: the % pack names no currency; name one', p_country;
+  end if;
+  v_language := lower(coalesce(p_language, v_defaults.language_default));
+  if v_language is null then
+    raise exception 'no_language: the % pack names no language for its labels; name one', p_country;
+  end if;
+
+  select * into v_bounds from fiscal_year_bounds(p_country, v_year, p_fiscal_year_start);
+
+  insert into companies (name, country, fiscal_country, currency_code, language)
+  values (p_name, p_country, p_country, v_currency, v_language)
+  returning * into v_company;
+
+  if v_owner is not null then
+    insert into company_members (company_id, user_id, role)
+    values (v_company.id, v_owner, 'owner')
+    on conflict (company_id, user_id) do nothing;
+  end if;
+
+  perform install_country_template(v_company.id, p_country, v_language, p_chart_code);
+
+  insert into fiscal_years (company_id, name, start_date, end_date)
+  values (v_company.id, 'FY' || v_year::text, v_bounds.start_date, v_bounds.end_date);
+
+  select * into v_company from companies where id = v_company.id;
+  return v_company;
+end;
+$$;
+
+comment on function create_company(text, char, char, char, text, integer, date, uuid) is
+  'Creates a company, makes the caller its first member, copies the country pack into it and opens its first financial year on the month that pack declares. An instance-level act, like the policy on companies.';
+
+revoke execute on all functions in schema public from public;

package/dist/assets/migrations/20260913092527_entries_import.sql

@@ -0,0 +1,219 @@
+-- Ekwo OS — taking over books that already have numbers.
+--
+-- ST13 gave `country_defaults.numbering_gapless` a reader: `post_entry()`
+-- refuses a number chosen by hand where the law forbids a hole in the
+-- sequence, because a number that skips the counter is exactly how a hole
+-- appears. That entry also wrote down what it would cost — "the day an import
+-- of somebody's old entries under their old numbers is written, this is the
+-- rule it will have to argue with" — and the argument arrived immediately: a
+-- company moving from another system arrives with three years of entries that
+-- already carry numbers, and those numbers are the ones its VAT returns, its
+-- filings and its auditor already know.
+--
+-- So the rule stands and gains an exception that has a name.
+--
+-- **`entries.import` is a capability, and it is in no preset.** Not a flag on
+-- the call, not a session setting, not an argument somebody can pass by
+-- accident: the one thing that lets an explicit number through is a
+-- capability an owner has to grant, on purpose, to the person doing the
+-- import — and take back afterwards. It is in `capabilities` so it can be
+-- granted and revoked like every other, and out of `role_capabilities` so
+-- that no role carries it by default. Importing is not something an
+-- accountant does on a Tuesday.
+--
+-- **What it does not relax.** A duplicate is still refused, by the unique
+-- index `entries_company_number_idx` that has been there since the first
+-- release — `(company_id, number)`, which is stricter than per journal and
+-- was already the right key. And an explicit number on a normal entry, from
+-- somebody without the capability, is refused exactly as it was yesterday.
+--
+-- **It applies to everybody, including the installer.** A gapless sequence is
+-- a rule about the books and not a permission, so this guard does not carry
+-- the `auth.uid() is null` exemption the permission checks do: a superuser
+-- connection is refused like anybody else. An importer running over such a
+-- connection sets the request claim for the user it is acting for — which is
+-- what `ekwo demo` already does to satisfy `claim_instance_admin()` — and
+-- that user holds `entries.import`.
+--
+-- **The counter catches up.** An imported number that is written in the
+-- country's own pattern advances `journal_sequences` to it, so the first
+-- entry booked after the import continues the series instead of restarting
+-- at one and colliding. A number that does not parse against the pattern —
+-- a series from another system, in another shape — leaves the counter alone,
+-- because there is nothing in it the counter could learn.
+
+insert into capabilities (code, area, description) values
+  ('entries.import', 'entries',
+   'Post an entry under a number chosen by hand, where the country forbids a hole in the sequence. For taking over books that already have numbers. In no preset: it is granted for an import and taken back after it.');
+
+-- ---------------------------------------------------------------------------
+-- Reading a counter back out of a number
+--
+-- The pattern is the pack's, so the way to read a number is the pattern read
+-- backwards: the literal text of the format is literal, `{CODE}`, `{YYYY}`,
+-- `{YY}` and `{MM}` are what they are, and the `{N…}` token is the number we
+-- are after. Anything that does not match returns null, which is an answer.
+-- ---------------------------------------------------------------------------
+
+create or replace function number_counter(p_format text, p_number text)
+returns integer
+language plpgsql
+immutable
+as $$
+declare
+  v_pattern text;
+  v_found   text;
+begin
+  if p_format is null or p_number is null then
+    return null;
+  end if;
+
+  -- Everything that is not a token becomes literal; the tokens become what
+  -- they can match. `regexp_replace` with the `g` flag walks the format once.
+  v_pattern := regexp_replace(p_format, '([.^$*+?()\[\]{}|\\])', '\\\1', 'g');
+  -- The escaping above also escaped the braces of the tokens, so the tokens
+  -- are matched in their escaped shape.
+  v_pattern := replace(v_pattern, '\{CODE\}', '.+');
+  v_pattern := replace(v_pattern, '\{YYYY\}', '[0-9]{4}');
+  v_pattern := replace(v_pattern, '\{YY\}',   '[0-9]{2}');
+  v_pattern := replace(v_pattern, '\{MM\}',   '[0-9]{2}');
+  v_pattern := regexp_replace(v_pattern, '\\\{N+\\\}', '([0-9]+)');
+
+  if v_pattern !~ '\(\[0-9\]\+\)' then
+    return null;
+  end if;
+
+  v_found := (regexp_match(p_number, '^' || v_pattern || '$'))[1];
+  if v_found is null then
+    return null;
+  end if;
+  return v_found::integer;
+exception
+  when others then
+    return null;
+end;
+$$;
+
+comment on function number_counter(text, text) is
+  'The counter inside a number, read back through the pattern it was written with, or null when the number does not follow that pattern. What lets an import advance the sequence it interrupted.';
+
+-- ---------------------------------------------------------------------------
+-- Catching the counter up
+--
+-- Definer for the reason the counters are definer: `journal_sequences` has a
+-- select policy and no other, and nobody writes it by hand. The caller has
+-- already been checked by `post_entry()`.
+-- ---------------------------------------------------------------------------
+
+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;
+
+  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 a journal counter to an imported number, so the next automatic one continues the series rather than colliding with it. Does nothing for a number that does not follow the country''s pattern.';
+
+-- ---------------------------------------------------------------------------
+-- post_entry, with the exception that has a name
+--
+-- Unchanged but for the guard and the catching-up: everything else is the
+-- function as published.
+-- ---------------------------------------------------------------------------
+
+create or replace function post_entry(p_entry_id uuid)
+returns entries
+language plpgsql
+as $$
+declare
+  v_entry   entries%rowtype;
+  v_lines   integer;
+  v_gapless boolean;
+begin
+  select * into v_entry from entries where id = p_entry_id for update;
+  if not found then
+    raise exception 'unknown_entry: entry % does not exist', p_entry_id;
+  end if;
+  if v_entry.state = 'posted' then
+    return v_entry;
+  end if;
+  if v_entry.state = 'cancelled' then
+    raise exception 'entry_cancelled: entry % cannot be posted', p_entry_id;
+  end if;
+
+  select count(*) into v_lines from entry_lines where entry_id = p_entry_id;
+  if v_lines = 0 then
+    raise exception 'entry_empty: entry % has no lines', p_entry_id;
+  end if;
+
+  -- Re-read the totals maintained by the line trigger.
+  select * into v_entry from entries where id = p_entry_id;
+  if v_entry.total_debit <> v_entry.total_credit then
+    raise exception 'entry_unbalanced: entry % has debit % and credit %',
+      p_entry_id, v_entry.total_debit, v_entry.total_credit;
+  end if;
+
+  -- Where the law forbids a hole, the number comes from the counter and from
+  -- nowhere else — unless the caller holds `entries.import`, which is how a
+  -- set of books that already has numbers is taken over. A duplicate is
+  -- refused either way, by `entries_company_number_idx`.
+  if v_entry.number is not null then
+    select numbering_gapless into v_gapless from numbering_rules(v_entry.company_id);
+    if v_gapless and not (auth.uid() is not null
+                          and has_capability(v_entry.company_id, 'entries.import')) then
+      raise exception 'numbering_gapless: this country forbids a hole in the sequence, so entry % may not be posted under a number chosen by hand. Leave entries.number empty and the journal counter draws it, or hold entries.import to bring in books that already have numbers',
+        p_entry_id;
+    end if;
+  end if;
+
+  perform assert_period_open(v_entry.company_id, v_entry.entry_date, true);
+
+  update entries
+     set number = coalesce(number, next_entry_number(journal_id, entry_date)),
+         fiscal_year_id = coalesce(fiscal_year_id, fiscal_year_at(company_id, entry_date)),
+         state = 'posted',
+         posted_at = now()
+   where id = p_entry_id
+  returning * into v_entry;
+
+  -- An imported number advances the counter it interrupted, so the next
+  -- automatic one continues the series. A number drawn from the counter is
+  -- already at it and this is a no-op.
+  perform catch_up_journal_sequence(v_entry.journal_id, v_entry.entry_date, v_entry.number);
+
+  return v_entry;
+end;
+$$;
+
+comment on function post_entry(uuid) is
+  'Validates, numbers and posts an entry. Raises rather than warning: a swallowed error is a missing entry. Where the country forbids a hole in the sequence it refuses a number chosen by hand, unless the caller holds entries.import — and then the counter catches up to it.';
+
+revoke execute on all functions in schema public from public;