ekwo-os 0.4.1

package/dist/assets/modules/assets/supabase/migrations/20260918150801_assets_leave_with_the_company.sql

@@ -0,0 +1,41 @@
+-- Ekwo module `assets` — its tables leave with the company.
+--
+-- The socle writes an archive of one company from a registry of tables, and
+-- refuses to write one while a table that belongs to a company is
+-- unclassified. A module answers for its own through `<schema>.archive_tables()`,
+-- looked up by the socle the way `can_disable()` is — a function in this schema
+-- and not rows in a table of the socle, because this migration may be applied
+-- on a socle that does not have that table yet.
+--
+-- All three tables travel. The register and the schedule are the company's,
+-- and a depreciation line points at the entry it posted: left behind, the
+-- ledger would arrive with entries tagged `assets` that nothing explains.
+-- `category_templates` and `country_rules` are reference data of the
+-- installation and belong to no company.
+--
+-- `load_order` is relative to this module; the socle places every module after
+-- its own tables.
+
+create or replace function assets.archive_tables()
+returns table (
+  table_name  text,
+  disposition text,
+  reason      text,
+  via_column  text,
+  via_table   text,
+  load_order  integer
+)
+language sql
+immutable
+as $$
+  values
+    ('assets'::text,       'exported'::text, null::text, null::text, null::text, 1),
+    ('depreciation_lines', 'exported',       null,       null,       null,       2),
+    ('disposals',          'exported',       null,       null,       null,       3);
+$$;
+
+comment on function assets.archive_tables() is
+  'What an archive of one company does with each table of this module. Read by `public.company_archive_tables()`.';
+
+revoke execute on function assets.archive_tables() from public, anon;
+grant execute on function assets.archive_tables() to authenticated, service_role;

package/dist/assets/modules/budgets/module.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://ekwo.ai/schemas/module/1.json",
+  "code": "budgets",
+  "name": "Budgets",
+  "description": "A budget per financial year, its lines per account and period, and the variance against what the ledger actually holds. Reads the socle and writes nothing to it.",
+  "schema": "budgets",
+  "version": "1.0.0",
+  "status": "available",
+  "requires_socle_min": "20260913074512",
+  "posts": false,
+  "mcp": { "prefix": "budgets" }
+}

package/dist/assets/modules/budgets/supabase/migrations/20260913083012_budgets.sql

@@ -0,0 +1,210 @@
+-- Ekwo — the `budgets` module: what a company planned, against what it booked.
+--
+-- The second module, and the one that proves the mechanism holds for a module
+-- that is not like the first. It has **no country data at all** — a budget is a
+-- decision a business takes, not a rule a country writes — and it **never
+-- writes to the ledger**: it reads `public.entry_lines` and compares. So there
+-- is no pack section, no seed, no call to `post_module_entry()`, and
+-- `module.json` says `"posts": false`, which a test holds it to.
+--
+-- It also deliberately writes **no `budgets.can_disable()`**. The convention
+-- `disable_module()` follows is to look for that function and allow the
+-- disable when there is none, and this is the module that exercises the
+-- absence: turning budgets off takes nothing away, because the rows stay where
+-- they are and come back the moment it is turned on again. Row level security
+-- is what hides them in between, which is the whole meaning of
+-- `module_enabled()` sitting in every policy.
+--
+-- **The sign.** A budget is stated the way a business says it out loud: an
+-- income of 100 000 and a cost of 60 000 are both positive numbers. The ledger
+-- does not work that way — an income account carries a credit balance — so the
+-- comparison multiplies the ledger balance by −1 on an income account and by
+-- +1 everywhere else. That is one rule, it comes from `accounts.internal_group`
+-- rather than from a column somebody fills in, and it is what the eighteen
+-- account types are for.
+--
+-- **What counts as actual.** Posted entries, and only the ones that are
+-- `kind = 'normal'`. A closing entry is the mirror image of the year and an
+-- appropriation entry moves its result; neither is something a budget planned,
+-- and leaving them in would make a closed year read as a variance of exactly
+-- minus the budget. That is the same exclusion `financial_statement()` makes on
+-- an income statement, for the same reason.
+
+create schema budgets;
+
+comment on schema budgets is
+  'Ekwo module `budgets`: what a company planned, per account and period, against what its ledger holds. Reads the socle, writes nothing to it.';
+
+create type budgets.budget_state as enum ('draft', 'approved', 'closed');
+
+comment on type budgets.budget_state is
+  'draft while it is being written, approved once it is the plan, closed when the period it covers is behind. It gates nothing in this module: a variance is a reading, and reading a draft is useful.';
+
+create table budgets.budgets (
+  id             uuid primary key default gen_random_uuid(),
+  company_id     uuid not null references public.companies(id) on delete cascade,
+  fiscal_year_id uuid references public.fiscal_years(id) on delete restrict,
+  code           text not null,
+  name           text not null,
+  state          budgets.budget_state not null default 'draft',
+  notes          text,
+  created_at     timestamptz not null default now(),
+  updated_at     timestamptz not null default now(),
+  unique (company_id, code),
+  foreign key (fiscal_year_id) references public.fiscal_years(id)
+);
+
+comment on table budgets.budgets is
+  'One budget of one company, usually for one financial year. A company may hold several — a plan and a revision are two budgets and not two columns.';
+comment on column budgets.budgets.fiscal_year_id is
+  'The year this budget is for, where it is for one. Null on a rolling budget, whose lines carry their own periods anyway.';
+
+create unique index budgets_id_company_idx on budgets.budgets (id, company_id);
+
+create trigger budgets_set_updated_at
+  before update on budgets.budgets
+  for each row execute function public.set_updated_at();
+
+create table budgets.lines (
+  id           uuid primary key default gen_random_uuid(),
+  budget_id    uuid not null references budgets.budgets(id) on delete cascade,
+  company_id   uuid not null references public.companies(id) on delete cascade,
+  account_id   uuid not null references public.accounts(id) on delete restrict,
+  period_start date not null,
+  period_end   date not null,
+  amount       numeric(16, 2) not null,
+  note         text,
+  created_at   timestamptz not null default now(),
+  updated_at   timestamptz not null default now(),
+  -- One line per account and period. A second figure for the same month on the
+  -- same account is a revision, and a revision is a budget of its own.
+  unique (budget_id, account_id, period_start, period_end),
+  constraint budgets_lines_period check (period_end >= period_start),
+  foreign key (budget_id, company_id) references budgets.budgets(id, company_id) on delete cascade,
+  foreign key (account_id, company_id) references public.accounts(id, company_id)
+);
+
+comment on table budgets.lines is
+  'What one account is expected to carry over one period, in the sign a business says it: an income and a cost are both positive.';
+
+create index budgets_lines_account_idx on budgets.lines (company_id, account_id, period_start);
+
+create trigger budgets_lines_set_updated_at
+  before update on budgets.lines
+  for each row execute function public.set_updated_at();
+
+-- ---------------------------------------------------------------------------
+-- The reading
+-- ---------------------------------------------------------------------------
+
+create or replace function budgets.variance(
+  p_company_id uuid,
+  p_budget_id  uuid,
+  p_from       date,
+  p_to         date
+)
+returns table (
+  account_code text,
+  account_name text,
+  budget       numeric,
+  actual       numeric,
+  variance     numeric
+)
+language sql
+stable
+as $$
+  with planned as (
+    select l.account_id, sum(l.amount) as amount
+      from budgets.lines l
+     where l.budget_id = p_budget_id
+       and l.company_id = p_company_id
+       and l.period_start >= p_from
+       and l.period_end <= p_to
+     group by l.account_id
+  ),
+  booked as (
+    select l.account_id,
+           sum((l.debit - l.credit) * case when a.internal_group = 'income' then -1 else 1 end) as amount
+      from public.entry_lines l
+      join public.entries e on e.id = l.entry_id
+      join public.accounts a on a.id = l.account_id
+     where l.company_id = p_company_id
+       and e.state = 'posted'
+       and e.kind = 'normal'
+       and e.entry_date between p_from and p_to
+       and l.account_id in (select account_id from planned)
+     group by l.account_id
+  )
+  select a.code,
+         a.name,
+         coalesce(p.amount, 0)::numeric(16, 2),
+         coalesce(b.amount, 0)::numeric(16, 2),
+         (coalesce(b.amount, 0) - coalesce(p.amount, 0))::numeric(16, 2)
+    from planned p
+    join public.accounts a on a.id = p.account_id
+    left join booked b on b.account_id = p.account_id
+   order by a.code;
+$$;
+
+comment on function budgets.variance(uuid, uuid, date, date) is
+  'Budget against ledger, per account, over a period. Both figures are in the sign a business states them in — an income account''s credit balance is flipped — and the variance is the actual less the plan. Reads posted entries of kind `normal` only: a closing or appropriation entry is not what a period earned.';
+
+-- ---------------------------------------------------------------------------
+-- Row level security
+-- ---------------------------------------------------------------------------
+
+alter table budgets.budgets enable row level security;
+alter table budgets.lines   enable row level security;
+
+create policy budgets_select on budgets.budgets
+  for select using (public.module_enabled(company_id, 'budgets'));
+create policy budgets_write on budgets.budgets
+  for all using (public.module_enabled(company_id, 'budgets') and public.can_write_company(company_id))
+  with check (public.module_enabled(company_id, 'budgets') and public.can_write_company(company_id));
+
+create policy budgets_lines_select on budgets.lines
+  for select using (public.module_enabled(company_id, 'budgets'));
+create policy budgets_lines_write on budgets.lines
+  for all using (public.module_enabled(company_id, 'budgets') and public.can_write_company(company_id))
+  with check (public.module_enabled(company_id, 'budgets') and public.can_write_company(company_id));
+
+-- ---------------------------------------------------------------------------
+-- Privileges — a module schema does its own, because `public` gets them from
+-- Supabase's default privileges and a schema a migration created gets nothing.
+-- ---------------------------------------------------------------------------
+
+grant usage on schema budgets to anon, authenticated, service_role;
+
+grant select on all tables in schema budgets to anon;
+grant select, insert, update, delete on all tables in schema budgets to authenticated, service_role;
+grant execute on all functions in schema budgets to authenticated, service_role;
+
+alter default privileges in schema budgets grant select on tables to anon;
+alter default privileges in schema budgets
+  grant select, insert, update, delete on tables to authenticated, service_role;
+alter default privileges in schema budgets revoke execute on functions from public, anon;
+alter default privileges in schema budgets grant execute on functions to authenticated, service_role;
+
+revoke execute on all functions in schema budgets from public;
+
+-- ---------------------------------------------------------------------------
+-- The registry row
+-- ---------------------------------------------------------------------------
+
+insert into public.modules (code, name, description, schema_name, version, status, requires_socle_min)
+values (
+  'budgets',
+  'Budgets',
+  'A budget per financial year, its lines per account and period, and the variance against what the ledger actually holds. No country data, and nothing written to the ledger.',
+  'budgets',
+  '1.0.0',
+  'available',
+  '20260913074512'
+)
+on conflict (code) do update set
+  name               = excluded.name,
+  description        = excluded.description,
+  schema_name        = excluded.schema_name,
+  version            = excluded.version,
+  status             = excluded.status,
+  requires_socle_min = excluded.requires_socle_min;

package/dist/assets/modules/budgets/supabase/migrations/20260913104233_foreign_key_indexes.sql

@@ -0,0 +1,37 @@
+-- Ekwo OS — a foreign key without an index is a sequential scan waiting for
+-- a big enough table.
+--
+-- Postgres indexes the *referenced* side of a foreign key, because that side
+-- is a primary key. It indexes nothing on the referencing side. Two things
+-- then read the whole table:
+--
+--   * every delete or key update of the parent, which has to prove no child
+--     points at the row — deleting one contact scans `entry_lines`;
+--   * every join written the natural way, which for an accounting core is
+--     most of them: a document to its lines, an entry to its lines, a line to
+--     its account, its tax, its contact.
+--
+-- On the demo company nothing is slow, which is exactly why this survived 49
+-- migrations. On a company with four years of books it is the difference
+-- between a report and a timeout.
+--
+-- 3 indexes: every foreign key of the `budgets` module that had none, and the
+-- `company_id` of the tables that had none either — which the sweep covers,
+-- because `company_id` is itself a foreign key everywhere it appears.
+--
+-- Where a table has both a single-column key and a composite one leading with
+-- the same column — `(account_id)` and `(account_id, company_id)`, the shape
+-- this schema uses to keep a child in its parent's company — one index on the
+-- composite serves both, and that is the one created.
+--
+-- The list is not maintained by hand. `tests/schema.test.ts` asks the
+-- catalogue the same question and fails when the answer is not empty, so a
+-- foreign key added later arrives with its index or the build says so.
+
+
+-- budgets.budgets
+create index if not exists budgets_fiscal_year_idx on budgets.budgets (fiscal_year_id);
+
+-- budgets.lines
+create index if not exists lines_account_company_idx on budgets.lines (account_id, company_id);
+create index if not exists lines_budget_company_idx on budgets.lines (budget_id, company_id);

package/dist/assets/modules/budgets/supabase/migrations/20260913104501_budgets_capabilities.sql

@@ -0,0 +1,72 @@
+-- Ekwo module `budgets` — the module names what it lets somebody do.
+--
+-- Its policies asked `public.can_write_company()`, which is `entries.write`:
+-- whoever may draft a journal entry could also write next year's budget. A
+-- budget is not a book — it is written by whoever plans, read by whoever
+-- reports, and it is the one thing in an installation that is deliberately
+-- not the truth. Sharing a lock with the ledger is the wrong shape.
+--
+--   budgets.read  — see the budgets and their variance.
+--   budgets.write — create and change a budget and its lines.
+--
+-- There is no `budgets.post`: this module writes nothing to the ledger, which
+-- its manifest says (`"posts": false`) and a test of the socle enforces.
+--
+-- The presets follow the socle's. The owner preset was filled with `select
+-- 'owner', code from capabilities` at the socle's own migration time, so a
+-- code added later has to name the owner itself.
+
+insert into public.capabilities (code, area, description) values
+  ('budgets.read',  'budgets', 'Read the budgets of a company and their variance against the ledger.'),
+  ('budgets.write', 'budgets', 'Create and change a budget and its lines.')
+on conflict (code) do update set area = excluded.area, description = excluded.description;
+
+insert into public.role_capabilities (role, capability) values
+  ('viewer'::public.member_role,     'budgets.read'),
+  ('accountant'::public.member_role, 'budgets.read'),
+  ('accountant'::public.member_role, 'budgets.write'),
+  ('owner'::public.member_role,      'budgets.read'),
+  ('owner'::public.member_role,      'budgets.write')
+on conflict do nothing;
+
+-- `module_enabled()` stays in front of every policy: a capability says what a
+-- person may do, and the module being enabled says whether the company has
+-- this at all.
+
+drop policy budgets_select on budgets.budgets;
+create policy budgets_select on budgets.budgets
+  for select using (
+    public.module_enabled(company_id, 'budgets')
+    and public.has_capability(company_id, 'budgets.read')
+  );
+
+drop policy budgets_write on budgets.budgets;
+create policy budgets_write on budgets.budgets
+  for all using (
+    public.module_enabled(company_id, 'budgets')
+    and public.has_capability(company_id, 'budgets.write')
+  )
+  with check (
+    public.module_enabled(company_id, 'budgets')
+    and public.has_capability(company_id, 'budgets.write')
+  );
+
+drop policy budgets_lines_select on budgets.lines;
+create policy budgets_lines_select on budgets.lines
+  for select using (
+    public.module_enabled(company_id, 'budgets')
+    and public.has_capability(company_id, 'budgets.read')
+  );
+
+drop policy budgets_lines_write on budgets.lines;
+create policy budgets_lines_write on budgets.lines
+  for all using (
+    public.module_enabled(company_id, 'budgets')
+    and public.has_capability(company_id, 'budgets.write')
+  )
+  with check (
+    public.module_enabled(company_id, 'budgets')
+    and public.has_capability(company_id, 'budgets.write')
+  );
+
+revoke execute on all functions in schema budgets from public;

package/dist/assets/modules/budgets/supabase/migrations/20260914122400_budgets_round_at_the_currency.sql

@@ -0,0 +1,68 @@
+-- Ekwo OS (budgets) — a plan and what was booked against it are written at
+-- the decimals of the company's currency.
+--
+-- `budgets.variance()` cast its three figures to `numeric(16, 2)`, which is a
+-- rounding to two decimals wearing the clothes of a type. A plan stated in a
+-- currency with no decimals came back with two of them, and the variance
+-- between a plan and a ledger that both hold whole units read as a fraction.
+--
+-- The three casts become `public.round_amount`, which asks the company what
+-- its currency is. Nothing else about the reading changes: the sign a business
+-- states a figure in, and the closing entries left out of it, are as they were.
+
+create or replace function budgets.variance(
+  p_company_id uuid,
+  p_budget_id  uuid,
+  p_from       date,
+  p_to         date
+)
+returns table (
+  account_code text,
+  account_name text,
+  budget       numeric,
+  actual       numeric,
+  variance     numeric
+)
+language sql
+stable
+as $$
+  with planned as (
+    select l.account_id, sum(l.amount) as amount
+      from budgets.lines l
+     where l.budget_id = p_budget_id
+       and l.company_id = p_company_id
+       and l.period_start >= p_from
+       and l.period_end <= p_to
+     group by l.account_id
+  ),
+  booked as (
+    select l.account_id,
+           sum((l.debit - l.credit) * case when a.internal_group = 'income' then -1 else 1 end) as amount
+      from public.entry_lines l
+      join public.entries e on e.id = l.entry_id
+      join public.accounts a on a.id = l.account_id
+     where l.company_id = p_company_id
+       and e.state = 'posted'
+       and e.kind = 'normal'
+       and e.entry_date between p_from and p_to
+       and l.account_id in (select account_id from planned)
+     group by l.account_id
+  )
+  select a.code,
+         a.name,
+         public.round_amount(coalesce(p.amount, 0), r.rounding),
+         public.round_amount(coalesce(b.amount, 0), r.rounding),
+         public.round_amount(coalesce(b.amount, 0) - coalesce(p.amount, 0), r.rounding)
+    from planned p
+    join public.accounts a on a.id = p.account_id
+    left join booked b on b.account_id = p.account_id
+    cross join (select public.rounding_of(p_company_id) as rounding) r
+   order by a.code;
+$$;
+
+
+comment on function budgets.variance(uuid, uuid, date, date) is
+  'Budget against ledger, per account, over a period, at the decimals of the company''s currency. Both figures are in the sign a business states them in — an income account''s credit balance is flipped — and the variance is the actual less the plan. Reads posted entries of kind `normal` only: a closing or appropriation entry is not what a period earned.';
+
+
+revoke execute on all functions in schema budgets from public;

package/dist/assets/modules/budgets/supabase/migrations/20260914145048_budgets_accounts_in_use.sql

@@ -0,0 +1,30 @@
+-- The `budgets` module answers which accounts of a company it holds.
+--
+-- Same convention as `assets`: `public.accounts_in_use()` asks each module the
+-- company has enabled for `<schema>.accounts_in_use(uuid)` rather than naming
+-- the schema itself, so the socle keeps ignoring what is built beside it.
+--
+-- A budget line is a planned amount on an account, and an account somebody has
+-- budgeted for is an account they mean to use — which is the whole case for
+-- counting it before anything is booked on it.
+--
+-- Security invoker: the policies of `budgets.lines` decide, and a caller who
+-- is not a member of the company sees nothing.
+
+create or replace function budgets.accounts_in_use(p_company_id uuid)
+returns setof uuid
+language sql
+stable
+as $$
+  select distinct l.account_id
+    from budgets.lines l
+   where l.company_id = p_company_id;
+$$;
+
+comment on function budgets.accounts_in_use(uuid) is
+  'The accounts this module points at for one company: every account a budget line plans an amount on. Read by public.accounts_in_use() through the module convention.';
+
+revoke execute on function budgets.accounts_in_use(uuid) from public, anon;
+grant execute on function budgets.accounts_in_use(uuid) to authenticated, service_role;
+
+revoke execute on all functions in schema budgets from public;

package/dist/assets/modules/budgets/supabase/migrations/20260914151812_budgets_grants_its_own_rights.sql

@@ -0,0 +1,31 @@
+-- The `budgets` module grants its own rights, by name.
+--
+-- Same change as `20260914151207` for the socle and
+-- `20260914151530` for `assets`: the privileges a module schema hands out are
+-- written down, table by table, instead of being taken from a wildcard or
+-- from the project's default privileges.
+--
+-- `20260913083012` granted `select on all tables in schema budgets to anon`.
+-- Row level security answered every such read with an empty set, so nothing
+-- leaked, and the doctrine of `20260911210131` still says the anonymous role
+-- reaches the policy helpers and nothing else. Published migrations are never
+-- edited, so it is corrected here.
+
+revoke all on all tables    in schema budgets from anon, authenticated, service_role;
+revoke all on all sequences in schema budgets from anon, authenticated, service_role;
+
+alter default privileges in schema budgets revoke all on tables    from anon, authenticated, service_role;
+alter default privileges in schema budgets revoke all on sequences from anon, authenticated, service_role;
+alter default privileges in schema budgets revoke execute on functions from public, anon, authenticated, service_role;
+
+-- Both tables carry a policy `for all`: a budget and its lines are written by
+-- the people who plan the year, and read by everyone who may read the books.
+grant select, insert, update, delete on table
+  budgets.budgets,
+  budgets.lines
+to authenticated, service_role;
+
+-- `budgets.variance` keeps the grant its own migration gave it. The schema
+-- has no trigger function and no sequence.
+
+revoke execute on all functions in schema budgets from public;

package/dist/assets/modules/budgets/supabase/migrations/20260918113954_budgets_client_reads.sql

@@ -0,0 +1,20 @@
+-- Ekwo module `budgets` — the client preset reads this module too.
+--
+-- The socle's `client` preset holds what `viewer` holds, and it was filled
+-- from `role_capabilities` when the socle's migration ran: on an installation
+-- that already carried this module, `budgets.read` was copied then. On a fresh
+-- one the socle is applied before any module, so the row has to come from
+-- here.
+--
+-- The label is read from the catalogue rather than written as a literal. A
+-- module may be applied on a socle older than the preset, where
+-- `'client'::member_role` does not parse; there this inserts nothing, and the
+-- socle's migration copies the row the day it arrives.
+
+insert into public.role_capabilities (role, capability)
+select e.enumlabel::text::public.member_role, 'budgets.read'
+  from pg_catalog.pg_enum e
+  join pg_catalog.pg_type t on t.oid = e.enumtypid
+  join pg_catalog.pg_namespace n on n.oid = t.typnamespace
+ where n.nspname = 'public' and t.typname = 'member_role' and e.enumlabel = 'client'
+on conflict do nothing;

package/dist/assets/modules/budgets/supabase/migrations/20260918150823_budgets_leave_with_the_company.sql

@@ -0,0 +1,37 @@
+-- Ekwo module `budgets` — its tables leave with the company.
+--
+-- The socle writes an archive of one company from a registry of tables, and
+-- refuses to write one while a table that belongs to a company is
+-- unclassified. A module answers for its own through `<schema>.archive_tables()`,
+-- looked up by the socle the way `can_disable()` is — a function in this schema
+-- and not rows in a table of the socle, because this migration may be applied
+-- on a socle that does not have that table yet.
+--
+-- A budget is a plan the company wrote against its own chart and its own
+-- financial years. It posts nothing, and it is still the company's.
+--
+-- `load_order` is relative to this module; the socle places every module after
+-- its own tables.
+
+create or replace function budgets.archive_tables()
+returns table (
+  table_name  text,
+  disposition text,
+  reason      text,
+  via_column  text,
+  via_table   text,
+  load_order  integer
+)
+language sql
+immutable
+as $$
+  values
+    ('budgets'::text, 'exported'::text, null::text, null::text, null::text, 1),
+    ('lines',         'exported',       null,       null,       null,       2);
+$$;
+
+comment on function budgets.archive_tables() is
+  'What an archive of one company does with each table of this module. Read by `public.company_archive_tables()`.';
+
+revoke execute on function budgets.archive_tables() from public, anon;
+grant execute on function budgets.archive_tables() to authenticated, service_role;

package/dist/assets/modules/schema/module.1.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ekwo.ai/schemas/module/1.json",
+  "title": "Ekwo module manifest, version 1",
+  "description": "What a module of Ekwo OS says about itself. One file, `modules/<code>/module.json`, read by `ekwo module list|enable|migrate`, by the MCP loader and by the guard tests. Everything a module *does* is in its migrations; this says where it lives and what it is allowed to reach.",
+  "type": "object",
+  "required": ["code", "name", "schema", "version", "status"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "code": {
+      "$ref": "#/$defs/identifier",
+      "description": "The module's identifier, and the key of `public.modules`. Immutable once published: it is written on every entry the module posts."
+    },
+    "name": { "type": "string", "minLength": 1, "maxLength": 120 },
+    "description": { "type": "string", "minLength": 1, "maxLength": 400 },
+    "schema": {
+      "$ref": "#/$defs/identifier",
+      "description": "The Postgres schema the module lives in. One schema per module, never `public`, and PostgREST only serves it once it is listed in the project's exposed schemas."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$",
+      "description": "Semver, on the same scale a pack uses: a label is a patch, a table or a column is a minor, a change that asks a company to do something is a major."
+    },
+    "status": {
+      "enum": ["draft", "available", "deprecated"],
+      "description": "draft: installed and refused by enable_module(). available: enableable. deprecated: the companies that hold it keep working and no new one may enable it."
+    },
+    "requires_socle_min": {
+      "type": "string",
+      "pattern": "^[0-9]{14}$",
+      "description": "The oldest socle migration this module needs, by its timestamp version. `ekwo module enable` compares it against the migration history and refuses rather than letting a foreign key fail halfway."
+    },
+    "posts": {
+      "type": "boolean",
+      "description": "Whether this module writes to the ledger, always through post_module_entry(). A module that says false is held to it: a test refuses post_module_entry in its migrations."
+    },
+    "mcp": {
+      "type": "object",
+      "required": ["prefix"],
+      "additionalProperties": false,
+      "properties": {
+        "prefix": {
+          "$ref": "#/$defs/identifier",
+          "description": "Every MCP tool of this module is named `<prefix>_<verb>`, so a model reading a tool list can tell which module answers for what."
+        }
+      }
+    },
+    "pack": {
+      "type": "object",
+      "description": "The country data this module reads, if any. A module with no `pack` section has no country rule at all — which is most of them.",
+      "required": ["section"],
+      "additionalProperties": false,
+      "properties": {
+        "section": {
+          "$ref": "#/$defs/identifier",
+          "description": "The file a country pack carries for this module: `packs/<cc>/<section>.json`, compiled by `ekwo pack build` into `supabase/seed/modules/<code>/`."
+        }
+      }
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]{1,30}$"
+    }
+  }
+}

package/dist/assets/seed/00_currencies.sql

@@ -0,0 +1,15 @@
+-- Ekwo OS — currencies. ISO 4217, the handful a European ledger meets.
+
+insert into currencies (code, name, symbol, decimal_places) values
+  ('EUR', 'Euro',                 E'€', 2),
+  ('USD', 'US dollar',            '$',       2),
+  ('GBP', 'Pound sterling',       E'£', 2),
+  ('CHF', 'Swiss franc',          'CHF',     2),
+  ('SEK', 'Swedish krona',        'kr',      2),
+  ('DKK', 'Danish krone',         'kr',      2),
+  ('NOK', 'Norwegian krone',      'kr',      2),
+  ('PLN', 'Polish zloty',         E'z\u0142', 2),
+  ('CZK', 'Czech koruna',         E'Kč', 2),
+  ('CAD', 'Canadian dollar',      '$',       2),
+  ('JPY', 'Japanese yen',         E'¥', 0)
+on conflict (code) do nothing;