ekwo-os 0.6.0 → 0.7.0

package/README.md

@@ -6,13 +6,17 @@ books: the schema, the chart of accounts, the VAT codes, the first
 administrator, the first company and its first financial year.
 
 ```sh
-npx ekwo-os init
+npx -y ekwo-os@latest init
 ```
 
-The package is `ekwo-os` and the command it installs is `ekwo`: `npx ekwo-os
-<command>` runs it without installing anything, and after
-`npm install -g ekwo-os` every example below that starts with `ekwo ` works as
-written.
+The package is `ekwo-os` and the command it installs is `ekwo`:
+`npx -y ekwo-os@latest <command>` runs it without installing anything, and
+after `npm install -g ekwo-os` every example below that starts with `ekwo `
+works as written. Keep the version in the command: run from inside a clone of
+the Ekwo repository, a bare `npx ekwo-os` finds the workspace package of the
+same name, which links no command, and answers `ekwo: command not found`. With
+`@latest`, `npx` fetches the published CLI wherever it is started; the clone's
+own is `node packages/cli/dist/bin.js`, after `npm run build`.
 
 You need Node 20 or later. That is the whole list. The Supabase CLI is not
 required — this talks to Postgres directly — and Docker is not required
@@ -26,9 +30,11 @@ either.
 2. **Copy two things** from the dashboard:
    - Project Settings → Database → **Connection string** (URI). It contains
      your database password.
-   - Project Settings → API → **`service_role` key**, and the **Project URL**.
-     These are used once, to create the first administrator in your own
-     Supabase Auth, and are never written to disk.
+   - Project Settings → API Keys → the **secret key** (`sb_secret_…`), and the
+     **Project URL**. A project created before the new keys has the legacy
+     **`service_role` key** instead, and it works the same. These are used
+     once, to create the first administrator in your own Supabase Auth, and
+     are never written to disk.
 
    **Take the pooler string, not the direct one, unless you know you have
    IPv6.** The direct host `db.<ref>.supabase.co` resolves to an IPv6 address
@@ -48,7 +54,7 @@ either.
 3. **Run the installer.**
 
    ```sh
-   npx ekwo-os init
+   npx -y ekwo-os@latest init
    ```
 
    It asks for the connection string, the country, the chart of accounts and
@@ -71,7 +77,7 @@ either.
 Everything above in one non-interactive line:
 
 ```sh
-npx ekwo-os init \
+npx -y ekwo-os@latest init \
   --db-url "postgresql://postgres.YOURREF:PASSWORD@aws-1-eu-west-3.pooler.supabase.com:5432/postgres" \
   --supabase-url "https://YOURREF.supabase.co" \
   --service-role-key "$SUPABASE_SERVICE_ROLE_KEY" \
@@ -117,6 +123,52 @@ in `defaults.fiscal_year_default`; one that names none — the United Kingdom's,
 where a company's year ends on the accounting reference date it chose — asks
 for the day.
 
+`ekwo company new` asks the same questions about every other company, and
+refuses the same way.
+
+## Several countries in one installation: `init --no-company`
+
+An installation is not in a country; its companies are. `ekwo init` loads every
+pack of the release whatever `--country` says, so one installation keeps the
+books of companies in as many countries as it holds packs. When there is no
+"first company" to name — a group, a firm, a holding with subsidiaries abroad —
+install without one, then create each company in its own country:
+
+```sh
+npx -y ekwo-os@latest init --no-company \
+  --db-url "$EKWO_DB_URL" --supabase-url "https://YOURREF.supabase.co" \
+  --service-role-key "$SUPABASE_SERVICE_ROLE_KEY" \
+  --org "My Group" --admin-email "you@example.com" --yes
+
+ekwo company new "My Company Belgium" --country BE --chart default --language nl --yes
+ekwo company new "My Company France"  --country FR --language fr --yes
+ekwo company list
+```
+
+`--no-company` runs the migrations, the seeds of every pack, the modules, the
+first administrator, `init_instance()` and `claim_instance_admin()`, and
+nothing else. The instance row records no country. A flag that only describes
+a company — `--country`, `--company`, `--chart`, `--language`, `--currency`,
+`--fiscal-year`, `--fiscal-year-start`, `--vat-period`, `--filing-period`,
+`--iban`, `--bic`, `--bank-name` — is refused with it, exit code 2, before the
+database is touched: it would describe nothing.
+
+**`ekwo company new` is `create_company()`**, the function the `create_company`
+tool of the MCP server calls: the country pack copied in, the first financial
+year opened, the administrator its first owner. It is called as an
+administrator of the installation — `--as-user`, or the only one when there is
+exactly one — so the database judges that person exactly as it judges the tool:
+anybody else is refused, `not_instance_admin`, exit code 3. Before the call,
+the CLI asks what `ekwo init` asks about its first company, from the packs the
+installation holds, and refuses the same way off a terminal: no country without
+`--country`, and `--chart`, `--language` and `--fiscal-year-start` wherever the
+pack offers a choice. `--currency` and `--fiscal-year` override the pack and
+this year.
+
+Without `--no-company`, `ekwo init` does what it always did, and the installation
+takes more companies later the same way. Neither writes a country into
+`ekwo.json`: see below.
+
 ## Where table access comes from
 
 **The schema grants its own rights.** Every table, view and function of Ekwo
@@ -222,7 +274,7 @@ and read by a person.
 | 2 | Applies every reference seed of `supabase/seed/`, in file-name order: `00_currencies.sql`, `00_territories.sql`, `05_framework_generic.sql`, then one `<n>_pack_<cc>.sql` per country pack, in the order of the number each pack declares | The currencies, the territories the tax rules name, the country-less financial statements every chart falls back on, and every country pack of the release — so a company in any of them can be created later without installing anything. They are exactly the seeds `supabase/config.toml` lists (a list `ekwo pack build` writes from `packs/`), so `supabase db push` installs the same set; a test compares both paths row by row. `90_demo_company.sql` is sample data and is never applied here |
 | 3 | Creates the first administrator through the Supabase Auth admin API | See below: a database connection cannot be a signed-in user |
 | 4 | `init_instance()`, `claim_instance_admin()`, the company, `company_members` as owner, `install_country_template()`, the first financial year, and the bank account when an IBAN was given | The six steps of the root README, in the same order, plus the one thing nobody can derive |
-| 5 | Writes `ekwo.json` | Project URL, country, schema version. Nothing else, ever |
+| 5 | Writes `ekwo.json` | The installation: project URL and schema version. Nothing else, ever — no country, since each company carries its own. A file written by 0.6 or earlier also names a country; it is still read, and the key is taken for nothing |
 | 6 | Asks whether to register with Ekwo | The default answer is no, and no is a supported answer forever |
 
 Every step checks before it acts. Running `ekwo init` twice on the same
@@ -250,7 +302,7 @@ instead if the account already exists, and no key is needed.
 
 | Command | What it does |
 |---|---|
-| `ekwo init` | The whole installation, interactive or not: the socle's migrations, the reference seeds, then the modules', as `ekwo migrate` applies them. |
+| `ekwo init` | The whole installation, interactive or not: the socle's migrations, the reference seeds, then the modules', as `ekwo migrate` applies them. `--no-company` stops before the first company: see [several countries](#several-countries-in-one-installation-init---no-company). |
 | `ekwo migrate` | Applies the migrations this release adds, after showing the gap — the socle's, then the modules'. Re-applies the reference seeds, which are idempotent. `--no-modules` leaves the modules alone. |
 | `ekwo status` | Schema version installed against available, pending migrations, the instance, its administrators, the country packs it holds and, per company, the pack version it copied. Exits 1 when something is pending. |
 | `ekwo doctor` | Every object this release defines and every privilege it grants, against what the database holds; row level security on every table, a policy on every protected table, no pending migration, no membership pointing at a deleted user, every company with a bank account, statements that tie to their lines, posted entries that balance. Exits 1 on a problem, 0 on warnings. |
@@ -258,7 +310,7 @@ instead if the account already exists, and no key is needed.
 | `ekwo unregister` | Opt back out. Clears the address and the date on the instance row. |
 | `ekwo demo` | Loads the sample company. Fictional data, explicit request only. |
 | `ekwo module` | What is installed beside the socle, applies a module's migrations and its country seeds, and turns one on or off for a company. |
-| `ekwo company` | One company leaves an installation with its books — `export` writes an archive anybody can read, as a member under row level security — and arrives in another one alive: `import` takes it in whole or not at all. |
+| `ekwo company` | `new` creates a company in its own country, through `create_company()`, and `list` shows the companies held here. One company leaves an installation with its books — `export` writes an archive anybody can read, as a member under row level security — and arrives in another one alive: `import` takes it in whole or not at all. |
 | `ekwo pack` | Compiles a country pack into its seed, and refuses a seed that is no longer the output of its pack. Runs in a checkout of the repository only. |
 | `ekwo login` | Signs in to an instance as yourself and keeps the session, in your own configuration directory. See [acting as a person](#acting-as-a-person-login-use-whoami). |
 | `ekwo logout` | Ends that session, here and on the instance. |
@@ -515,7 +567,7 @@ source, and nothing is posted while an account has no answer:
 ```bash
 ekwo import fec 123456789FEC20251231.txt --dry-run --open-years --save-mapping map.json
 #   read, propose a correspondence, rehearse the import in the database, take it back
-$EDITOR map.json                                   # answer what is null, correct what is wrong
+$EDITOR map.json                                   # answer what is null — read `suggested` — correct what is wrong
 ekwo import fec 123456789FEC20251231.txt --mapping map.json --open-years
 ekwo import trial-balance balance.csv --opening-date 2026-01-01 --dry-run --save-mapping map.json
 ekwo import journal-items items.csv accounts.csv partners.csv --dry-run --save-mapping map.json
@@ -540,23 +592,33 @@ official page and state.
 
 **The correspondence is yours.** Every account of the old chart has to become
 an account of the company's chart, and every old journal a journal of the
-company. The core proposes, from the codes alone — the same code, the same
-digits without the zeros a chart pads with (`411` and `411000`), or the
-account whose digits are the longest beginning of the old code, three at least
-(`401ACME` → `401000`); a tie is no answer — and each proposal says which rule
-found it. `--save-mapping` writes it as JSON:
+company. The codes give a candidate — the same code, the same digits without
+the zeros a chart pads with (`411` and `411000`), or the account whose digits
+are the longest beginning of the old code, three at least (`401ACME` and
+`401000`); a tie is no answer — and what the files say of the old account —
+the type its export gives it, its name, the side of its balance — is held
+against the type of the candidate in the chart, because two charts give the
+same digits to different things. Only the same code, not contradicted, is
+`exact`. Anything else is `suggested`, with its reason, and waits for you; a
+candidate the files contradict is dropped for the one account of the chart of
+the kind they say. `--dry-run` prints the lines to read first, each with its
+reason, and `--save-mapping` writes the correspondence as JSON:
 
 ```json
 {
   "version": 1,
   "source": "fec",
-  "accounts": { "411000": "411000", "401ACME": "401000", "471200": null },
-  "journals": { "VE": "SAL", "AN": "@opening", "BQ1": "MISC" }
+  "accounts": { "411000": "411000", "401ACME": null, "471200": null },
+  "journals": { "VE": "SAL", "AN": "@opening", "BQ1": "MISC" },
+  "suggested": { "401ACME": { "target": "401000", "reason": "the longest beginning of the code the chart has; …" } }
 }
 ```
 
 and `--mapping` gives it back: what it answers wins over the proposal, so the
-second run posts what the first one showed. A journal mapped to `@opening`
+second run posts what the first one showed. A suggestion is confirmed by
+writing its code under `accounts`; `--accept-suggestions` takes all of them
+once you have read them. Nothing is posted while one the books use is only
+suggested. A journal mapped to `@opening`
 becomes the opening entry of its year instead of ordinary entries — the
 *à-nouveaux* of a FEC, typically. A journal whose code is the one the pack
 opens years on is proposed as `@opening` on its own; `*` stands for entries
@@ -580,7 +642,7 @@ dry run reads the file and asks nothing: a statement books nothing anyway.
 What else to know:
 
 - **Refused before the database is asked**, and listed under `refusals` by a
-  dry run: an account or a journal with no answer, books whose reader found
+  dry run: an account or a journal with no answer or only a suggestion, books whose reader found
   something that does not add up (an entry that does not balance, a line of a
   draft entry), a currency the files name that is not the company's.
 - **The numbers** are drawn by the journal each entry goes to; the old number
@@ -592,7 +654,8 @@ What else to know:
   statements, and no box of a VAT return. A period kept elsewhere was declared
   from where it was kept.
 - **The same files twice are refused** (`import_already_done`): `book_imports`
-  keeps the checksum of what each import read.
+  keeps the checksum of what each import read, and the refusal says which
+  files, when, and what that import wrote.
 - **Dates and encodings are said, never guessed**: `--encoding` for a file
   that is not UTF-8, `--date-order` for a report that writes dates in digits.
 - **Reconciliation marks are read and not re-applied yet**: the matching of an
@@ -631,9 +694,23 @@ them as history it has no file for.
 
 ## `ekwo company`
 
-A firm keeps several companies in one installation, and each of them belongs to
-somebody. These two commands are how one of them leaves, and arrives somewhere
-else.
+A firm keeps several companies in one installation, each in its own country,
+and each of them belongs to somebody. `new` creates one and `list` shows them —
+see [several countries](#several-countries-in-one-installation-init---no-company):
+
+```sh
+ekwo company new "My Company Belgium" --country BE --chart default --language fr
+ekwo company new "My Company France" --country FR --language fr
+ekwo company list                                     # name, country, currency, language, chart, pack, members
+```
+
+`company new --json` answers the company (`id`, `country`, `currency`,
+`language`, `chart`, `packVersion`), its first financial year and its owner;
+`company list --json` answers `companies`, one per company. Both shapes are
+under `$defs/data` of the output schema, and the exit codes are the ones every
+command has: 2 for a missing answer, 3 when the database refuses.
+
+The two commands below are how a company leaves, and arrives somewhere else.
 
 ```sh
 ekwo company export "My Company" --out ./my-company   # manifest.json + data/<schema>.<table>.jsonl
@@ -810,7 +887,7 @@ Every command takes the connection flags:
 | `--db-password <pw>` | Database password. Prompted, masked, when omitted. |
 | `--db-region <region>` | With `--project-ref`, the session pooler in that region. Both generation prefixes are tried and the one that answers is kept. |
 | `--supabase-url <url>` | `https://<ref>.supabase.co`. Needed only to create a user. |
-| `--service-role-key <key>` | Needed only to create a user. |
+| `--service-role-key <key>` | Needed only to create a user. Either form Supabase issues: a secret key, `sb_secret_…`, sent on the `apikey` header alone because it is not a JWT, or the legacy `service_role` JWT, sent on `apikey` and as a Bearer as before. |
 | `--yes`, `-y` | Never ask a question. Everything must come from flags or the environment. |
 
 `--project-ref` with `--db-password` and `--db-region` builds the session
@@ -845,6 +922,12 @@ dashboard under Connect → Session pooler, is the form that is never derived.
 | `--register` | Register without being asked. `--register-email` sets the address. |
 | `--registry-url <url>` | Where the registration is announced. |
 | `--no-modules` | Leave the modules out. By default `init` installs them, as `ekwo migrate` does — empty schemas until a company enables one. |
+| `--no-company` | Install without a company: schema, every pack, the modules, the first administrator, and no country on the instance row. The flags that only describe a company are refused with it. Then `ekwo company new`, once per company. |
+
+`ekwo company new <name>` takes `--country`, `--chart`, `--language`,
+`--currency`, `--fiscal-year` and `--fiscal-year-start` as `init` does, and
+`--as-user <uuid>`: the administrator of the installation it is created as,
+who becomes its owner — the only one, when there is exactly one.
 
 Every command takes `--json`; see [what a command answers](#what-a-command-answers---json-and-the-exit-codes).
 `ekwo migrate` takes `--skip-seeds`.

package/dist/assets/expected-objects.json

@@ -1,6 +1,6 @@
 {
-  "schemaVersion": "0.6.0",
-  "migration": "20260922091348",
+  "schemaVersion": "0.7.0",
+  "migration": "20260922124012",
   "socle": {
     "schema": "public",
     "tables": [

package/dist/assets/migrations/20260922115309_an_installation_without_a_country.sql

@@ -0,0 +1,24 @@
+-- Ekwo OS — an installation is not in a country; its companies are.
+--
+-- `instance.country` was `not null` because the installation used to be set up
+-- *for* one country: `ekwo init` created the first company in the same run and
+-- wrote its country on the instance row. It never meant more than that. The
+-- seeds of every pack are loaded whatever it says, `create_company()` takes a
+-- country per company, and nothing in the schema reads the column — a firm
+-- keeping the books of companies in two countries has had one installation
+-- for both since the first release.
+--
+-- `ekwo init --no-company` installs the schema, the packs and the first
+-- administrator and creates no company, so there is no country to write down,
+-- and inventing one would be a default nobody chose. The column becomes
+-- nullable. The format check stays: a country, when there is one, is still two
+-- capital letters, and a null passes a check by definition.
+--
+-- `init_instance()` is unchanged: `upper(null)` is null, and the row now takes
+-- it. An installation set up with a company keeps the country of that company,
+-- as before.
+
+alter table instance alter column country drop not null;
+
+comment on column instance.country is
+  'The country of the first company, when `ekwo init` created one with the installation. Null for an installation set up without a company. Informative: every company carries its own country, and nothing reads this one to decide anything.';

package/dist/assets/migrations/20260922120418_import_already_done_says_what.sql

@@ -0,0 +1,284 @@
+-- Ekwo OS — a second import of the same files says what the first one was.
+--
+-- `import_books()` refuses files it has already imported, by their checksum,
+-- and the refusal said when and then "(% entries, % to %)". For a trial
+-- balance — the first thing most people import, and an import with no entry
+-- at all — that read "0 entries, — to —": true, and no help to somebody
+-- trying to remember what they did. The row in `book_imports` knows more: the
+-- file names, the source, the time, and the number of the opening entry.
+--
+-- So the refusal names them: which files, read as which source, imported when
+-- (to the minute, in UTC, since a person may import twice in one day), and
+-- what that import wrote — its entries with their first and last number, its
+-- opening entry by number, or both. The function is otherwise the one of
+-- `20260922081645_books_taken_over_from_an_export`, republished whole because
+-- a function body cannot be patched.
+
+create or replace function import_books(
+  p_company_id            uuid,
+  p_books                 jsonb,
+  p_dry_run               boolean default false,
+  p_open_years            boolean default false,
+  p_allow_result_accounts boolean default false
+)
+returns jsonb
+language plpgsql
+volatile
+security invoker
+as $$
+declare
+  v_checksum   text := p_books ->> 'checksum';
+  v_source     text := p_books ->> 'source';
+  v_previous   book_imports;
+  v_result     jsonb;
+  v_contacts   jsonb := '{}'::jsonb;
+  v_contact    jsonb;
+  v_contact_id uuid;
+  v_created    integer := 0;
+  v_found      integer := 0;
+  v_entry      jsonb;
+  v_draft      entries;
+  v_journal    uuid;
+  v_date       date;
+  v_missing    text;
+  v_years      jsonb := '[]'::jsonb;
+  v_year       uuid;
+  v_entries    integer := 0;
+  v_lines      integer := 0;
+  v_first      text;
+  v_last       text;
+  v_opening    jsonb := p_books -> 'opening';
+  v_opening_id uuid;
+  v_opening_no text;
+  v_debit      numeric := 0;
+  v_credit     numeric := 0;
+  v_journals   jsonb;
+begin
+  if not exists (select 1 from companies c where c.id = p_company_id) then
+    raise exception 'unknown_company: %', p_company_id using errcode = 'no_data_found';
+  end if;
+  -- Row level security is what refuses; this is what says why.
+  if not coalesce(is_installer(), false) then
+    if not coalesce(has_capability(p_company_id, 'entries.write'), false)
+       or not coalesce(has_capability(p_company_id, 'entries.post'), false) then
+      raise exception 'not_allowed: importing books into this company needs entries.write and entries.post'
+        using errcode = '42501';
+    end if;
+  end if;
+  if v_source is null or v_checksum is null then
+    raise exception 'invalid_books: the books name no source or no checksum — expected them as the importer builds them';
+  end if;
+  if jsonb_typeof(coalesce(p_books -> 'entries', '[]'::jsonb)) <> 'array' then
+    raise exception 'invalid_books: entries must be a list';
+  end if;
+  if jsonb_array_length(coalesce(p_books -> 'entries', '[]'::jsonb)) = 0
+     and (v_opening is null or jsonb_typeof(v_opening) = 'null') then
+    raise exception 'import_empty: the files hold no entry and no balance; there is nothing to import';
+  end if;
+
+  select * into v_previous from book_imports b
+   where b.company_id = p_company_id and b.checksum = v_checksum;
+  if found then
+    raise exception 'import_already_done: % (%) was imported on % UTC: %. Importing it again would count every amount twice',
+      coalesce(nullif(array_to_string(v_previous.file_names, ', '), ''), 'the same file'),
+      v_previous.source,
+      to_char(v_previous.created_at at time zone 'UTC', 'YYYY-MM-DD HH24:MI'),
+      concat_ws(' and ',
+        case when v_previous.entry_count > 0 then
+          v_previous.entry_count || case when v_previous.entry_count = 1 then ' entry' else ' entries' end
+          || coalesce(', numbered ' || v_previous.first_number
+                      || case when v_previous.last_number is distinct from v_previous.first_number
+                              then ' to ' || v_previous.last_number else '' end, '')
+        end,
+        case when v_previous.opening_number is not null then
+          'the opening entry ' || v_previous.opening_number
+        end,
+        v_previous.line_count || case when v_previous.line_count = 1 then ' line' else ' lines' end)
+      using errcode = '23505';
+  end if;
+
+  begin
+    -- 1. The years. Each date that falls in none is refused by name, or opened
+    --    when the caller asked for it.
+    for v_date in
+      select distinct d::date from (
+        select e ->> 'date' as d from jsonb_array_elements(coalesce(p_books -> 'entries', '[]'::jsonb)) e
+        union
+        select v_opening ->> 'date' where v_opening is not null and jsonb_typeof(v_opening) <> 'null'
+      ) dates
+      where d is not null
+      order by 1
+    loop
+      if fiscal_year_at(p_company_id, v_date) is null then
+        if not p_open_years then
+          raise exception 'import_outside_fiscal_year: % falls in no fiscal year of this company. Open that year, or ask the import to open the years it needs',
+            v_date
+            using errcode = '55006';
+        end if;
+        v_year := import_fiscal_year_for(p_company_id, v_date);
+        select v_years || jsonb_build_object('name', f.name, 'start_date', f.start_date::text, 'end_date', f.end_date::text)
+          into v_years from fiscal_years f where f.id = v_year;
+      end if;
+    end loop;
+
+    -- 2. The parties: by the code the source gave them, then by their name,
+    --    or created. A party the file names once is still one party.
+    for v_contact in select value from jsonb_array_elements(coalesce(p_books -> 'contacts', '[]'::jsonb)) loop
+      v_contact_id := null;
+      if nullif(v_contact ->> 'auxiliary_code', '') is not null then
+        select c.id into v_contact_id from contacts c
+         where c.company_id = p_company_id and c.auxiliary_code = v_contact ->> 'auxiliary_code'
+         order by c.created_at limit 1;
+      end if;
+      if v_contact_id is null then
+        select c.id into v_contact_id from contacts c
+         where c.company_id = p_company_id and lower(c.name) = lower(v_contact ->> 'name')
+         order by c.created_at limit 1;
+      end if;
+      if v_contact_id is null then
+        insert into contacts (company_id, name, contact_type, auxiliary_code,
+                              vat_number, registration_number, email, country)
+        values (p_company_id, v_contact ->> 'name',
+                coalesce(v_contact ->> 'contact_type', 'other')::contact_type,
+                nullif(v_contact ->> 'auxiliary_code', ''),
+                nullif(v_contact ->> 'vat_number', ''),
+                nullif(v_contact ->> 'registration_number', ''),
+                nullif(v_contact ->> 'email', ''),
+                nullif(upper(v_contact ->> 'country'), ''))
+        returning id into v_contact_id;
+        v_created := v_created + 1;
+      else
+        v_found := v_found + 1;
+      end if;
+      v_contacts := v_contacts || jsonb_build_object(v_contact ->> 'key', v_contact_id);
+    end loop;
+
+    -- 3. The accounts every line names, all of them, before anything is
+    --    written: one refusal that lists them is worth more than the first.
+    select string_agg(distinct code, ', ' order by code) into v_missing
+      from (
+        select l ->> 'account_code' as code
+          from jsonb_array_elements(coalesce(p_books -> 'entries', '[]'::jsonb)) e,
+               jsonb_array_elements(e -> 'lines') l
+        union
+        select l ->> 'account_code'
+          from jsonb_array_elements(coalesce(v_opening -> 'lines', '[]'::jsonb)) l
+      ) wanted
+     where not exists (select 1 from accounts a where a.company_id = p_company_id and a.code = wanted.code);
+    if v_missing is not null then
+      raise exception 'unknown_account: % % not in the chart of this company. Map each to an account of the chart',
+        v_missing, case when v_missing like '%,%' then 'are' else 'is' end
+        using errcode = 'no_data_found';
+    end if;
+
+    -- 4. The entries, each a draft and then posted by post_entry().
+    for v_entry in select value from jsonb_array_elements(coalesce(p_books -> 'entries', '[]'::jsonb)) loop
+      select j.id into v_journal from journals j
+       where j.company_id = p_company_id and j.code = v_entry ->> 'journal_code';
+      if v_journal is null then
+        raise exception 'unknown_journal: % is not a journal of this company', v_entry ->> 'journal_code'
+          using errcode = 'no_data_found';
+      end if;
+
+      insert into entries (company_id, journal_id, entry_date, number, reference, description, state, currency_code)
+      select p_company_id, v_journal, (v_entry ->> 'date')::date,
+             nullif(v_entry ->> 'number', ''),
+             nullif(v_entry ->> 'reference', ''),
+             nullif(v_entry ->> 'description', ''),
+             'draft', c.currency_code
+        from companies c where c.id = p_company_id
+      returning * into v_draft;
+
+      insert into entry_lines (entry_id, company_id, account_id, sequence, name, debit, credit,
+                               contact_id, currency_code, amount_currency, date_maturity)
+      select v_draft.id, p_company_id, a.id, (l.ordinality * 10)::integer,
+             nullif(l.value ->> 'label', ''),
+             coalesce((l.value ->> 'debit')::numeric, 0),
+             coalesce((l.value ->> 'credit')::numeric, 0),
+             case when l.value ->> 'contact_key' is null then null
+                  else (v_contacts ->> (l.value ->> 'contact_key'))::uuid end,
+             nullif(l.value ->> 'currency_code', ''),
+             nullif(l.value ->> 'amount_currency', '')::numeric,
+             nullif(l.value ->> 'date_maturity', '')::date
+        from jsonb_array_elements(v_entry -> 'lines') with ordinality l
+        join accounts a on a.company_id = p_company_id and a.code = l.value ->> 'account_code';
+
+      v_draft := post_entry(v_draft.id);
+      v_entries := v_entries + 1;
+      v_lines := v_lines + jsonb_array_length(v_entry -> 'lines');
+      v_debit := v_debit + v_draft.total_debit;
+      v_credit := v_credit + v_draft.total_credit;
+      v_first := coalesce(v_first, v_draft.number);
+      v_last := v_draft.number;
+    end loop;
+
+    -- 5. The balances, as the opening entry of the year they open.
+    if v_opening is not null and jsonb_typeof(v_opening) <> 'null' then
+      v_year := fiscal_year_at(p_company_id, (v_opening ->> 'date')::date);
+      if (select f.start_date from fiscal_years f where f.id = v_year) <> (v_opening ->> 'date')::date then
+        raise exception 'opening_not_first_day: an opening balance is dated on the first day of a fiscal year, and % is not; the year it falls in starts on %',
+          v_opening ->> 'date', (select f.start_date from fiscal_years f where f.id = v_year);
+      end if;
+      v_opening_id := opening_balance(
+        p_company_id, v_year,
+        (select jsonb_agg(jsonb_build_object(
+                  'account_code', l ->> 'account_code',
+                  'debit', l ->> 'debit',
+                  'credit', l ->> 'credit',
+                  'label', coalesce(nullif(l ->> 'label', ''), 'Opening balance'),
+                  'contact_id', case when l ->> 'contact_key' is null then null
+                                     else v_contacts ->> (l ->> 'contact_key') end))
+           from jsonb_array_elements(v_opening -> 'lines') l),
+        p_allow_result_accounts);
+      select e.number into v_opening_no from entries e where e.id = v_opening_id;
+      v_lines := v_lines + jsonb_array_length(v_opening -> 'lines');
+    end if;
+
+    select coalesce(jsonb_agg(jsonb_build_object('journal_code', j.code, 'entries', n) order by j.code), '[]'::jsonb)
+      into v_journals
+      from (select e ->> 'journal_code' as code, count(*) as n
+              from jsonb_array_elements(coalesce(p_books -> 'entries', '[]'::jsonb)) e
+             group by 1) per
+      join journals j on j.company_id = p_company_id and j.code = per.code;
+
+    insert into book_imports (company_id, source, checksum, file_names, entry_count, line_count,
+                              first_number, last_number, opening_number)
+    values (p_company_id, v_source, v_checksum,
+            coalesce((select array_agg(value) from jsonb_array_elements_text(coalesce(p_books -> 'file_names', '[]'::jsonb))), '{}'),
+            v_entries, v_lines, v_first, v_last, v_opening_no);
+
+    v_result := jsonb_build_object(
+      'dry_run', p_dry_run,
+      'source', v_source,
+      'entries', v_entries,
+      'lines', v_lines,
+      'total_debit', v_debit::text,
+      'total_credit', v_credit::text,
+      'first_number', v_first,
+      'last_number', v_last,
+      'opening_number', v_opening_no,
+      'journals', v_journals,
+      'contacts_created', v_created,
+      'contacts_found', v_found,
+      'fiscal_years_opened', v_years
+    );
+
+    if p_dry_run then
+      -- The way out of the block that undoes everything done inside it. A
+      -- variable is not part of the transaction, so the answer survives.
+      raise exception using errcode = 'EKW01', message = 'rehearsal';
+    end if;
+  exception
+    when sqlstate 'EKW01' then
+      null;
+  end;
+
+  return v_result;
+end;
+$$;
+
+comment on function import_books(uuid, jsonb, boolean, boolean, boolean) is
+  'Takes over books read from another system, whole or not at all: the fiscal years they need (p_open_years), their parties, every entry posted through post_entry() and a trial balance through opening_balance(). Account codes arrive already translated into the company''s chart. p_dry_run does all of it and rolls it back, so the answer and the refusals are the real ones. The same files twice are refused (import_already_done).';
+
+revoke execute on function import_books(uuid, jsonb, boolean, boolean, boolean) from public, anon;
+grant execute on function import_books(uuid, jsonb, boolean, boolean, boolean) to authenticated, service_role;

package/dist/assets/migrations/20260922124012_schema_version_0_7_0.sql

@@ -0,0 +1,40 @@
+-- Ekwo OS — the schema this release defines is 0.7.0.
+--
+-- `ekwo_schema_version()` is the one place the number lives, and a migration
+-- is the only thing that moves it. A database then answers for the files it
+-- has actually run rather than for what somebody believed it had run: the
+-- column default and `init_instance()` both call this function, so a fresh
+-- install records the new number without a second edit, and `ekwo migrate`
+-- reads it back onto `instance.schema_version` for a database that was
+-- installed at an older one.
+--
+-- Between 0.6.0 and here the schema gained two things. `instance.country` is
+-- nullable, because `ekwo init --no-company` installs without a company and
+-- so without a country to write down; `ekwo company new` then creates each
+-- company in its own country through `create_company()`. And `import_books()`
+-- says, when it refuses files it has already imported, which files, read as
+-- which source, when, and what that import wrote. A 0.6.0 database has
+-- neither. The packages of this release call no function a 0.6.0 database
+-- lacks, but they are built and tested against the installation these two
+-- migrations leave, and `ekwo migrate` brings a 0.6.0 one there in a second:
+-- so the packages declare 0.7.0 as their floor and refuse an older database by
+-- name, as every release has, rather than answering for one they were never
+-- run against.
+
+create or replace function ekwo_schema_version()
+returns text
+language sql
+immutable
+as $$
+  select '0.7.0'::text;
+$$;
+
+comment on function ekwo_schema_version() is
+  'Schema version of the installed release. Bumped by a migration, never by hand.';
+
+-- `create or replace` keeps the privileges the function already had, and the
+-- revoke is what every migration of this directory ends with: a function that
+-- comes out with the built-in default is published by Supabase as an
+-- anonymous RPC endpoint.
+revoke execute on all functions in schema public from public;
+grant execute on function ekwo_schema_version() to authenticated, service_role;

package/dist/auth.d.ts

@@ -38,6 +38,23 @@ export interface CreateAuthUserOptions {
 }
 /** How the bootstrap gets a user id. Injected, so tests never hit the network. */
 export type CreateAuthUser = (options: CreateAuthUserOptions) => Promise<AuthUser>;
+/**
+ * The headers the admin API is called with, for either form of the key.
+ *
+ * A legacy `service_role` key is a JWT, and GoTrue has always read it from
+ * `Authorization: Bearer` as well as from `apikey`. A secret key of the newer
+ * form — `sb_secret_…` — is a short string and not a JWT: Supabase documents
+ * that it travels on `apikey` and not on `Authorization: Bearer`, where
+ * anything that tries to verify it as a JWT refuses it. The CLI used to send
+ * it both ways; a walkthrough on a new project stopped at the first
+ * administrator with such a key, although a probe of 22 September 2026 found
+ * the gateway still tolerating a Bearer equal to `apikey`. What is documented
+ * is what is relied on: the new form goes on `apikey` alone, and the gateway
+ * turns it into the role it stands for.
+ */
+export declare function adminHeaders(key: string): Record<string, string>;
+/** A key of the newer form, `sb_secret_…` or `sb_publishable_…`: not a JWT. */
+export declare function isOpaqueKey(key: string): boolean;
 /**
  * Creates the first administrator in the customer's own Supabase Auth.
  *

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEjF,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,kFAAkF;AAClF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AA6BnF;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,EAAE,cAwE5B,CAAC;AAEF,4DAA4D;AAC5D,wBAAsB,mBAAmB,CAAC,EACxC,WAAW,EACX,cAAc,EACd,KAAK,EACL,SAA4B,GAC7B,EAAE;IACD,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAiBhC"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEjF,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,kFAAkF;AAClF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAMnF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMhE;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhD;AAiBD;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,EAAE,cAwE5B,CAAC;AAEF,4DAA4D;AAC5D,wBAAsB,mBAAmB,CAAC,EACxC,WAAW,EACX,cAAc,EACd,KAAK,EACL,SAA4B,GAC7B,EAAE;IACD,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAiBhC"}