ekwo-os 0.4.1

package/dist/assets/migrations/20260917200000_what_moved_after_it_went.sql

@@ -0,0 +1,227 @@
+-- Ekwo OS — what moved after it went.
+--
+-- A declaration leaves, and the period it covers stays open. That is not a
+-- defect: a supplier invoice arrives late, an accountant adjusts an entry, a
+-- correction lands. Every one of those is legitimate, and refusing them would
+-- be refusing bookkeeping. **What is not legitimate is that nobody is told.**
+--
+-- D1 froze the figures and gave `filing_drift()` — box by box, what the ledger
+-- says now against what was sent. This file adds the two things that were
+-- missing around it:
+--
+--   filings_touched_since()  which declarations the ledger disturbed after
+--                            they went, how many entries, and how many of
+--                            their figures moved
+--   lock_filed_period()      a company that wants the period shut says so
+--                            once, after the books for it are clear
+--
+-- and it makes the corrective settle **the difference**, which is the part D4
+-- left named and undone.
+--
+-- On the lock: the database does not propose anything, it answers. The
+-- proposal belongs to whatever is at the keyboard — the CLI, an agent, a
+-- person — and what the schema owes it is a way of saying yes that cannot be
+-- got wrong. So the lock is its own function, it moves forward only, and it
+-- refuses while the period still has books to clear. A company that never
+-- calls it keeps an open period and a reading that says what fell into it.
+--
+-- What is deliberately not here: **what a country does with a correction.**
+-- Some want a full replacement return, some an adjustment carried on the next
+-- period, most with a threshold below which nothing is filed at all. That is
+-- pack data, nobody has read the texts yet, and a mechanism invented now would
+-- be one country's habit given to five others. `supersede_filing()` does the
+-- one thing that is true everywhere: what was sent stays sent, and the new
+-- declaration points at it.
+
+-- ---------------------------------------------------------------------------
+-- filing_tax_movements, net of what an earlier settlement already carried
+--
+-- A corrective covers the same period as the declaration it replaces, and that
+-- period's tax accounts were already cleared once. Left as it was, this would
+-- hand `settle_filing()` the whole period again and book the debt twice.
+--
+-- So the movements of the window are netted against the settlement entries of
+-- the declarations that came before it on the same period — restricted to the
+-- accounts the window itself moved, which is what leaves out their
+-- counterpart line on the debt account. What comes back is exactly what has
+-- not been settled yet: nothing at all when nothing moved, and the difference
+-- when something did.
+-- ---------------------------------------------------------------------------
+
+create or replace function filing_tax_movements(p_filing_id uuid)
+returns table (account_id uuid, balance numeric)
+language sql
+stable
+security invoker
+as $$
+  with f as (
+    select * from tax_filings where id = p_filing_id
+  ),
+  moved as (
+    select l.account_id, sum(l.balance) as balance
+      from f
+      join entry_lines l on l.company_id = f.company_id
+      join entries e     on e.id = l.entry_id
+     where e.state = 'posted'
+       and l.tax_line
+       and coalesce(l.tax_point_date, e.entry_date) between f.period_start and f.period_end
+     group by l.account_id
+  ),
+  already as (
+    select l.account_id, sum(l.balance) as balance
+      from f
+      join tax_filings p
+        on p.company_id = f.company_id
+       and p.report_code = f.report_code
+       and p.period_start = f.period_start
+       and p.period_end = f.period_end
+       and p.id <> f.id
+       and p.settlement_entry_id is not null
+      join entry_lines l on l.entry_id = p.settlement_entry_id
+      join moved m       on m.account_id = l.account_id
+     group by l.account_id
+  )
+  select m.account_id,
+         round_amount(m.balance + coalesce(a.balance, 0), rounding_of(f.company_id))
+    from f, moved m
+    left join already a on a.account_id = m.account_id
+   where round_amount(m.balance + coalesce(a.balance, 0), rounding_of(f.company_id)) <> 0;
+$$;
+
+comment on function filing_tax_movements(uuid) is
+  'The tax accounts a declared period moved and by how much, on the same window and the same tax-point rule the return read, net of what an earlier settlement of the same period already carried. What settle_filing() clears — the whole period the first time, the difference on a corrective — and what anybody can read before it does.';
+
+revoke execute on function filing_tax_movements(uuid) from public, anon;
+grant execute on function filing_tax_movements(uuid) to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- filings_touched_since
+--
+-- The reading the whole freeze was for. A declaration is listed when the
+-- ledger moved inside its period **after** it was filed — not when the figures
+-- happen to differ, which is `filing_drift()`'s question, because an entry
+-- that nets to nothing in every box is still an entry somebody posted into a
+-- period that had gone.
+--
+-- What counts as moving it is a line that names a box, which is the same test
+-- the tax lock uses to decide what it protects. Two readings of "an entry
+-- that concerns the declaration" would eventually disagree, and a payroll
+-- entry landing in a declared quarter is not news. It also leaves out the
+-- settlement of the declaration itself, which is posted at the end of the
+-- period and after the filing, and is the opposite of a disturbance.
+--
+-- Read-only, and it names nothing to do: whether a change is a corrective to
+-- file, an entry in the wrong period, or a legitimate movement that changes no
+-- figure, is a judgement, and the database's job is to stop it being invisible.
+-- ---------------------------------------------------------------------------
+
+create or replace function filings_touched_since(
+  p_company_id uuid,
+  p_from       date default null,
+  p_to         date default null
+)
+returns table (
+  filing_id     uuid,
+  report_code   text,
+  period_start  date,
+  period_end    date,
+  state         tax_filing_state,
+  filed_at      timestamptz,
+  entries       integer,
+  last_entry_at timestamptz,
+  boxes_moved   integer
+)
+language sql
+stable
+security invoker
+as $$
+  select f.id, f.report_code, f.period_start, f.period_end, f.state, f.filed_at,
+         t.entries::integer, t.last_entry_at,
+         (select count(*) from filing_drift(f.id))::integer
+    from tax_filings f
+    cross join lateral (
+      select count(distinct e.id) as entries, max(e.posted_at) as last_entry_at
+        from entry_lines l
+        join entries e on e.id = l.entry_id
+       where l.company_id = f.company_id
+         and e.state = 'posted'
+         and e.posted_at > f.filed_at
+         and l.declaration_box is not null
+         and coalesce(l.tax_point_date, e.entry_date) between f.period_start and f.period_end
+    ) t
+   where f.company_id = p_company_id
+     and f.filed_at is not null
+     and f.state <> 'superseded'
+     and (p_from is null or f.period_end >= p_from)
+     and (p_to is null or f.period_start <= p_to)
+     and t.entries > 0
+   order by f.period_start, f.report_code;
+$$;
+
+comment on function filings_touched_since(uuid, date, date) is
+  'Declarations that have gone and whose period the ledger moved afterwards: how many entries carrying a declaration box landed in it, when the last one did, and how many of the filed figures now disagree. An entry that changes no figure is still listed — it was posted into a period that had been declared, and that is the fact being reported.';
+
+revoke execute on function filings_touched_since(uuid, date, date) from public, anon;
+grant execute on function filings_touched_since(uuid, date, date) to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- lock_filed_period
+--
+-- The other half of "signalled, not refused": a company that does want the
+-- period shut says so, once, and the schema makes saying it safe.
+--
+-- It is a function of its own and not a flag on `file_filing()`, and the test
+-- is what settled that. The tax lock is checked by `post_entry()` for every
+-- entry it posts, whatever the entry names — so locking at the moment of
+-- filing locks the declaration's own settlement out of its period, and the
+-- books can never be cleared. The order that works is the order the work
+-- actually has: file, hear back, settle, then shut.
+--
+-- So this refuses to shut a period whose settlement is still possible and not
+-- done, and says which. It moves the lock forward only: a company filing an
+-- old period late did not ask to reopen everything it had already closed.
+-- ---------------------------------------------------------------------------
+
+create or replace function lock_filed_period(p_filing_id uuid)
+returns date
+language plpgsql
+volatile
+security invoker
+as $$
+declare
+  v_filing tax_filings;
+  v_lock   date;
+begin
+  select * into v_filing from tax_filings f where f.id = p_filing_id;
+  if not found then
+    raise exception 'not_found: filing %', p_filing_id using errcode = 'no_data_found';
+  end if;
+  if v_filing.state in ('draft', 'ready') then
+    raise exception 'filing_not_sent: a period is shut behind a declaration that has gone, and this one is %',
+      v_filing.state;
+  end if;
+  if v_filing.state = 'superseded' then
+    raise exception 'filing_superseded: % was replaced, and it is the declaration that replaced it that shuts the period',
+      p_filing_id;
+  end if;
+
+  if v_filing.settlement_entry_id is null
+     and exists (select 1 from filing_tax_movements(p_filing_id)) then
+    raise exception 'settle_first: this period still has tax accounts to clear, and the lock would refuse the entry that clears them';
+  end if;
+
+  update companies
+     set tax_lock_date = v_filing.period_end
+   where id = v_filing.company_id
+     and (tax_lock_date is null or tax_lock_date < v_filing.period_end);
+
+  select c.tax_lock_date into v_lock from companies c where c.id = v_filing.company_id;
+  return v_lock;
+end;
+$$;
+
+comment on function lock_filed_period(uuid) is
+  'Carries the tax lock to the end of the period a declaration covers, so nothing more falls into it. Forward only, refused on a declaration that has not gone, and refused while the period still has tax accounts to clear — because the lock would then refuse the very entry that clears them. Returns the lock date the company ends up with. Nobody is obliged to call it: a period left open is a period filings_touched_since() reports on.';
+
+revoke execute on function lock_filed_period(uuid) from public, anon;
+grant execute on function lock_filed_period(uuid) to authenticated, service_role;

package/dist/assets/migrations/20260918090000_a_form_names_its_file.sql

@@ -0,0 +1,27 @@
+-- Ekwo OS — a form names the file it is deposited as.
+--
+-- Seven bricks write legal files today and not one of them writes a periodic
+-- VAT return: `intra-consignment`, `des`, `vd` and `ecdf` carry recapitulative
+-- statements, `xbrl-cbso` the annual accounts, `fec` and `factur-x` are
+-- neither. The declaration a company actually files every month — the one D1
+-- freezes and D4 settles — existed here as figures and never as a file.
+--
+-- `@ekwo-ai/vat-consignment` is the first, for the XML Intervat takes. This
+-- column is what says a form has one, and it is a **name of a format** and not
+-- of a country: the day two countries deposit the same shape of file, they
+-- name the same brick, and the day one country changes form it names another.
+--
+-- Null is the ordinary answer, for now and on purpose. A form nobody can write
+-- is still a form a company files by hand on a portal, and a column that had
+-- to be filled would be filled with something invented.
+--
+-- What is not here: **the guard that refuses a pack naming a format nobody can
+-- write.** It belongs with the one owed to `bank_statement_formats` and
+-- `payment_formats`, which are declared with no reader for the same reason,
+-- and it is one guard over the three of them rather than three.
+
+alter table tax_report_templates
+  add column if not exists file_format text;
+
+comment on column tax_report_templates.file_format is
+  'The file this form is deposited as, by the name of the brick that writes it — vat-consignment for the Belgian XML Intervat takes. Named after the format and never after the country. Null where no brick writes the form, which is most of them: filing by hand on a portal is how it is done until one exists.';

package/dist/assets/migrations/20260918110000_a_deposit_and_what_came_back.sql

@@ -0,0 +1,286 @@
+-- Ekwo OS — a deposit, and what came back.
+--
+-- Filing was one act with one date: `filed_at`, `reference`, and a state that
+-- went `filed` then `accepted` or `rejected`. That is the happy path and it is
+-- the only one the schema could describe. A declaration is refused for a
+-- malformed file, for a certificate that expired mid-session, for a figure the
+-- administration disputes — and then it is **sent again**, which the schema had
+-- no way of saying: `file_filing()` refused everything that was not a draft, so
+-- a rejected declaration was a dead end whose only exit was a corrective. A
+-- corrective replaces a declaration the administration **accepted**. One it
+-- never received has nothing to correct.
+--
+-- So a deposit becomes an object of its own:
+--
+--   tax_filing_deposits   one row per send, with what came back
+--   file_filing()         records a send, and accepts a rejected declaration
+--   reopen_filing()       a rejected declaration goes back to draft to be redone
+--
+-- **Why this is in the open core.** Sending the file is the operated side —
+-- credentials, a certificate, a portal session, somebody answerable when a
+-- return is late — and it stays in `ee/`, on the same line as the bank. What
+-- comes back does not: the deposit number, the acknowledgement, the words the
+-- administration used, and the file that was sent are the company's proof that
+-- it filed. A company that stops paying for the transmission keeps every one of
+-- them, in its own database, under the same policies as the rest of its books.
+-- That is the whole argument for installing this.
+--
+-- The channel is two words and not a list of providers. `portal` is a person
+-- uploading the file themselves, which is complete and free and is how most
+-- installations will do it; `service` is a transmission held by somebody, whose
+-- name is recorded as text. A closed list of providers here would be the
+-- coupling this project refuses — one interface, one provider at a time, and
+-- the core never knows which.
+
+create type filing_channel as enum ('portal', 'service');
+
+comment on type filing_channel is
+  'How a declaration was sent: portal — a person uploaded it themselves — or service, a transmission somebody operates. Two words, because the core describes the act and never the provider.';
+
+create table tax_filing_deposits (
+  id           uuid primary key default gen_random_uuid(),
+  filing_id    uuid not null references tax_filings(id) on delete cascade,
+  -- 1, 2, 3: a rejected declaration is sent again, and each send is a row.
+  sequence     integer not null,
+  channel      filing_channel not null default 'portal',
+  -- The name of the service, where one was used. Free text on purpose: the
+  -- core records what was used and never holds a list of what may be.
+  service      text,
+  sent_at      timestamptz not null default now(),
+  sent_by      uuid,
+  -- What the administration gave back for **this** send.
+  reference    text,
+  outcome      tax_filing_state,
+  outcome_at   timestamptz,
+  -- Its own words. A refusal summarised is a refusal half-read, and the
+  -- sentence is what a person needs to know what to change.
+  message      text,
+  -- The two files of a deposit, where they were kept: what was sent, and the
+  -- receipt. Both are rows of `attachments` on this declaration; naming them
+  -- here is what tells them apart.
+  sent_file_id        uuid references attachments(id) on delete set null,
+  acknowledgement_id  uuid references attachments(id) on delete set null,
+  created_at   timestamptz not null default now(),
+  unique (filing_id, sequence),
+  constraint tax_filing_deposits_outcome check (
+    outcome is null or outcome in ('accepted', 'rejected', 'paid')
+  ),
+  constraint tax_filing_deposits_outcome_has_a_date check (
+    (outcome is null) = (outcome_at is null)
+  )
+);
+
+comment on table tax_filing_deposits is
+  'One row per send of a declaration, with what came back: the deposit number, the outcome, the administration''s own words, and the two files — what was sent and the receipt. A rejected declaration is sent again, so a declaration has as many deposits as it took.';
+comment on column tax_filing_deposits.service is
+  'The name of the transmission service, where one was used. Free text: the core records what was used and holds no list of what may be, which is what keeps it uncoupled from any provider.';
+comment on column tax_filing_deposits.message is
+  'What the administration answered, in its own words. Not summarised: a refusal is read to know what to change.';
+comment on column tax_filing_deposits.sent_file_id is
+  'The file that was sent, kept as an attachment of this declaration. Keeping it is what makes reopening a rejected declaration lossless — the core makes it possible and cannot impose it.';
+
+create index tax_filing_deposits_filing_idx on tax_filing_deposits (filing_id, sequence desc);
+-- The two files, indexed like every other foreign key of this schema: a
+-- deleted attachment has to find the deposits that point at it without a scan.
+create index tax_filing_deposits_sent_file_idx on tax_filing_deposits (sent_file_id);
+create index tax_filing_deposits_acknowledgement_idx on tax_filing_deposits (acknowledgement_id);
+
+alter table tax_filing_deposits enable row level security;
+
+create policy tax_filing_deposits_select on tax_filing_deposits
+  for select using (exists (
+    select 1 from tax_filings f
+    where f.id = tax_filing_deposits.filing_id
+      and has_capability(f.company_id, 'filings.read')));
+create policy tax_filing_deposits_write on tax_filing_deposits
+  for all using (exists (
+    select 1 from tax_filings f
+    where f.id = tax_filing_deposits.filing_id
+      and has_capability(f.company_id, 'filings.write')))
+  with check (exists (
+    select 1 from tax_filings f
+    where f.id = tax_filing_deposits.filing_id
+      and has_capability(f.company_id, 'filings.write')));
+
+comment on policy tax_filing_deposits_select on tax_filing_deposits is
+  'filings.read: what was sent and what came back is proof of filing, and it is read by whoever reads the declarations.';
+
+grant select, insert, update, delete on table tax_filing_deposits to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- file_filing, which now records the send
+--
+-- Replaces the three-argument function rather than sitting beside it: two
+-- overloads with defaults would make the call everybody writes ambiguous.
+-- ---------------------------------------------------------------------------
+
+drop function if exists file_filing(uuid, text, timestamptz);
+
+create or replace function file_filing(
+  p_filing_id uuid,
+  p_reference text default null,
+  p_filed_at  timestamptz default null,
+  p_channel   filing_channel default 'portal',
+  p_service   text default null
+)
+returns tax_filings
+language plpgsql
+volatile
+security invoker
+as $$
+declare
+  v_filing tax_filings;
+  v_at     timestamptz;
+  v_next   integer;
+begin
+  select * into v_filing from tax_filings f where f.id = p_filing_id;
+  if not found then
+    raise exception 'not_found: filing %', p_filing_id using errcode = 'no_data_found';
+  end if;
+
+  -- Rejected is a state a declaration is sent again from. It was never
+  -- received, so there is nothing to correct and no corrective to open.
+  if v_filing.state not in ('draft', 'ready', 'rejected') then
+    raise exception 'filing_already_%: this declaration has already gone', v_filing.state;
+  end if;
+
+  if v_filing.prepared_at is null then
+    raise exception 'filing_not_prepared: compute the figures before filing them';
+  end if;
+
+  v_at := coalesce(p_filed_at, now());
+
+  select coalesce(max(d.sequence), 0) + 1 into v_next
+    from tax_filing_deposits d where d.filing_id = p_filing_id;
+
+  insert into tax_filing_deposits (filing_id, sequence, channel, service, sent_at, sent_by, reference)
+  values (p_filing_id, v_next, p_channel, p_service, v_at, auth.uid(), p_reference);
+
+  update tax_filings
+     set state     = 'filed',
+         reference = coalesce(p_reference, reference),
+         filed_at  = v_at,
+         filed_by  = auth.uid()
+   where id = p_filing_id
+  returning * into v_filing;
+
+  return v_filing;
+end;
+$$;
+
+comment on function file_filing(uuid, text, timestamptz, filing_channel, text) is
+  'Records that a declaration has gone, with the reference the administration gave back, and keeps the send as a row of tax_filing_deposits. It asks that the figures were computed, not that there are any: a period where nothing happened is filed nil. A rejected declaration may be sent again — it was never received — and the second send is a second deposit, not a corrective.';
+
+revoke execute on function file_filing(uuid, text, timestamptz, filing_channel, text) from public, anon;
+grant execute on function file_filing(uuid, text, timestamptz, filing_channel, text) to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- record_filing_outcome, which writes on the deposit it answers
+-- ---------------------------------------------------------------------------
+
+drop function if exists record_filing_outcome(uuid, tax_filing_state, text);
+
+create or replace function record_filing_outcome(
+  p_filing_id uuid,
+  p_state     tax_filing_state,
+  p_reference text default null,
+  p_message   text default null
+)
+returns tax_filings
+language plpgsql
+volatile
+security invoker
+as $$
+declare
+  v_filing tax_filings;
+begin
+  select * into v_filing from tax_filings f where f.id = p_filing_id;
+  if not found then
+    raise exception 'not_found: filing %', p_filing_id using errcode = 'no_data_found';
+  end if;
+
+  if p_state not in ('accepted', 'rejected', 'paid') then
+    raise exception 'not_an_outcome: % is not something an administration answers', p_state;
+  end if;
+  if v_filing.state = 'draft' or v_filing.state = 'ready' then
+    raise exception 'filing_not_sent: a declaration that has not gone cannot come back %', p_state;
+  end if;
+  if p_state = 'paid' and v_filing.state <> 'accepted' then
+    raise exception 'filing_not_accepted: paying follows acceptance, and this one is %', v_filing.state;
+  end if;
+
+  -- On the last send, because that is the one being answered.
+  update tax_filing_deposits d
+     set outcome    = p_state,
+         outcome_at = now(),
+         reference  = coalesce(p_reference, d.reference),
+         message    = coalesce(p_message, d.message)
+   where d.filing_id = p_filing_id
+     and d.sequence = (select max(x.sequence) from tax_filing_deposits x where x.filing_id = p_filing_id);
+
+  update tax_filings
+     set state     = p_state,
+         reference = coalesce(p_reference, reference)
+   where id = p_filing_id
+  returning * into v_filing;
+  return v_filing;
+end;
+$$;
+
+comment on function record_filing_outcome(uuid, tax_filing_state, text, text) is
+  'What came back: accepted, rejected, or paid, written on the declaration and on the send it answers — with the administration''s own words where it gave any. Paying follows acceptance, and a declaration that never went cannot come back at all.';
+
+revoke execute on function record_filing_outcome(uuid, tax_filing_state, text, text) from public, anon;
+grant execute on function record_filing_outcome(uuid, tax_filing_state, text, text) to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- reopen_filing
+--
+-- A rejection on the substance is not answered by sending the same file again:
+-- the figures have to be worked out afresh, and `prepare_filing()` refuses
+-- anything that has left draft. So this is the door back, and it opens for one
+-- state only.
+--
+-- It is safe because of the table above: what was sent is a deposit, with its
+-- reference, its answer and — where somebody kept it — the file itself. The
+-- core cannot force an installation to archive that file; it can make keeping
+-- it the thing that makes this lossless, and say so.
+-- ---------------------------------------------------------------------------
+
+create or replace function reopen_filing(p_filing_id uuid)
+returns tax_filings
+language plpgsql
+volatile
+security invoker
+as $$
+declare
+  v_filing tax_filings;
+begin
+  select * into v_filing from tax_filings f where f.id = p_filing_id;
+  if not found then
+    raise exception 'not_found: filing %', p_filing_id using errcode = 'no_data_found';
+  end if;
+  if v_filing.state <> 'rejected' then
+    raise exception 'filing_not_rejected: a % declaration is not redone, it is superseded by a corrective',
+      v_filing.state;
+  end if;
+
+  -- The declaration goes back to being prepared. `filed_at` empties with it —
+  -- the schema's own rule that a draft carries no filing date — and nothing is
+  -- lost, because the send that was refused is a row of tax_filing_deposits.
+  update tax_filings
+     set state     = 'draft',
+         filed_at  = null,
+         filed_by  = null,
+         reference = null
+   where id = p_filing_id
+  returning * into v_filing;
+  return v_filing;
+end;
+$$;
+
+comment on function reopen_filing(uuid) is
+  'Takes a rejected declaration back to draft so its figures can be worked out again. Only a rejected one: a declaration the administration accepted is replaced by a corrective, never rewritten. What was sent stays in tax_filing_deposits.';
+
+revoke execute on function reopen_filing(uuid) from public, anon;
+grant execute on function reopen_filing(uuid) to authenticated, service_role;

package/dist/assets/migrations/20260918113741_a_fourth_preset_is_named.sql

@@ -0,0 +1,9 @@
+-- Ekwo OS — a fourth preset is named, and nothing else happens here.
+--
+-- `member_role` gains `client`: the person whose company this is, inside an
+-- installation that belongs to whoever keeps their books. What the preset
+-- holds is the next migration — a new enum value cannot be used in the
+-- transaction that adds it, which is the reason `instance_admin` was added in
+-- a file of its own on the first day, and the reason this one is.
+
+alter type member_role add value if not exists 'client';

package/dist/assets/migrations/20260918113807_a_client_reads_and_hands_over.sql

@@ -0,0 +1,96 @@
+-- Ekwo OS — a client reads, and hands over a piece. It writes nothing.
+--
+-- Several companies inside one installation is the normal case: a firm and
+-- the companies it keeps the books of. The person who runs one of those
+-- companies had no preset to sit on. `viewer` reads and cannot hand anything
+-- over; `accountant` hands over and can also draft an invoice, which is the
+-- one thing the firm is there to do.
+--
+-- **What was missing was not a preset.** Filing a piece is an insert into
+-- `attachments`, and the only policy that admits one tests `documents.write`
+-- — the capability that also creates and changes draft documents and their
+-- lines. There was no way to say "may give us the receipt" without saying
+-- "may write the purchase invoice". So this migration adds one capability,
+-- `documents.deposit`, and the narrowest policy that can carry it:
+--
+--   * INSERT only. There is no update and no delete behind it: a piece that
+--     was handed over is the firm's to file, to re-point at the document it
+--     becomes, or to discard, and all three are `documents.write`.
+--   * On the company itself — `entity_type = 'company'`, `entity_id` the
+--     company. `attachments` is polymorphic, and a capability that attached
+--     to any row would let its holder pin a file of their own making on a
+--     filed declaration, beside the receipt the administration sent. The
+--     company row is the one thing a depositor is certain to be able to name,
+--     and a file sitting on it is what an in-tray is.
+--   * Signed. `uploaded_by` must be the caller, and the column now defaults
+--     to it, so the firm reads who handed over what without trusting the
+--     application to have said so.
+--
+-- **Reading back what one handed over.** `insert … returning` is checked
+-- against the SELECT policies, and the one on `attachments` tests
+-- `documents.read`. A client holds it; a member or a key granted
+-- `documents.deposit` alone — a scanner in a hallway — does not, and would
+-- have its insert refused for a row it is allowed to write. A second SELECT
+-- policy lets a depositor read their own deposits. It reads no table, so it
+-- cannot recurse.
+--
+-- **The preset.** `client` holds what `viewer` holds, read from
+-- `role_capabilities` rather than listed again, plus `documents.deposit`. The
+-- ledger is included on purpose: the books are the client's, the firm is the
+-- guest, and a preset that hid a company's own entries from the person
+-- answerable for them would be describing a different relationship. A firm
+-- that wants less revokes it, per member — that is what
+-- `capabilities_revoked` is for.
+--
+-- There is no approval in this preset because there is no act of approval in
+-- the schema that is not also a write: `tax_filings.state = 'ready'` is
+-- reached through `filings.write`. `docs/decisions.md` says so under this
+-- date.
+
+insert into capabilities (code, area, description) values
+  ('documents.deposit', 'documents',
+   'Hand a file over to the company: an attachment on the company itself, signed by whoever dropped it. Insert only — filing it, moving it and deleting it are documents.write.')
+on conflict (code) do nothing;
+
+-- Whoever may write a document may already file an attachment anywhere, so
+-- the two working presets hold the narrower act as well: an interface asks
+-- one question — may this person drop a file here — and gets one answer.
+insert into role_capabilities (role, capability) values
+  ('owner'::member_role,      'documents.deposit'),
+  ('accountant'::member_role, 'documents.deposit'),
+  ('client'::member_role,     'documents.deposit')
+on conflict do nothing;
+
+insert into role_capabilities (role, capability)
+select 'client'::member_role, rc.capability
+  from role_capabilities rc
+ where rc.role = 'viewer'
+on conflict do nothing;
+
+alter table attachments alter column uploaded_by set default auth.uid();
+
+comment on column attachments.uploaded_by is
+  'Who filed it. Defaults to the caller; a deposit is refused unless it says the caller.';
+
+create policy attachments_deposit on attachments
+  for insert with check (
+    has_capability(company_id, 'documents.deposit')
+    and entity_type = 'company'
+    and entity_id = company_id
+    and uploaded_by is not distinct from auth.uid()
+  );
+
+comment on policy attachments_deposit on attachments is
+  'A piece handed over: on the company itself, signed by the caller, insert only. Everything else on this table is documents.write.';
+
+create policy attachments_select_own_deposit on attachments
+  for select using (
+    uploaded_by = auth.uid()
+    and has_capability(company_id, 'documents.deposit')
+  );
+
+comment on policy attachments_select_own_deposit on attachments is
+  'A depositor reads back what they handed over, so that `insert … returning` answers for somebody who holds documents.deposit and not documents.read.';
+
+comment on table company_members is
+  'Who may read or write a company. A role is a preset resolved through `role_capabilities`: `owner` administers, `accountant` books, `viewer` reads, `client` reads and hands pieces over.';