feat(company): ideell förening as a third legal form, behind a flag (#2072 step 1) (#2423)

* feat(company): ideell förening as a third legal form, behind a flag (#2072 step 1)

Why the problem occurred: the legal form was modelled as a binary flag in
~300 files. `EntityType` was a two-member union, but nothing dispatched on it
exhaustively: 28 sites defaulted `?? 'enskild_firma'` (invoice, categorize,
match, stripe, invoice-inbox) or `?? 'aktiebolag'` (year-end, bokslut,
MCP), and every form-dependent choice was an `=== 'aktiebolag' ? A : B`
ternary. Widening the union compiled everywhere and changed nothing, so a
förening would have booked as an enskild firma in the app and as an
aktiebolag in bokslut and MCP, with no error anywhere. The lookup refused
föreningar at the door (mapEntityType returned null), which is what the
tester hit.

What was removed or simplified: the silent defaults. One module,
lib/company/entity-type.ts, now holds the list (ENTITY_TYPES), the parser
(never defaults), the resolver (settings hint, then companies.entity_type,
then throw) and `byEntityType`, whose Record arms make the compiler refuse
the next widening until each site has an answer. The form-dependent facts
(closing account, owner settlement account, calendar-year lock, default
method, K1/K2 label, personnummer vs 16-prefix) live there once instead of
in the ternaries. On the SQL side supported_entity_types() replaces four
copies of the literal list in the create RPCs.

Why this shape and not the proposed one: the tracker asked for the enum
widening plus a chart; that alone was the dangerous version (compiles, books
wrong). Bundling stiftelse was considered and dropped: identical plumbing but
no chart block. Creation sits behind NEXT_PUBLIC_IDEELL_FORENING_ENABLED so
the CHECK, RPCs and seed can ship now and the first partner is switched on
without a migration; the flag goes when Phase 2 (packs, INK3, årsbokslut,
Swish) lands on the tracker.

Domain choices (DECISIONS.md 2026-09-08, verify with an accountant before
Phase 2): result closes to 2069 with 2068 as prior-year carry; no owner
accounts, member settlement on 2890; accrual default; brutet räkenskapsår
allowed; K1 label for the 5 000 kr accrual threshold (BFNAR 2010:1); org
number gets the 16 prefix.

Migration 20260908110835 widens the three CHECK constraints, adds
supported_entity_types(), re-creates the three create RPCs with the widened
guard and adds the förening block to seed_chart_of_accounts. Applied to
staging and covered by ideell-forening-entity-type.pg.test.ts.

Part of #2072

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PdGafpUA7jVV1oYjkwfQCh

* fix(company): close the förening paths the skeptic refuted (#2072)

Five refutations from the /skeptic pass on 7a05c54d2, each fixed at the
shared definition rather than the reported site:

1. Privately paid supplier invoices and the utlägg dialog resolved the owner
   account in lib/expenses/payer.ts with its own AB/EF ternary, so a förening
   member's invoice was built on 2893 and then refused by the expense-claim
   service (which already said 2890), burning an ankomstnummer. The helper now
   uses ownerSettlementAccount.
2. Booking templates substitute their `_ab` accounts only for an aktiebolag;
   the `private_expense` template kept its base 2013 for a förening. Template
   accounts now resolve through templateAccountForForm: EF base, AB override,
   förening base with owner accounts translated to 2890 (booking-templates.ts
   and proposal-lines.ts share it).
3. A VAT-registered förening with helårsmoms got no momsdeklaration deadline:
   the annual VAT rule bailed on anything but AB/EF. A förening is a juridisk
   person and follows the räkenskapsår schedule (SFL 26 kap 33 §), so the rule
   now keys on fiscalYearLockedToCalendar instead of the two literals; same in
   the MCP VAT report.
4. 2069 would have accumulated across years: the year-open omföring was
   AB-only with 2099/2098 hard-coded. planResultAppropriation now takes the
   pair from resultClosingAccounts (AB 2099 -> 2098, förening 2069 -> 2068)
   and skips forms with no carry (EF).
5. With the flag off, a registry lookup that returned "Ideell förening" was
   prefilled into the onboarding journey, the form picker was skipped and the
   create step answered "Ogiltig företagsform" with no way back. The
   journey, the BankID picker, the onboarding page and the MCP lookup now use
   mapSetupEntityType, which maps only creatable forms, so a flagged-off form
   falls through to the picker as before.

Also: form picker keeps its AB-first order; tests for each fix.

Part of #2072

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PdGafpUA7jVV1oYjkwfQCh

* chore(migrations): move ideell förening migration after main's latest version (20260908143051)

Two migrations landed on main after the branch forked; a lower version
would be skipped by the merge-time apply. Staging history row renamed to
match.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PdGafpUA7jVV1oYjkwfQCh

* chore(skills): regenerate accounted-api reference for the widened entity_type enum

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PdGafpUA7jVV1oYjkwfQCh

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

app/api/agent/categorize/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server'
+import { parseEntityType } from '@/lib/company/entity-type'
 import { z } from 'zod'
 import { withRouteContext } from '@/lib/api/with-route-context'
 import { checkAgentRateLimit, agentRateLimitResponseBody } from '@/lib/rate-limits/agent'
@@ -119,7 +120,7 @@ export const POST = withRouteContext(
         },
         underlag,
         candidates,
-        entityType: ((company?.entity_type as EntityType | undefined) ?? 'enskild_firma'),
+        entityType: parseEntityType(company?.entity_type),
         vatRegistered: settings?.vat_registered ?? false,
         samples: parsed.data.samples,
       })

app/api/bookkeeping/mapping-rules/evaluate/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { withRouteContext } from '@/lib/api/with-route-context'
 import { evaluateMappingRules } from '@/lib/bookkeeping/mapping-engine'
 import { validateBody } from '@/lib/api/validate'
@@ -39,7 +40,12 @@ export const POST = withRouteContext('mapping_rules.evaluate', async (request, c
   }
 
   try {
-    const result = await evaluateMappingRules(supabase, companyId, transaction)
+    const result = await evaluateMappingRules(
+      supabase,
+      companyId,
+      transaction,
+      await resolveCompanyEntityType(supabase, companyId),
+    )
     return NextResponse.json({ data: result })
   } catch (err) {
     return NextResponse.json(

app/api/invoices/[id]/book/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { withRouteContext } from '@/lib/api/with-route-context'
 import { errorResponse, errorResponseFromCode } from '@/lib/errors/get-structured-error'
 import {
@@ -61,7 +62,11 @@ export const POST = withRouteContext(
     if ((settings.accounting_method || 'accrual') !== 'accrual') {
       return errorResponseFromCode('INVOICE_BOOK_CASH_METHOD', log, { requestId })
     }
-    const entityType = ((settings as Partial<CompanySettings>).entity_type as EntityType) || 'enskild_firma'
+    const entityType = await resolveCompanyEntityType(
+      supabase,
+      companyId,
+      (settings as Partial<CompanySettings>).entity_type,
+    )
 
     const result = await bookInvoiceDeferred({
       supabase,

app/api/invoices/[id]/mark-paid/__tests__/route.test.ts

@@ -371,6 +371,8 @@ describe('POST /api/invoices/[id]/mark-paid', () => {
 
     // Fetch invoice
     enqueue({ data: invoice, error: null })
+    // No customer: the duplicate guard skips straight to the settings read
+    enqueue({ data: { accounting_method: 'accrual', entity_type: 'enskild_firma' }, error: null })
 
     const unbalancedLines = [
       { account_number: '1920', debit_amount: 12500, credit_amount: 0 },
@@ -627,6 +629,7 @@ describe('POST /api/invoices/[id]/mark-paid', () => {
     const invoice = makeInvoice({ id: 'inv-1', status: 'sent', total: 12500 })
 
     enqueue({ data: invoice, error: null })
+    enqueue({ data: { accounting_method: 'accrual', entity_type: 'enskild_firma' }, error: null })
 
     const overpayLines = [
       { account_number: '1930', debit_amount: 15000, credit_amount: 0 },
@@ -722,6 +725,7 @@ describe('POST /api/invoices/[id]/mark-paid', () => {
     })
 
     enqueue({ data: invoice, error: null })
+    enqueue({ data: { accounting_method: 'accrual', entity_type: 'enskild_firma' }, error: null })
 
     const request = createMockRequest('/api/invoices/inv-1/mark-paid', {
       method: 'POST',
@@ -752,6 +756,7 @@ describe('POST /api/invoices/[id]/mark-paid', () => {
     })
 
     enqueue({ data: invoice, error: null })
+    enqueue({ data: { accounting_method: 'accrual', entity_type: 'enskild_firma' }, error: null })
 
     // Bank 90 000 exceeds the 86 800 customer share even after the 1513
     // exclusion: the overpayment guard must still fire.

app/api/invoices/[id]/mark-paid/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { MarkInvoicePaidSchema } from '@/lib/api/schemas'
 import { ensureInitialized } from '@/lib/init'
 import { withRouteContext } from '@/lib/api/with-route-context'
@@ -238,7 +239,7 @@ export const POST = withRouteContext(
       .single()
 
     const accountingMethod = settings?.accounting_method || 'accrual'
-    const entityType = (settings?.entity_type as EntityType) || 'enskild_firma'
+    const entityType = await resolveCompanyEntityType(supabase, companyId, settings?.entity_type)
 
     // paymentAmountInInvoiceCurrency was resolved above, before the
     // duplicate-payment guard, so the guard comparison and the ledger math run

app/api/invoices/[id]/mark-sent/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { ensureInvoiceNumber } from '@/lib/invoices/ensure-invoice-number'
 import {
   creditNoteNeedsJournalEntry,
@@ -156,7 +157,7 @@ export const POST = withRouteContext<{ params: Promise<{ id: string }> }>(
   }
 
   const accountingMethod = (settings.accounting_method || 'accrual') as AccountingMethod
-  const entityType = (settings.entity_type as EntityType) || 'enskild_firma'
+  const entityType = await resolveCompanyEntityType(supabase, companyId, settings.entity_type)
 
   const { data: original } = await supabase
     .from('invoices')

app/api/invoices/[id]/send/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { eventBus } from '@/lib/events'
 import { ensureInitialized } from '@/lib/init'
 import { renderToBuffer } from '@react-pdf/renderer'
@@ -449,7 +450,7 @@ export const POST = withRouteContext(
         userId: user.id,
         creditNote: invoice as CreditNote,
         originalInvoice,
-        entityType: ((company as CompanySettings).entity_type as EntityType) || 'enskild_firma',
+        entityType: await resolveCompanyEntityType(supabase, companyId!, (company as CompanySettings).entity_type),
         accountingMethod: ((company as Record<string, unknown>).accounting_method || 'accrual') as AccountingMethod,
         log: opLog,
       })

app/api/invoices/bulk-book/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { ensureInitialized } from '@/lib/init'
 import { withRouteContext } from '@/lib/api/with-route-context'
 import { validateBody } from '@/lib/api/validate'
@@ -75,8 +76,11 @@ export const POST = withRouteContext(
     if ((settings.accounting_method || 'accrual') !== 'accrual') {
       return errorResponseFromCode('INVOICE_BOOK_CASH_METHOD', log, { requestId })
     }
-    const entityType =
-      ((settings as Partial<CompanySettings>).entity_type as EntityType) || 'enskild_firma'
+    const entityType = await resolveCompanyEntityType(
+      supabase,
+      companyId,
+      (settings as Partial<CompanySettings>).entity_type,
+    )
 
     const { data: invoices, error: fetchError } = await supabase
       .from('invoices')

app/api/pending-operations/[id]/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { z } from 'zod'
 import { ensureInitialized } from '@/lib/init'
 import { withRouteContext } from '@/lib/api/with-route-context'
@@ -122,7 +123,7 @@ export const PATCH = withRouteContext<{ params: Promise<{ id: string }> }>(
       .select('entity_type')
       .eq('company_id', companyId)
       .maybeSingle()
-    const entityType = ((settings?.entity_type as EntityType) || 'enskild_firma')
+    const entityType = await resolveCompanyEntityType(supabase, companyId, settings?.entity_type)
 
     const isBusiness = newCategory !== 'private'
 

app/api/supplier-invoices/route.ts

@@ -24,7 +24,8 @@ import {
 } from '@/lib/currency/supplier-invoice-rate'
 import { roundOre } from '@/lib/money'
 import { linkToJournalEntry } from '@/lib/core/documents/document-service'
-import type { Currency, SupplierInvoice, SupplierInvoiceItem } from '@/types'
+import type { Currency, EntityType, SupplierInvoice, SupplierInvoiceItem } from '@/types'
+import { parseEntityType } from '@/lib/company/entity-type'
 import { getErrorMessage as getUserErrorMessage } from '@/lib/errors/get-error-message'
 
 ensureInitialized()
@@ -251,7 +252,7 @@ export const POST = withRouteContext(
     // Entity type drives the credit account for privately-paid invoices:
     // AB → 2893 (skuld till aktieägare), EF → 2018 (egen insättning). Loaded
     // up front so we can fail early if the company row is missing.
-    let entityType: 'aktiebolag' | 'enskild_firma' | null = null
+    let entityType: EntityType | null = null
     if (paidPrivately) {
       const { data: company } = await supabase
         .from('companies')
@@ -264,7 +265,7 @@ export const POST = withRouteContext(
           details: { reason: 'company entity_type missing, cannot pick owner account' },
         })
       }
-      entityType = company.entity_type as 'aktiebolag' | 'enskild_firma'
+      entityType = parseEntityType(company.entity_type)
       if (body.employee_id) {
         // Checked before the arrival-number sequence is touched: a claim the
         // service would refuse must not burn an ankomstnummer.

app/api/transactions/[id]/categorize/route.ts

@@ -1,4 +1,5 @@
 import type { SupabaseClient } from '@supabase/supabase-js'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { NextResponse } from 'next/server'
 import { eventBus } from '@/lib/events'
 import { ensureInitialized } from '@/lib/init'
@@ -273,7 +274,7 @@ export const POST = withRouteContext(
       .eq('company_id', companyId)
       .single()
 
-    const entityType: EntityType = (settings?.entity_type as EntityType) || 'enskild_firma'
+    const entityType: EntityType = await resolveCompanyEntityType(supabase, companyId, settings?.entity_type)
     const fiscalYearStartMonth: number = settings?.fiscal_year_start_month ?? 1
 
     let finalCategory: TransactionCategory

app/api/transactions/[id]/match-invoice/preview/route.ts

@@ -20,6 +20,7 @@
  * the lack of any preview was part of the reported bug.
  */
 import { NextResponse } from 'next/server'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { withRouteContext } from '@/lib/api/with-route-context'
 import { errorResponseFromCode } from '@/lib/errors/get-structured-error'
 import { cashPartialBlockReason } from '@/lib/bookkeeping/booking-mode'
@@ -92,7 +93,7 @@ export const GET = withRouteContext(
       .single()
 
     const accountingMethod = settings?.accounting_method || 'accrual'
-    const entityType: EntityType = (settings?.entity_type as EntityType) || 'enskild_firma'
+    const entityType: EntityType = await resolveCompanyEntityType(supabase, companyId, settings?.entity_type)
 
     // Same resolution as the POST handler: debit the cash account this
     // transaction is actually linked to, never a hardcoded 1930, so the

app/api/transactions/[id]/match-invoice/route.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { cashPartialBlockReason } from '@/lib/bookkeeping/booking-mode'
 import { createInvoiceCashEntry } from '@/lib/bookkeeping/invoice-entries'
 import { buildInvoicePaymentClearingLines } from '@/lib/bookkeeping/invoice-payment-lines'
@@ -412,7 +413,7 @@ export const POST = withRouteContext(
       .single()
 
     const accountingMethod = settings?.accounting_method || 'accrual'
-    const entityType = (settings?.entity_type as EntityType) || 'enskild_firma'
+    const entityType = await resolveCompanyEntityType(supabase, companyId, settings?.entity_type)
 
     // Debit the cash account THIS transaction actually belongs to, never a
     // hardcoded 1930: cash_account_id -> cash_accounts.ledger_account is the

app/api/v1/companies/[companyId]/invoices/[id]/mark-sent/route.ts

@@ -39,6 +39,7 @@
  */
 
 import { z } from 'zod'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { ok } from '@/lib/api/v1/response'
 import { dryRunPreview } from '@/lib/api/v1/dry-run'
 import { registerEndpoint, dataEnvelope } from '@/lib/api/v1/registry'
@@ -255,7 +256,7 @@ export const POST = withApiV1<{ params: Promise<{ companyId: string; id: string
       })
     }
     const accountingMethod = companySettings.accounting_method ?? 'accrual'
-    const entityType = (companySettings.entity_type ?? 'enskild_firma') as EntityType
+    const entityType = await resolveCompanyEntityType(ctx.supabase, ctx.companyId!, companySettings.entity_type)
     const isRealInvoice = !typed.document_type || typed.document_type === 'invoice'
     // #967: kontantmetoden and defer_invoice_booking companies mark sent
     // WITHOUT booking (same gate as the dashboard, issue-and-book-invoice.ts).

app/api/v1/companies/[companyId]/invoices/[id]/send/route.ts

@@ -40,6 +40,7 @@
  */
 
 import { z } from 'zod'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { renderToBuffer } from '@react-pdf/renderer'
 import { ok } from '@/lib/api/v1/response'
 import { dryRunPreview } from '@/lib/api/v1/dry-run'
@@ -729,7 +730,7 @@ export const POST = withApiV1<{ params: Promise<{ companyId: string; id: string
           ctx.companyId!,
           ctx.userId,
           renderableInvoice,
-          (settings.entity_type ?? 'enskild_firma') as EntityType,
+          await resolveCompanyEntityType(ctx.supabase, ctx.companyId!, settings.entity_type),
           customer.name,
         )
         if (entry) {

app/api/v1/companies/[companyId]/transactions/[id]/categorize/route.ts

@@ -20,6 +20,7 @@
  * without inserting the journal entry or mutating the transaction.
  */
 import { z } from 'zod'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { ok } from '@/lib/api/v1/response'
 import { dryRunPreview } from '@/lib/api/v1/dry-run'
 import { registerEndpoint, dataEnvelope } from '@/lib/api/v1/registry'
@@ -174,7 +175,7 @@ export const POST = withApiV1<{ params: Promise<{ companyId: string; id: string
       .select('entity_type')
       .eq('company_id', ctx.companyId!)
       .single()
-    const entityType: EntityType = (settings?.entity_type as EntityType) || 'enskild_firma'
+    const entityType: EntityType = await resolveCompanyEntityType(ctx.supabase, ctx.companyId!, settings?.entity_type)
 
     // Resolve final category and mapping result. Mirrors the internal route.
     let finalCategory: TransactionCategory

app/api/v1/companies/[companyId]/transactions/[id]/match-invoice/route.ts

@@ -23,6 +23,7 @@
  * resolved preview before commit. Skip the flag here; document it.
  */
 import { z } from 'zod'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { ok } from '@/lib/api/v1/response'
 import { registerEndpoint, dataEnvelope } from '@/lib/api/v1/registry'
 import { withApiV1 } from '@/lib/api/v1/with-api-v1'
@@ -440,8 +441,7 @@ export const POST = withApiV1<{ params: Promise<{ companyId: string; id: string
       .eq('company_id', ctx.companyId!)
       .single()
     const accountingMethod = settings?.accounting_method || 'accrual'
-    const entityType: EntityType =
-      (settings?.entity_type as EntityType) || 'enskild_firma'
+    const entityType: EntityType = await resolveCompanyEntityType(ctx.supabase, ctx.companyId!, settings?.entity_type)
 
     // Debit the cash account THIS transaction actually belongs to, never a
     // hardcoded 1930: cash_account_id -> cash_accounts.ledger_account is the

app/api/v1/companies/[companyId]/transactions/batch-categorize/route.ts

@@ -10,6 +10,7 @@
  * Idempotent over the whole batch. Dry-runnable.
  */
 import { z } from 'zod'
+import { resolveCompanyEntityType } from '@/lib/company/entity-type'
 import { ok } from '@/lib/api/v1/response'
 import { dryRunPreview } from '@/lib/api/v1/dry-run'
 import { registerEndpoint, dataEnvelope } from '@/lib/api/v1/registry'
@@ -543,8 +544,7 @@ export const POST = withApiV1<{ params: Promise<{ companyId: string }> }>(
       .select('entity_type')
       .eq('company_id', ctx.companyId!)
       .single()
-    const entityType: EntityType =
-      (settings?.entity_type as EntityType) || 'enskild_firma'
+    const entityType: EntityType = await resolveCompanyEntityType(ctx.supabase, ctx.companyId!, settings?.entity_type)
 
     const results: Item[] = []
     for (let i = 0; i < body.items.length; i++) {

app/api/v1/companies/route.ts

@@ -23,6 +23,7 @@ import { readV1JsonBody } from '@/lib/api/v1/body'
 import { dryRunPreview } from '@/lib/api/v1/dry-run'
 import { createCompanyCore } from '@/lib/company/create-company'
 import { CompanySetupSchema, planCompanySetup } from '@/lib/company/onboarding-input'
+import { EntityTypeSchema } from '@/lib/api/schemas'
 
 const Company = z.object({
   id: z.string().uuid(),
@@ -77,7 +78,7 @@ registerEndpoint({
 const CreatedCompany = z.object({
   id: z.string().uuid(),
   name: z.string(),
-  entity_type: z.enum(['enskild_firma', 'aktiebolag']),
+  entity_type: EntityTypeSchema,
   org_number: z.string().nullable(),
   vat_registered: z.boolean(),
   moms_period: z.enum(['monthly', 'quarterly', 'yearly']).nullable(),