feat(invariants): shared format contracts + upgrade-path CI (#1364)

* feat(invariants): centralise shared format contracts, reconcile the org-number paths

The same format rules were written out independently across the codebase, and
where they disagreed the disagreement was invisible until a filing failed.

Worst case, now fixed: four Skatteverket- and Bolagsverket-bound export paths
each had their own idea of a valid organisationsnummer.

  lib/skatteverket/format.ts      strip '-' only      threw on any input with a space
  lib/salary/ku/ku10-generator.ts replace('-', '')    first hyphen only, spaces survived
  lib/salary/agi/xml-generator.ts strip non-digits    stray letters passed the length check
  lib/bokslut/ixbrl/validate      /^\d{6}-?\d{4}$/    rejected the 12-digit form, no Luhn

A company stored with a space or in 12-digit form could file AGI all year and
then fail at the arsredovisning deadline with a message that did not say why.

lib/invariants/ now owns account number, ISO date, four-digit fiscal year and
org number, each with the rationale recorded next to the rule. normalizeOrgNumber
moves here from lib/company-lookup/ and isSaneDateString from lib/utils.ts; both
old paths re-export, so no caller changes. lib/api/schemas.ts builds its
primitives on the module, so ~100 schemas inherit any correction.

The arsredovisning check-digit verdict is a warn, not an error: a wrong Luhn
digit is almost certainly a typo worth surfacing, but whether every org number
Bolagsverket accepts satisfies Luhn is a Swedish domain question we have not
verified against a primary source, and an error there blocks Skicka in. We do
not block a statutory filing on an unverified assumption.

KU10 still passes a 12-digit stored org number through unfolded. That is
pre-existing, and whether the KU10 schema wants 10 or 12 digits is not covered
by the swedish-payroll skill, so it is pinned by a test rather than changed
silently.

Guard 8 (hand-rolled-invariant) tracks the remaining 114 inline copies as a
ratchet that may only go down, same mechanism as the roundOre guard.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* test(ci): add an upgrade-path job that applies new migrations against real data

The pg-real job applies all 548 migrations to an EMPTY database. Empty means
zero rows, so a migration that adds a NOT NULL, adds a CHECK, creates a unique
index or backfills passes trivially in CI and can still fail on production,
where the rows exist. CI proved that a fresh install works; nothing proved that
an existing install upgrades.

The new pg-upgrade job: apply the schema as it stands at the merge base, seed a
small real company (three posted verifikat, balanced lines, one ore-level
amount), then apply ONLY the migrations this PR adds, then assert the data
survived (entries still posted, lines intact, ledger still balances, ore
unchanged, voucher numbers sequential). A PR with no migration no-ops.

Verified locally against supabase/postgres:15.8.1.060 rather than assumed, with
three deliberately bad migrations:

  rescale money on posted lines   empty: would pass   seeded: ERROR (immutability trigger)
  CHECK violating the ore row     empty: exit 0       seeded: exit 3
  NOT NULL on a populated column  empty: exit 0       seeded: exit 3

Base migrations are read out of the merge-base git tree, not the working tree,
so a PR that edits an already-shipped migration still gets the original applied
and the edit surfaces as a failure here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs: record the invariants and upgrade-CI decisions

Two entries covering what this PR changes and, more importantly, the calls that
are not obvious from the diff: why the arsredovisning check-digit verdict is a
warning rather than an error, why KU10's 12-digit passthrough is pinned instead
of fixed, and why the ROT/RUT brf org-number schemas stay on their own rule.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs(test): mark the upgrade fixture as CI-only, never a production template

The fixture writes posted journal_entries and their lines directly, bypassing
the engine and the atomic commit RPC. That is the only way to hand a migration
pre-existing posted rows to break, and it is safe against a throwaway CI
database, but it reads like a sanctioned pattern to anyone who finds it later.

Says so explicitly, with the reason it is confined here (no voucher sequence to
keep gapless, no retention obligation on a database destroyed with the job) and
a pointer back to Hard Rule 2 for anything touching a real database.

Raised by the Swedish compliance review bot on #1364.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

lib/salary/agi/xml-generator.ts

@@ -1,4 +1,5 @@
 import { decryptPersonnummer } from '../personnummer'
+import { isOrgNumberShaped } from '@/lib/invariants/org-number'
 
 /**
  * AGI XML generator: Arbetsgivardeklaration på individnivå.
@@ -197,11 +198,14 @@ export class AGIIncompleteDataError extends Error {
 
 function assertRequiredCompanyData(company: AGICompanyData): void {
   const missing: string[] = []
-  const orgNumberDigits = (company.orgNumber || '').replace(/\D/g, '')
   // Skatteverket's IDENTITET type requires either 10 digits (AB orgnr, we prefix
-  // with "16") or 12 digits (personnummer for enskild firma). Any other length
-  // is a data-entry error that we cannot silently fix.
-  if (orgNumberDigits.length !== 10 && orgNumberDigits.length !== 12) missing.push('organisationsnummer')
+  // with "16") or 12 digits (personnummer for enskild firma). Any other shape is
+  // a data-entry error that we cannot silently fix.
+  //
+  // Shared rule (lib/invariants/org-number.ts), not a local digit-strip: the
+  // previous `replace(/\D/g, '')` also swallowed letters, so a field holding
+  // stray text still measured 10 digits and passed.
+  if (!isOrgNumberShaped(company.orgNumber)) missing.push('organisationsnummer')
   if (!company.contactName.trim()) missing.push('kontaktperson (namn)')
   if (!company.contactPhone.trim()) missing.push('telefon')
   if (!company.contactEmail.trim()) missing.push('e-post')

lib/salary/ku/ku10-generator.ts

@@ -1,5 +1,6 @@
 import { decryptPersonnummer } from '../personnummer'
 import { getBranding } from '@/lib/branding/service'
+import { stripOrgNumberFormatting } from '@/lib/invariants/org-number'
 
 /**
  * KU10 (Kontrolluppgift): Annual employee income statement.
@@ -49,7 +50,10 @@ export function generateKU10Xml(
   employees: KU10EmployeeData[]
 ): string {
   const lines: string[] = []
-  const orgNr = company.orgNumber.replace('-', '')
+  // Shared rule (lib/invariants/org-number.ts). The previous
+  // `replace('-', '')` removed only the FIRST hyphen and left spaces intact, so
+  // an org number entered as "556012 5790" reached Skatteverket with a space in it.
+  const orgNr = stripOrgNumberFormatting(company.orgNumber)
 
   lines.push('<?xml version="1.0" encoding="UTF-8"?>')
   lines.push('<Skatteverket xmlns="http://xmls.skatteverket.se/se/skatteverket/ai/instans/infoForBeskworksgivku/1.0"')