@ekwo-ai/xbrl-cbso 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-09-14
+
+Released with Ekwo OS `v0.2.0`, the first tagged release of the repository this
+package lives in.
+
+### Fixed
+- **A negative half was rounded the wrong way.** The equations and the PCMN
+  mapping used `Math.round(v * 100) / 100`, which goes towards positive
+  infinity and turns `-0.005` into `-0.00`, and which reads `2.675` as `2.67`
+  because `2.675 * 100` is really `267.49999999999994`. The new `roundCurrency`
+  rounds half up on the absolute value, and is the same file in the three
+  packages that hold a copy.
+- **53 reporting codes were filed under the wrong fact**, among them nine pairs that were
+  swapped with each other: `22/27` (Immobilisations corporelles) with `24` (Mobilier et
+  matériel roulant), `20/58` (TOTAL DE L'ACTIF) with `10/49` (TOTAL DU PASSIF), `10`
+  (Capital) with `10/11` (Apport), `65` with `65/66B` (Charges financières), `14`
+  (Bénéfice à reporter) with `9906` (Bénéfice à affecter), `8179` with `8309` in the
+  fixed-assets annex, and nine rows of the social balance sheet. `29` (Créances à plus d'un
+  an), `44` (Dettes commerciales), `62` (Rémunérations) and `66A` were filed under `902`,
+  `440/4`, `1023` and `29`. Every correction is sourced in
+  [`docs/sources.md`](docs/sources.md) and pinned by `test/rubrics.test.ts`.
+
+### Changed
+- **Target framework is now CBSO 26.0**, in use by the Central Balance Sheet Office since
+  2 January 2026: `link:schemaRef` points at `fws/26.0/mod/m01/m01-f.xsd` and the
+  enumeration namespaces move to `26.0`. The abridged model itself did not change between
+  25.0 and 26.0 — the generator produces the same 430 facts against either framework — but
+  the postal-code enumeration follows the municipality mergers of 1 January 2025.
+- The reporting-code table is **generated** from the NBB taxonomy package by
+  `scripts/build-taxonomy.mjs`, no longer transcribed by hand, and covers the whole model:
+  297 codes and 430 cells, against 106 codes before. `--check` verifies the committed table
+  against a package.
+- The previous-year boxes the NBB suffixes with `P` in the annexes (`8059P`, `1003P`) stay
+  the `p` column of their base code; `14P`, which is a line of its own, keeps its own code.
+- `CBSO_25_M01F` is renamed `CBSO_26_M01F`; `FRAMEWORK` is exported.
+- `CbsoInput.values` becomes optional, and `unknownCodes` returns a sorted array.
+
+### Added
+- `CbsoInput.lines`: statement lines keyed by their fact signature
+  (`met:am1|bas:m9|rst:m2`) instead of by a reporting code, so the mapping can live in the
+  system that produced the statement rather than being copied here. `CbsoInput.values`
+  remains supported as the legacy path, and the two can be combined.
+- `resolveFactKey`, `valuesFromFactKeys`, `parseFactKey`, `factKeyOf`, `mergeValues` and
+  `CbsoFactKeyError`, which names the candidate codes when a key fits more than one line.
+- `unfiledValues(input)`: figures that would be dropped, because the code is unknown or
+  because the model has no such column.
+- `docs/sources.md`: where every assertion comes from, and what still needs a filing to
+  confirm it.
+
+## [0.1.0] — 2026-09-11
+
+### Added
+- `generateCbsoXbrl` / `XbrlCbso`: XBRL instance generator for the CBSO taxonomy,
+  abridged model for companies with capital (m01-f), with board members (natural persons,
+  legal entities, permanent representatives, foreign addresses).
+- `checkBnbEquations`: arithmetic identities of the abridged model.
+- `validateInput`, `CbsoInputError`, enterprise-number helpers.
+- `@ekwo-ai/xbrl-cbso/pcmn`: Belgian minimum chart of accounts → reporting codes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ekwo AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# @ekwo-ai/xbrl-cbso
+
+Generate the XBRL file of Belgian annual accounts for the National Bank of Belgium
+(Central Balance Sheet Office, *CBSO* / *Centrale des bilans* / *Balanscentrale*),
+taxonomy **26.0**, abridged model for companies with capital (**m01-f**).
+
+- **Pure TypeScript, zero runtime dependencies.** Works in Node ≥ 18, Deno, Bun and browsers.
+- **Generated from the official taxonomy.** The 297 reporting codes of the model (430 cells,
+  current and previous year), with their metric and dimension members, are read straight out of
+  the NBB taxonomy package by
+  [`scripts/build-taxonomy.mjs`](scripts/build-taxonomy.mjs) — not transcribed by hand. Sources
+  and method: [`docs/sources.md`](docs/sources.md).
+- **Two ways in.** Reporting codes (`20/58`, `9904`), or the fact keys a book-keeping system
+  already stores next to each statement line (`met:am1|bas:m9|rst:m2`).
+- **Partial forms welcome.** Only the codes you provide are emitted; Filing fills the rest.
+  `unknownCodes()` tells you which of your codes the model would skip.
+- **Built-in checks.** Enterprise-number check digits, ISO dates, Belgian postal codes, and the
+  arithmetic identities of the form (`20/58 = 10/49`, `9904 = 9903 + 780 − 680 − 67/77`, …).
+- **Optional PCMN layer.** Turn a trial balance (Belgian minimum chart of accounts) into the
+  reporting codes.
+
+## Install
+
+```sh
+npm install @ekwo-ai/xbrl-cbso
+```
+
+## Usage
+
+```ts
+import { generateCbsoXbrl, checkBnbEquations, LegalForm, EnterpriseCourt } from '@ekwo-ai/xbrl-cbso';
+
+const input = {
+  entityNumber: '0123.456.749',
+  denomination: 'Exemple Conseil',
+  legalForm: LegalForm.SA_NV,          // 'lgf:m014'
+  court: EnterpriseCourt.BRUSSELS_FR,  // 'cct:m31'
+  address: { street: "Rue de l'Exemple", number: '1', postalCode: '1000', city: 'Bruxelles' },
+  periodStart: '2025-01-01',
+  periodEnd: '2025-12-31',
+  prevPeriodStart: '2024-01-01',
+  prevPeriodEnd: '2024-12-31',
+  gaDate: '2026-05-15',   // general meeting approving the accounts
+  deedDate: '2019-03-04', // deed of incorporation / latest amendment of the articles
+  values: {
+    '20/58': { n: 201500, p: 171000 }, // total assets, current and previous year
+    '10/49': { n: 201500, p: 171000 },
+    '9904':  { n: 57500,  p: 43600 },
+    '9087':  { n: 3.5,    p: 3 },      // full-time equivalents
+    // … any other code of the abridged model
+  },
+  administrators: [
+    { kind: 'person', lastName: 'Dupont', firstName: 'Marie',
+      street: 'Avenue des Tilleuls', number: '12', postalCode: '1180', city: 'Uccle' },
+    { kind: 'company', name: 'Gestion Exemple', enterpriseNumber: '0400.000.086',
+      street: 'Kerkstraat', number: '7', postalCode: '9000', city: 'Gent',
+      representative: { lastName: 'Janssens', firstName: 'Pieter' } },
+  ],
+};
+
+const violations = checkBnbEquations(input.values); // [] when the form adds up
+const xml = generateCbsoXbrl(input);                 // string, UTF-8, ready to upload
+```
+
+See [`examples/basic.ts`](examples/basic.ts) for a runnable version (`npm run example`).
+
+### From statement lines that already carry their taxonomy key
+
+A book-keeping system that stores the CBSO fact key next to each line of its
+financial statements does not need to know the reporting codes at all. Hand the
+lines over as they are:
+
+```ts
+import { generateCbsoXbrl } from '@ekwo-ai/xbrl-cbso';
+
+const xml = generateCbsoXbrl({
+  ...identification,
+  lines: [
+    { xbrl_element: 'met:am1|bas:m2|ntr:m2', amount: 12000, previous_amount: 15000 }, // 22/27
+    { xbrl_element: 'met:am1|bas:m5|ntr:m2', amount: 8000,  previous_amount: 10000 }, // 24
+    { xbrl_element: 'met:am1|bas:m9|rst:m2', amount: 60000, previous_amount: 47500 }, // 40/41
+  ],
+});
+```
+
+A key is the metric followed by the domain members that matter; the members that
+only place a fact in a column (`dim:part`, `dim:prd`) may be left out. It
+resolves to the line that adds the fewest members of its own, so
+`met:am1|bas:m2` is the heading *ACTIFS IMMOBILISÉS* (21/28) and not one of the
+three lines under it. A key that fits two lines equally well is refused rather
+than guessed:
+
+```ts
+resolveFactKey('met:am1|bas:m25', CBSO_26_M01F);
+// CbsoFactKeyError: signature shared by 10/49, 20/58 — add the member that
+// separates them (usually a "part:" member)
+```
+
+`met:am1|bas:m25|part:m1` is the total of the assets, `|part:m3` the total of
+the liabilities. `resolveFactKey`, `valuesFromFactKeys` and `factKeyOf` are
+exported for callers that want to do the mapping themselves; `mergeValues`
+shows what a filing would carry when both `values` and `lines` are given, and
+refuses a code that the two disagree on.
+
+### From a trial balance
+
+```ts
+import { valuesFromTrialBalance } from '@ekwo-ai/xbrl-cbso/pcmn';
+
+// balance = debit − credit, for the current and the previous year
+const values = valuesFromTrialBalance([
+  { account: '400000', balance: 52000, priorBalance: 41000 },
+  { account: '440000', balance: -31000, priorBalance: -28000 },
+  { account: '700000', balance: -320000, priorBalance: -270000 },
+  // …
+]);
+```
+
+`valuesFromTrialBalance` computes the four sections (assets, equity and liabilities, income
+statement, appropriation) with the sign conventions of the standardised form, and returns them in
+the shape the generator expects. Lower-level functions (`computeBalanceSheet`,
+`computeIncomeStatement`, `computeAppropriation`, the `ASSETS` / `LIABILITIES` /
+`INCOME_STATEMENT` / `APPROPRIATION` tables) are exported for custom pipelines.
+
+Annex figures that do not derive from the trial balance (fixed-assets movements `8029`–`8395`,
+staff `9087`, …) are plain codes: add them to `values` yourself.
+
+## API
+
+| Export | Description |
+|---|---|
+| `generateCbsoXbrl(input, options?)` | One call: `CbsoInput` → XBRL string. Validates the input unless `options.validate === false`. `options.lang` sets `xml:lang` (default `fr`). |
+| `checkBnbEquations(values, options?)` | Returns the identities that do not add up (`code`, `column`, `expected`, `actual`, `rule`). Missing operands count as zero, as in Filing. |
+| `unknownCodes(values)` | Codes the abridged model does not carry (they would be silently skipped), sorted. |
+| `unfiledValues(input)` | Figures that would be dropped: an unknown code, or a code whose column the model does not have. |
+| `resolveFactKey(key, template)` | `"met:am1\|bas:m9\|rst:m2"` → `"40/41"`. Throws a `CbsoFactKeyError` naming the candidates when the key fits more than one line. |
+| `valuesFromFactKeys(lines, template)`, `factKeyOf(fact)`, `parseFactKey(key)` | The pieces of that path, for callers doing the mapping themselves. |
+| `mergeValues(input, template?)` | `values` plus the resolved `lines`; throws when the two disagree on a code. |
+| `validateInput(input)` | Throws a `CbsoInputError` (`path`, `message`) on the first problem. |
+| `normalizeEnterpriseNumber`, `isValidEnterpriseNumber` | `"BE 0123.456.749"` → `"0123456749"`; mod-97 check digits. |
+| `LegalForm`, `EnterpriseCourt` | Taxonomy members verified against accepted filings. Any other `lgf:*` / `cct:*` member can be passed as a string. |
+| `XbrlCbso`, `CBSO_26_M01F`, `FRAMEWORK`, `NAMESPACES` | Class API and bundled template, for a custom or updated taxonomy. |
+
+Types: `CbsoInput`, `FactKeyLine`, `PostalAddress`, `Administrator`, `YearValues`,
+`Declarations`, `TemplateFact`, `CbsoTemplate`.
+
+`CbsoInput.values` is the legacy path: it makes the caller hold its own mapping
+from its accounts to the reporting codes of the model. `CbsoInput.lines` exists
+so that mapping can live in one place — the system that produced the statement —
+instead of being copied here. Both stay supported, and they can be combined.
+
+## How it works
+
+The CBSO taxonomy carries the reporting code (*rubrique* / *rubriek*) in the **dimensions** of the
+context (`dim:bas → bas:mXX`, `dim:part`, `dim:prd` for current vs previous year…), never in the
+element name: amounts are all `met:am1` / `met:am2`, figures `met:int*` / `met:dec1`. A template
+lists, for each of the 430 cells of the abridged model, that exact signature. The generator:
+
+1. keeps the template facts that have a value (identification fields, reporting codes);
+2. adds the enumerated identification facts (legal form, court, postal code, country) and the
+   board members (typed dimensions keyed by name);
+3. builds the deduplicated contexts, declares only the namespaces actually used, and formats
+   numbers according to the element facets (two decimals for amounts, one for FTEs, integers).
+
+The previous financial year is **not** a second period: both columns are reported in a context
+whose period is the closing date of the current year, and `dim:prd` (`prd:m1` / `prd:m2`) says
+which column. The boxes the NBB itself suffixes with `P` in the annexes (`8059P`, `1003P`) measure
+the same thing as their base code one year earlier, so they are its `p` figure. `14P` is not in
+that case — "profit carried forward from the previous year" is a line of its own — and keeps its
+own code.
+
+To rebuild the table against a newer taxonomy package:
+
+```sh
+node scripts/build-taxonomy.mjs --package ~/nbb-cbso-26.0.15            # rewrite
+node scripts/build-taxonomy.mjs --package ~/nbb-cbso-26.0.15 --check    # verify only
+```
+
+## Scope and limitations
+
+- Model **m01-f** only (abridged, companies with capital). Full and micro models, and the
+  non-profit taxonomy, are not covered yet — though the build script takes `--model` and
+  `--framework`, so the table for another one is a command away.
+- The **identification** facts (section 1) are not generated: they carry no reporting code, and
+  are kept from a filing the NBB accepted. Everything else comes from the taxonomy.
+- Only the legal form and court identifiers verified in accepted filings are named constants;
+  other members must be looked up in the taxonomy's `lgf` / `cct` domains.
+- The generator does not validate against the XSD. The NBB *Filing* application remains the
+  authority: import the file in a draft and check its validation report before submitting.
+
+## Development
+
+```sh
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+## License
+
+[MIT](LICENSE) © Ekwo AI

package/dist/enterprise-number.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Belgian enterprise number (numéro d'entreprise / ondernemingsnummer):
+ * ten digits, the last two being `97 - (first eight mod 97)`.
+ */
+/** Strip dots, spaces and an optional `BE` prefix: `"BE 0123.456.749"` → `"0123456749"`. */
+export declare function normalizeEnterpriseNumber(raw: string): string;
+/** `true` when the ten-digit number carries valid check digits. */
+export declare function isValidEnterpriseNumber(raw: string): boolean;
+//# sourceMappingURL=enterprise-number.d.ts.map

package/dist/enterprise-number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enterprise-number.d.ts","sourceRoot":"","sources":["../src/enterprise-number.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4FAA4F;AAC5F,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,mEAAmE;AACnE,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAM5D"}

package/dist/enterprise-number.js

@@ -0,0 +1,18 @@
+/**
+ * Belgian enterprise number (numéro d'entreprise / ondernemingsnummer):
+ * ten digits, the last two being `97 - (first eight mod 97)`.
+ */
+/** Strip dots, spaces and an optional `BE` prefix: `"BE 0123.456.749"` → `"0123456749"`. */
+export function normalizeEnterpriseNumber(raw) {
+    return raw.replace(/^\s*BE/i, '').replace(/\D/g, '');
+}
+/** `true` when the ten-digit number carries valid check digits. */
+export function isValidEnterpriseNumber(raw) {
+    const digits = normalizeEnterpriseNumber(raw);
+    if (!/^\d{10}$/.test(digits))
+        return false;
+    const base = Number(digits.slice(0, 8));
+    const check = Number(digits.slice(8));
+    return 97 - (base % 97) === check;
+}
+//# sourceMappingURL=enterprise-number.js.map

package/dist/enterprise-number.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enterprise-number.js","sourceRoot":"","sources":["../src/enterprise-number.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4FAA4F;AAC5F,MAAM,UAAU,yBAAyB,CAAC,GAAW;IACnD,OAAO,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACvD,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,MAAM,MAAM,GAAG,yBAAyB,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,OAAO,EAAE,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,KAAK,KAAK,CAAC;AACpC,CAAC"}

package/dist/equations.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Arithmetic identities of the abridged model, as checked by the Filing
+ * application. Run them before generating to catch inconsistent inputs early.
+ */
+import type { BnbCode, YearValues } from './types.js';
+export interface EquationViolation {
+    /** Code of the total that does not add up. */
+    code: BnbCode;
+    column: 'n' | 'p';
+    expected: number;
+    actual: number;
+    /** Human-readable identity, e.g. `"20/58 = 20 + 21/28 + 29/58"`. */
+    rule: string;
+}
+interface Identity {
+    total: BnbCode;
+    /** Operands with their sign. */
+    terms: Array<{
+        code: BnbCode;
+        sign: 1 | -1;
+    }>;
+}
+/** Identities of the abridged model for companies with capital. */
+export declare const ABRIDGED_IDENTITIES: readonly Identity[];
+/**
+ * Checks every identity whose total and at least one operand are present in
+ * `values`. Missing operands count as zero, as in Filing. Returns the
+ * violations (empty = consistent).
+ */
+export declare function checkBnbEquations(values: Record<BnbCode, YearValues>, options?: {
+    tolerance?: number;
+    identities?: readonly Identity[];
+}): EquationViolation[];
+export {};
+//# sourceMappingURL=equations.d.ts.map

package/dist/equations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equations.d.ts","sourceRoot":"","sources":["../src/equations.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGtD,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,QAAQ;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,gCAAgC;IAChC,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;KAAE,CAAC,CAAC;CAC/C;AAKD,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,EAAE,SAAS,QAAQ,EAiClD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EACnC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAA;CAAO,GACrE,iBAAiB,EAAE,CA8BrB"}

package/dist/equations.js

@@ -0,0 +1,77 @@
+import { roundCurrency } from './rounding.js';
+const plus = (code) => ({ code, sign: 1 });
+const minus = (code) => ({ code, sign: -1 });
+/** Identities of the abridged model for companies with capital. */
+export const ABRIDGED_IDENTITIES = [
+    // Balance sheet
+    { total: '20/58', terms: [plus('20'), plus('21/28'), plus('29/58')] },
+    { total: '21/28', terms: [plus('21'), plus('22/27'), plus('28')] },
+    { total: '22/27', terms: [plus('22'), plus('23'), plus('24'), plus('25'), plus('26'), plus('27')] },
+    { total: '29/58', terms: [plus('29'), plus('3'), plus('40/41'), plus('50/53'), plus('54/58'), plus('490/1')] },
+    { total: '40/41', terms: [plus('40'), plus('41')] },
+    { total: '10/49', terms: [plus('10/15'), plus('16'), plus('17/49')] },
+    { total: '10/15', terms: [plus('10/11'), plus('12'), plus('13'), plus('14'), plus('15'), plus('19')] },
+    { total: '10/11', terms: [plus('10'), plus('11')] },
+    { total: '10', terms: [plus('100'), plus('101')] },
+    { total: '13', terms: [plus('130/1'), plus('132'), plus('133')] },
+    { total: '17/49', terms: [plus('17'), plus('42/48'), plus('492/3')] },
+    { total: '42/48', terms: [plus('42'), plus('43'), plus('44'), plus('46'), plus('45'), plus('47/48')] },
+    { total: '45', terms: [plus('450/3'), plus('454/9')] },
+    // Balance sheet total = total of liabilities and equity
+    { total: '20/58', terms: [plus('10/49')] },
+    // Income statement
+    { total: '75/76B', terms: [plus('75'), plus('76B')] },
+    { total: '65/66B', terms: [plus('65'), plus('66B')] },
+    {
+        total: '9901',
+        terms: [plus('9900'), minus('62'), minus('630'), minus('631/4'), minus('635/8'), minus('640/8'), plus('649'), minus('66A')],
+    },
+    { total: '9903', terms: [plus('9901'), plus('75/76B'), minus('65/66B')] },
+    { total: '9904', terms: [plus('9903'), plus('780'), minus('680'), minus('67/77')] },
+    { total: '9905', terms: [plus('9904'), plus('789'), minus('689')] },
+    // Appropriation
+    { total: '9906', terms: [plus('9905'), plus('14P')] },
+    // Fixed assets: net book value = acquisition value − depreciation
+    { total: '21', terms: [plus('8059'), minus('8129')] },
+    { total: '22/27', terms: [plus('8199'), minus('8329')] },
+    { total: '28', terms: [plus('8395')] },
+];
+/**
+ * Checks every identity whose total and at least one operand are present in
+ * `values`. Missing operands count as zero, as in Filing. Returns the
+ * violations (empty = consistent).
+ */
+export function checkBnbEquations(values, options = {}) {
+    const tolerance = options.tolerance ?? 0.005;
+    const identities = options.identities ?? ABRIDGED_IDENTITIES;
+    const violations = [];
+    for (const identity of identities) {
+        for (const column of ['n', 'p']) {
+            const actual = values[identity.total]?.[column];
+            if (actual == null)
+                continue;
+            // An identity whose operands are all absent is not part of the form
+            // being filed (e.g. the fixed-assets annex was not provided).
+            if (!identity.terms.some((t) => values[t.code]?.[column] != null))
+                continue;
+            const expected = identity.terms.reduce((sum, t) => sum + t.sign * (values[t.code]?.[column] ?? 0), 0);
+            if (Math.abs(expected - actual) > tolerance) {
+                violations.push({
+                    code: identity.total,
+                    column,
+                    expected: round2(expected),
+                    actual: round2(actual),
+                    rule: `${identity.total} = ${identity.terms
+                        .map((t, k) => `${t.sign < 0 ? '- ' : k === 0 ? '' : '+ '}${t.code}`)
+                        .join(' ')}`,
+                });
+            }
+        }
+    }
+    return violations;
+}
+/** The one rounding rule, at two decimals. See `rounding.ts`. */
+function round2(v) {
+    return roundCurrency(v, 2);
+}
+//# sourceMappingURL=equations.js.map

package/dist/equations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"equations.js","sourceRoot":"","sources":["../src/equations.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+/** Thrown by {@link generateCbsoXbrl} when the input cannot produce a valid filing. */
+export declare class CbsoInputError extends Error {
+    /** Dotted path of the offending field, e.g. `"address.postalCode"`. */
+    readonly path: string;
+    constructor(message: string, 
+    /** Dotted path of the offending field, e.g. `"address.postalCode"`. */
+    path: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,qBAAa,cAAe,SAAQ,KAAK;IAGrC,uEAAuE;aACvD,IAAI,EAAE,MAAM;gBAF5B,OAAO,EAAE,MAAM;IACf,uEAAuE;IACvD,IAAI,EAAE,MAAM;CAK/B"}

package/dist/errors.js

@@ -0,0 +1,12 @@
+/** Thrown by {@link generateCbsoXbrl} when the input cannot produce a valid filing. */
+export class CbsoInputError extends Error {
+    path;
+    constructor(message, 
+    /** Dotted path of the offending field, e.g. `"address.postalCode"`. */
+    path) {
+        super(`${path}: ${message}`);
+        this.path = path;
+        this.name = 'CbsoInputError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,MAAM,OAAO,cAAe,SAAQ,KAAK;IAIrB;IAHlB,YACE,OAAe;IACf,uEAAuE;IACvD,IAAY;QAE5B,KAAK,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QAFb,SAAI,GAAJ,IAAI,CAAQ;QAG5B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF"}

package/dist/fact-keys.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Fact keys — the dimensional way to name a line of the annual accounts.
+ *
+ * The CBSO taxonomy has no element per reporting code: a code is a generic
+ * metric plus a set of explicit dimension members. A fact key writes that
+ * signature down, metric first:
+ *
+ *     met:am1|bas:m9|rst:m2      → "Créances à un an au plus" (40/41)
+ *     met:am2|bas:m44|ntr:m4     → "Bénéfice (Perte) reporté(e)" (14)
+ *
+ * A key names the members that matter and leaves the rest implicit, so it can
+ * be stored next to a statement line without repeating the whole context. It
+ * resolves against the template to exactly one reporting code, or throws.
+ */
+import { CbsoInputError } from './errors.js';
+import type { BnbCode, CbsoTemplate, TemplateFact, YearValues } from './types.js';
+/**
+ * One line of a financial statement, keyed by its fact signature rather than
+ * by a reporting code. Shaped after the rows a book-keeping system produces:
+ * `xbrl_element` holds the key, `amount` the figure of the financial year.
+ */
+export interface FactKeyLine {
+    /** Fact key, e.g. `"met:am1|bas:m9|rst:m2"`. */
+    xbrl_element: string;
+    /** Amount of the current financial year. */
+    amount?: number | null;
+    /** Amount of the previous financial year, when the line carries one. */
+    previous_amount?: number | null;
+}
+/** Thrown when a fact key names no line of the model, or more than one. */
+export declare class CbsoFactKeyError extends CbsoInputError {
+    /** The key that could not be resolved. */
+    readonly key: string;
+    /** Reporting codes the key could stand for, when it is ambiguous. */
+    readonly candidates: readonly BnbCode[];
+    constructor(message: string, 
+    /** The key that could not be resolved. */
+    key: string, 
+    /** Reporting codes the key could stand for, when it is ambiguous. */
+    candidates?: readonly BnbCode[]);
+}
+interface ParsedKey {
+    metric: string;
+    members: Record<string, string>;
+}
+/** `"met:am1|bas:m9|rst:m2"` → metric plus `{ "dim:bas": "bas:m9", … }`. */
+export declare function parseFactKey(key: string): ParsedKey;
+/**
+ * Reporting code a fact key stands for.
+ *
+ * Candidates are the facts of the template that carry the key's metric and
+ * every one of its members; the winner is the one that adds the fewest members
+ * of its own — `met:am1|bas:m2` is "ACTIFS IMMOBILISÉS" (21/28) and not one of
+ * the three lines under it. A tie means the key does not say enough: the error
+ * lists the codes it could stand for.
+ */
+export declare function resolveFactKey(key: string, template: CbsoTemplate): BnbCode;
+/**
+ * Turns statement lines keyed by fact signature into the `values` map of
+ * {@link CbsoInput}. Lines whose two amounts are both absent are skipped; a
+ * code reached twice with conflicting figures is an error, not a silent
+ * overwrite.
+ */
+export declare function valuesFromFactKeys(lines: readonly FactKeyLine[], template: CbsoTemplate): Record<BnbCode, YearValues>;
+/** Fact key of one template fact, in the same syntax {@link parseFactKey} reads. */
+export declare function factKeyOf(fact: TemplateFact): string;
+export {};
+//# sourceMappingURL=fact-keys.d.ts.map

package/dist/fact-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-keys.d.ts","sourceRoot":"","sources":["../src/fact-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAElF;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,2EAA2E;AAC3E,qBAAa,gBAAiB,SAAQ,cAAc;IAGhD,0CAA0C;aAC1B,GAAG,EAAE,MAAM;IAC3B,qEAAqE;aACrD,UAAU,EAAE,SAAS,OAAO,EAAE;gBAJ9C,OAAO,EAAE,MAAM;IACf,0CAA0C;IAC1B,GAAG,EAAE,MAAM;IAC3B,qEAAqE;IACrD,UAAU,GAAE,SAAS,OAAO,EAAO;CAKtD;AAKD,UAAU,SAAS;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAkBnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAiC3E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,QAAQ,EAAE,YAAY,GACrB,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAiB7B;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAMpD"}