@12-apps/fiscal 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,125 @@
1
- # Temporary Holding Version
1
+ # @12-apps/fiscal
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Brazilian consumption-tax machinery for any host that sells. The package is
4
+ built module by module; the first is the **IBS/CBS engine**.
5
+
6
+ | subpath | what it is |
7
+ |---|---|
8
+ | `@12-apps/fiscal/engine` | `computeTax(input) → TaxBreakdown`: pure, no I/O, no clock, no defaults. Plus `computeTaxWithOracle` over an injected `OfficialCalculator` port, and `compareBreakdowns`. |
9
+ | `@12-apps/fiscal/tables/<file>.json` | Versioned rate tables — DATA, never code. The engine stamps the table's `version` on every result. |
10
+ | `@12-apps/fiscal/manifest` | The `@12-apps/wiring` manifest. A skeleton today: the four permissions. |
11
+
12
+ ## The engine
13
+
14
+ ```ts
15
+ import { computeTax } from "@12-apps/fiscal/engine";
16
+ import tables from "@12-apps/fiscal/tables/ibs-cbs-2026-11-13.json" with { type: "json" };
17
+
18
+ const breakdown = computeTax({
19
+ lines: [
20
+ {
21
+ id: "item-1",
22
+ valueCents: 3990, // what the buyer pays for the line, after its allocated discount
23
+ quantity: 1, // qCom, at most four decimals
24
+ foodAndDrink: true,
25
+ taxClass: { cClassTrib: "200047", cstIbsCbs: "200", regimeEspecifico: "BARES_RESTAURANTES", reductionBp: 0 },
26
+ },
27
+ ],
28
+ seller: { regime: "REGIME_REGULAR", regimeEffectiveFrom: "2026-01-01", restaurantRegime: true },
29
+ destinationIbge: "3550308", // the establishment, or for a delivered good the place of delivery
30
+ exclusions: { serviceCharge: null, retainedIntermediation: null },
31
+ tables,
32
+ supplyDate: "2026-11-20", // the local day of the supply, in the seller's clock
33
+ });
34
+ // breakdown.lines[i]: one NF-e item each — valueCents (vProd), taxBaseCents (vBC),
35
+ // cbsRateBp/cbsCents, ibsUfRateBp/ibsUfCents, ibsMunRateBp/ibsMunCents, reductionBp,
36
+ // taxCents, netValueCents (vProdLiq) and netUnitValue (vUnComLiq), the class snapshot
37
+ // breakdown: the sums, netValueCents (vProdLiqTot), gorjetaExcludedCents,
38
+ // intermediationExcludedCents, treatment, informative, provisional, taxInsidePrice,
39
+ // tablesVersion
40
+ ```
41
+
42
+ Money is integer cents, rates integer basis points, dates `YYYY-MM-DD`. Any
43
+ value the engine cannot read — a missing object, an `undefined` where `null` is
44
+ required, a malformed table — is refused with a `FiscalEngineError` carrying a
45
+ `code`; nothing is defaulted.
46
+
47
+ ### What a host passes as a line's value
48
+
49
+ Always **the price the buyer pays for the line** (all units, after the line's
50
+ share of an unconditional discount). The engine decides from the rate table
51
+ whether the tax is inside it:
52
+
53
+ - **A period with `taxInsidePrice: false` (2026).** The value is the base:
54
+ `vBC = value`, each tax is `vBC × rate`, and `netValueCents` /
55
+ `netUnitValue` are `null` — the tax is not part of `vProd` yet.
56
+ - **A period with `taxInsidePrice: true` (2027 on, where the IBS/CBS compose
57
+ `vProd`).** The value is tax-inclusive. The engine takes the taxes out: `vBC`
58
+ is the largest whole-cent base whose rounded taxes, added back, fit inside
59
+ the value; each tax is rounded on that `vBC`; `netValueCents` (`vProdLiq`) is
60
+ the value less the taxes, so `vProdLiq + Σ tax = vProd` to the cent; and
61
+ `netUnitValue` (`vUnComLiq`, reais with ten decimals) times the quantity is
62
+ within the layout's ±0,01 of `vProdLiq` (rule I11c-20). The price never
63
+ changes; the tax is a share of it.
64
+
65
+ ### The rules it applies (LC 214/2025)
66
+
67
+ - **Rates by the date of the supply**, from the table's period covering it:
68
+ 2026 CBS 0.9% and IBS 0.1% (arts. 343, 346), informative (art. 348 §1);
69
+ 2027–2028 IBS 0.05% state + 0.05% municipal (art. 344); later years the
70
+ reference rates the table carries. A period whose figures are not yet law is
71
+ `status: "ESTIMATE"` and stamps its results `provisional: true`.
72
+ - **Destination** (art. 11 I): a state's or municipality's own rate where the
73
+ table lists one (`byUf`, `byMunicipality`), the reference rate elsewhere.
74
+ - **Regimes** (art. 41): regime regular and the Simples híbrido → `FULL`;
75
+ Simples inside the DAS → `INFORMATIVE`, carrying the figures a regime store
76
+ would show and no amount "por fora"; MEI and não contribuinte → `NONE`, zero
77
+ and not informative. In 2026 the test rates are not applied to Simples
78
+ optants (art. 348 III "c"), read from the period's `appliesToSimplesNacional`.
79
+ - **Bares e restaurantes**: in a store with `restaurantRegime`, a line whose
80
+ class is `BARES_RESTAURANTES` (prepared food, non-alcoholic drinks prepared
81
+ on the premises — art. 273; official class 200047) takes the table's 40%
82
+ reduction (art. 275); alcohol and resale carry `regimeEspecifico: null` and
83
+ the full rate (art. 273 §2). Outside the special regime a class's own
84
+ `reductionBp` applies (a cesta-básica zero rate is a 100% reduction).
85
+ - **Exclusions**, restaurant regime only (art. 274 par. único), each
86
+ **segregated as its own item** with no tax (RCBS art. 399 §2; without the
87
+ segregation the base is the full value, §4), under the table's
88
+ `exclusionClasses`:
89
+ - the service charge, when passed in full to the staff AND at most 15% of
90
+ the food and drink (I): one item, class 410019. Above 15%, or kept by the
91
+ store, nothing is excluded — the WHOLE charge is a taxed item under the
92
+ class the host passes. There is no partial exclusion.
93
+ - what a platform retained for delivery and intermediation (II): one item,
94
+ class 410020, passed as `retainedIntermediation` and NOT inside any line's
95
+ value. No goods line's base moves for it. Outside the restaurant regime it
96
+ is refused: there the amount belongs in the lines.
97
+ - **Rounding**: per item, per tax, to whole cents, **half-even** — what the
98
+ official calculator does (R$ 5,00 × 0,9% = 0,045 → 0,04), never a floor; the
99
+ reduction applies to the rate before the product is rounded, and every order
100
+ figure is the sum of its rounded items. The effective rate (`pAliqEfet`) is
101
+ not output: the product is computed exactly from the nominal rate and the
102
+ reduction, which equals `vBC × pAliqEfet` for any whole-percent reduction —
103
+ every reduction in the official table (V0066) is one: 30, 40, 50, 60, 70, 80
104
+ or 100%.
105
+
106
+ ### The oracle mode
107
+
108
+ `computeTaxWithOracle(input, calculator)` takes the same input and asks an
109
+ `OfficialCalculator` port for each taxed item's rates, reduction and taxes; the
110
+ regime, the exclusions and the bases stay the engine's (in a tax-inside-price
111
+ period the base is taken out with the table's rates, since the calculator
112
+ takes a base). A host points the port at the official calculator's HTTP API.
113
+ The package's suite replays REAL recorded calculator answers for 2026
114
+ (`src/engine/__tests__/fixtures/calculator/`, version and date in
115
+ `recording.json`) and asserts `compareBreakdowns` finds nothing. The
116
+ calculator has no rates for 2027 and later yet, so those years' goldens are
117
+ the engine's own estimates, marked `provisional`.
118
+
119
+ ## The manifest
120
+
121
+ `@12-apps/fiscal/manifest` declares the permissions `fiscal:read`,
122
+ `fiscal:manage`, `fiscal:issue` and `fiscal:cancel`, here and nowhere else. The
123
+ document module adds `db`, `server: ["http", "jobs"]`, `notifications`,
124
+ `web: ["surface"]` and `observability`; until then `.wiring-conformance.json`
125
+ answers each with its reason.
@@ -0,0 +1,7 @@
1
+ var __defProp = Object.defineProperty;
2
+ var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
3
+
4
+ export {
5
+ __name
6
+ };
7
+ //# sourceMappingURL=chunk-7QVYU63E.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
@@ -0,0 +1,361 @@
1
+ /**
2
+ * The engine's vocabulary. Money is integer CENTS, rates are integer BASIS
3
+ * POINTS (1 bp = 0.01%), dates are ISO calendar days (`YYYY-MM-DD`) in the
4
+ * seller's own clock — the fato gerador is the local day of the supply, and the
5
+ * host, which owns the clock, says which day that was.
6
+ *
7
+ * Nothing here has a default. Every field is required, and a value the engine
8
+ * cannot read is refused with a `FiscalEngineError`, never guessed.
9
+ */
10
+ /** An ISO calendar day, `YYYY-MM-DD`. */
11
+ type IsoDate = string;
12
+ /**
13
+ * The seller's IBS/CBS regime (LC 214/2025 art. 41).
14
+ *
15
+ * - `REGIME_REGULAR` — Lucro Presumido/Real: the full breakdown, "por fora".
16
+ * - `SIMPLES_IBS_CBS_REGULAR` — the Simples híbrido (art. 41 §3): a Simples
17
+ * optant that applies the regime regular to IBS/CBS; full breakdown.
18
+ * - `SIMPLES` — inside the DAS (art. 41 §2): an `INFORMATIVE` breakdown, with
19
+ * the figures a regime store would show and no amount charged "por fora".
20
+ * - `MEI` and `NAO_CONTRIBUINTE` — no IBS/CBS on the document: zero.
21
+ */
22
+ type TaxRegime = "REGIME_REGULAR" | "SIMPLES_IBS_CBS_REGULAR" | "SIMPLES" | "MEI" | "NAO_CONTRIBUINTE";
23
+ /** The special regimes the engine applies. */
24
+ type RegimeEspecifico = "BARES_RESTAURANTES";
25
+ /** What the treatment of the seller's regime is on the date of the supply. */
26
+ type TaxTreatment = "FULL" | "INFORMATIVE" | "NONE";
27
+ /** The two codes an NF-e item carries for its IBS/CBS classification. */
28
+ interface TaxClassCode {
29
+ readonly cClassTrib: string;
30
+ readonly cstIbsCbs: string;
31
+ }
32
+ /**
33
+ * A line's tax class, as the host classified the item. `cClassTrib` and
34
+ * `cstIbsCbs` are carried opaque into the snapshot (the classification table
35
+ * is the host's data, Informe Técnico 2025.002).
36
+ *
37
+ * `regimeEspecifico: "BARES_RESTAURANTES"` marks prepared food and
38
+ * non-alcoholic drinks prepared on the premises (art. 273 caput, §1; the
39
+ * official class is 200047). Alcohol, even prepared on the premises, and food
40
+ * or drink bought from third parties and resold as-is are OUT (art. 273 §2)
41
+ * and must carry `null`.
42
+ */
43
+ interface TaxClass extends TaxClassCode {
44
+ readonly regimeEspecifico: RegimeEspecifico | null;
45
+ /** The class's own rate reduction (a listed-food reduction, say), 0–10000. */
46
+ readonly reductionBp: number;
47
+ }
48
+ /** One priced line of the supply. */
49
+ interface TaxLineInput {
50
+ /** The host's id, echoed on the output line; unique within the input. */
51
+ readonly id: string;
52
+ /**
53
+ * What the line costs the buyer, every unit, AFTER its allocated discount
54
+ * (an unconditional discount is outside the base, art. 12 §2 III). It is
55
+ * the price the shopper sees, so in a period whose table says
56
+ * `taxInsidePrice` the IBS/CBS are INSIDE it and the engine takes them out;
57
+ * otherwise it is the base itself and the tax is computed on top of it.
58
+ */
59
+ readonly valueCents: number;
60
+ /** Units (`qCom`): positive, at most four decimals (weighed goods). */
61
+ readonly quantity: number;
62
+ /**
63
+ * Whether the line is food or drink — what the gorjeta's 15% ceiling is
64
+ * measured against (art. 274 par. único I). A delivery fee is not.
65
+ */
66
+ readonly foodAndDrink: boolean;
67
+ readonly taxClass: TaxClass;
68
+ }
69
+ /** Who sells, and under which regime since when. */
70
+ interface SellerProfile {
71
+ readonly regime: TaxRegime;
72
+ /** The first day `regime` applies. A supply before it is refused. */
73
+ readonly regimeEffectiveFrom: IsoDate;
74
+ /** Whether the bares e restaurantes regime (arts. 273–276) applies. */
75
+ readonly restaurantRegime: boolean;
76
+ }
77
+ /** The service charge (taxa de serviço / gorjeta) on the supply. */
78
+ interface ServiceChargeInput {
79
+ /** Echoed as the service-charge line's id; unique within the input. */
80
+ readonly id: string;
81
+ readonly amountCents: number;
82
+ /** Whether the charge is passed in full to the staff. */
83
+ readonly passedToStaff: boolean;
84
+ /** The class the WHOLE charge is taxed at when it is not excluded. */
85
+ readonly taxClass: TaxClass;
86
+ }
87
+ /** What a digital platform retained for delivery and intermediation. */
88
+ interface RetainedIntermediationInput {
89
+ /** Echoed as the excluded line's id; unique within the input. */
90
+ readonly id: string;
91
+ /** Never passed to the restaurant; NOT included in any line's value. */
92
+ readonly amountCents: number;
93
+ }
94
+ /**
95
+ * The amounts the restaurant regime keeps out of the base (art. 274 par.
96
+ * único), each segregated on the document as its own item (RCBS art. 399 §2:
97
+ * without the segregation the base is the full value, §4).
98
+ */
99
+ interface TaxExclusions {
100
+ /**
101
+ * Excluded (its own line, the table's gorjeta class) only when the store is
102
+ * in the restaurant regime, the charge is passed in full to the staff AND it
103
+ * is at most 15% of the food and drink. Otherwise the whole charge is a
104
+ * taxed line under its own class — never a partial exclusion.
105
+ */
106
+ readonly serviceCharge: ServiceChargeInput | null;
107
+ /** Restaurant regime only (art. 274 par. único II); refused elsewhere. */
108
+ readonly retainedIntermediation: RetainedIntermediationInput | null;
109
+ }
110
+ /** The IBS share of one sphere in one period: the reference and the overrides. */
111
+ interface IbsSphereRates {
112
+ /** The reference rate, which applies wherever no own rate is listed. */
113
+ readonly referenceBp: number;
114
+ }
115
+ interface IbsUfRates extends IbsSphereRates {
116
+ /** State rates keyed by the 2-digit IBGE state code. */
117
+ readonly byUf: Readonly<Record<string, number>>;
118
+ }
119
+ interface IbsMunRates extends IbsSphereRates {
120
+ /** Municipal rates keyed by the 7-digit IBGE municipality code. */
121
+ readonly byMunicipality: Readonly<Record<string, number>>;
122
+ }
123
+ /** One stretch of time with one set of rates. */
124
+ interface RatePeriod {
125
+ readonly from: IsoDate;
126
+ /** Inclusive; `null` is open-ended. */
127
+ readonly to: IsoDate | null;
128
+ /** `ESTIMATE` stamps every result computed on it `provisional`. */
129
+ readonly status: "LAW" | "ESTIMATE";
130
+ readonly source: string;
131
+ /** The test year: highlighted, payment waived (art. 348 §1). */
132
+ readonly informative: boolean;
133
+ /** `false` in 2026: the test rates are not applied to Simples optants (art. 348 III "c"). */
134
+ readonly appliesToSimplesNacional: boolean;
135
+ /**
136
+ * Whether the IBS/CBS sit INSIDE the item's value on the document (they
137
+ * compose `vProd` and the price without tax travels in `vProdLiq`) — from
138
+ * 2027 by the NF-e layout. When true, a line's `valueCents` is the
139
+ * tax-inclusive price.
140
+ */
141
+ readonly taxInsidePrice: boolean;
142
+ readonly cbsBp: number;
143
+ readonly ibsUf: IbsUfRates;
144
+ readonly ibsMun: IbsMunRates;
145
+ }
146
+ /** A versioned rate table: DATA, loaded by the host, stamped on every result. */
147
+ interface RateTables {
148
+ readonly version: string;
149
+ readonly notes?: readonly string[];
150
+ /** The gorjeta's ceiling as a share of food and drink: 1500 (art. 274 par. único I). */
151
+ readonly gorjetaCapBp: number;
152
+ readonly gorjetaCapSource?: string;
153
+ /** The classes the excluded items are segregated under (410019, 410020). */
154
+ readonly exclusionClasses: {
155
+ readonly GORJETA: TaxClassCode;
156
+ readonly INTERMEDIATION: TaxClassCode;
157
+ readonly source?: string;
158
+ };
159
+ readonly specialRegimes: Readonly<Record<RegimeEspecifico, {
160
+ readonly reductionBp: number;
161
+ readonly source: string;
162
+ }>>;
163
+ readonly periods: readonly RatePeriod[];
164
+ }
165
+ /** Everything one computation needs. */
166
+ interface TaxInput {
167
+ readonly lines: readonly TaxLineInput[];
168
+ readonly seller: SellerProfile;
169
+ /**
170
+ * The 7-digit IBGE code of the place the IBS goes to: the establishment,
171
+ * or for a delivered good the place of delivery (art. 11 I).
172
+ */
173
+ readonly destinationIbge: string;
174
+ readonly exclusions: TaxExclusions;
175
+ readonly tables: RateTables;
176
+ /** The day of the supply; the rate is the rate of that day. */
177
+ readonly supplyDate: IsoDate;
178
+ }
179
+ /** Where an output line came from. */
180
+ type LineSource = "LINE" | "SERVICE_CHARGE" | "GORJETA_EXCLUDED" | "INTERMEDIATION_EXCLUDED";
181
+ /** The per-tax figures of one line. Rates are nominal; `reductionBp` applies to all three. */
182
+ interface LineFigures {
183
+ readonly reductionBp: number;
184
+ readonly cbsRateBp: number;
185
+ readonly cbsCents: number;
186
+ readonly ibsUfRateBp: number;
187
+ readonly ibsUfCents: number;
188
+ readonly ibsMunRateBp: number;
189
+ readonly ibsMunCents: number;
190
+ }
191
+ /** One output line — one NF-e item. */
192
+ interface LineTax extends LineFigures {
193
+ readonly lineId: string;
194
+ readonly source: LineSource;
195
+ readonly quantity: number;
196
+ /** The value as given (`vProd`). */
197
+ readonly valueCents: number;
198
+ /** The base the taxes are computed on (`vBC`): 0 on an excluded line. */
199
+ readonly taxBaseCents: number;
200
+ /** CBS + IBS-UF + IBS-Mun of the line. */
201
+ readonly taxCents: number;
202
+ /**
203
+ * The value without tax (`vProdLiq` = value − tax) in a `taxInsidePrice`
204
+ * period; `null` when the tax is not inside the value.
205
+ */
206
+ readonly netValueCents: number | null;
207
+ /**
208
+ * The unit value without tax (`vUnComLiq`), in reais with ten decimals as
209
+ * the layout writes it, within ±0,01 of `vProdLiq / qCom` (rule I11c-20);
210
+ * `null` when `netValueCents` is.
211
+ */
212
+ readonly netUnitValue: string | null;
213
+ /** The class snapshot (the table's exclusion class on an excluded line). */
214
+ readonly taxClass: TaxClass;
215
+ }
216
+ /** The breakdown of one supply. Every order figure is the sum of its rounded lines. */
217
+ interface TaxBreakdown {
218
+ readonly lines: readonly LineTax[];
219
+ readonly valueCents: number;
220
+ readonly taxBaseCents: number;
221
+ readonly cbsCents: number;
222
+ readonly ibsUfCents: number;
223
+ readonly ibsMunCents: number;
224
+ readonly ibsCents: number;
225
+ readonly totalTaxCents: number;
226
+ /** Σ `netValueCents` (`vProdLiqTot`), or `null` when the tax is not inside the values. */
227
+ readonly netValueCents: number | null;
228
+ readonly gorjetaExcludedCents: number;
229
+ readonly intermediationExcludedCents: number;
230
+ readonly regime: TaxRegime;
231
+ readonly treatment: TaxTreatment;
232
+ /**
233
+ * True when the figures are shown but not charged "por fora": the test year
234
+ * (2026), or a Simples store inside the DAS. False for a `NONE` treatment,
235
+ * which shows nothing.
236
+ */
237
+ readonly informative: boolean;
238
+ /** True when the period's figures are estimates, not law. */
239
+ readonly provisional: boolean;
240
+ /** Whether the line values were taken as tax-inclusive. */
241
+ readonly taxInsidePrice: boolean;
242
+ readonly supplyDate: IsoDate;
243
+ readonly destinationIbge: string;
244
+ readonly tablesVersion: string;
245
+ }
246
+
247
+ /**
248
+ * `computeTax` — the table mode. Pure: no I/O, no clock, no defaults. The
249
+ * same input gives the same breakdown, stamped with the table's version, so a
250
+ * supply settled in March reproduces its own tax in December after the tables
251
+ * moved.
252
+ */
253
+
254
+ /** The IBS/CBS breakdown of one supply, from the rate tables it is given. */
255
+ declare function computeTax(input: TaxInput): TaxBreakdown;
256
+
257
+ /**
258
+ * Everything the computation decides BEFORE a per-item figure is produced:
259
+ * the regime's treatment on the date, which items are segregated exclusions,
260
+ * each taxed item's reduction and base (`vBC`). Shared by the table mode and
261
+ * the oracle mode, so the two can only ever disagree on the per-item figures —
262
+ * the thing the oracle is there to check.
263
+ */
264
+
265
+ /** The three nominal rates at the destination. */
266
+ interface DestinationRates {
267
+ readonly cbsBp: number;
268
+ readonly ibsUfBp: number;
269
+ readonly ibsMunBp: number;
270
+ }
271
+ /** The three nominal rates of the period at the destination (art. 11 I). */
272
+ declare function ratesAt(period: RatePeriod, destinationIbge: string): DestinationRates;
273
+
274
+ /**
275
+ * The ORACLE mode: the same interface as `computeTax`, with the per-item
276
+ * figures asked of an injected `OfficialCalculator` — the port a host points
277
+ * at the official IBS/CBS calculator (the Receita Federal's Calculadora de
278
+ * Tributos, open source, with an HTTP API and an embeddable component).
279
+ * Everything else — the regime's treatment, the segregated exclusions, each
280
+ * item's base — is the engine's own plan, so running both modes over one
281
+ * fixture set checks exactly the rates, the reductions and the rounding
282
+ * against the official figures.
283
+ *
284
+ * In a tax-inside-price period the base is taken out of the price with the
285
+ * TABLE's rates (the calculator takes a base, not a price), and the
286
+ * calculator's taxes on that base give the net value.
287
+ */
288
+
289
+ /** One item, as the calculator is asked about it. */
290
+ interface OfficialCalculatorItemRequest {
291
+ readonly supplyDate: string;
292
+ readonly destinationIbge: string;
293
+ readonly cClassTrib: string;
294
+ readonly cstIbsCbs: string;
295
+ /** The base after the engine's exclusions (`vBC`). */
296
+ readonly taxBaseCents: number;
297
+ readonly quantity: number;
298
+ }
299
+ /** The calculator's answer for one item: nominal rates, the reduction, and the rounded taxes. */
300
+ type OfficialCalculatorItemAnswer = LineFigures;
301
+ /** The port. The host's adapter owns the transport, the retries and the unit conversion. */
302
+ interface OfficialCalculator {
303
+ /** Stamped on the result next to the tables' version. */
304
+ readonly version: string;
305
+ calculateItem(request: OfficialCalculatorItemRequest): Promise<OfficialCalculatorItemAnswer>;
306
+ }
307
+ /** `computeTax`, with the per-item figures from the official calculator. */
308
+ declare function computeTaxWithOracle(input: TaxInput, calculator: OfficialCalculator): Promise<TaxBreakdown>;
309
+
310
+ /**
311
+ * Where two breakdowns of the same supply disagree — the table mode against
312
+ * the oracle mode, or a stored snapshot against a recomputation. Versions are
313
+ * not compared: they differ by construction.
314
+ */
315
+
316
+ interface BreakdownDisagreement {
317
+ /** `null` for an order-level field. */
318
+ readonly lineId: string | null;
319
+ readonly field: string;
320
+ readonly left: unknown;
321
+ readonly right: unknown;
322
+ }
323
+ /** Every per-line field that differs, by line id; then the order fields that the lines do not already explain. */
324
+ declare function compareBreakdowns(left: TaxBreakdown, right: TaxBreakdown): BreakdownDisagreement[];
325
+
326
+ /**
327
+ * Every refusal the engine makes. A refusal is a THROW, on purpose: the
328
+ * engine has no fallback for an input it cannot read, and a figure computed
329
+ * from a guess would be printed on a fiscal document as a confession of the
330
+ * tax due (LC 214/2025 art. 60 §1).
331
+ */
332
+ type FiscalEngineErrorCode =
333
+ /** A field is missing, out of range or of the wrong shape. */
334
+ "INVALID_INPUT"
335
+ /** The rate table is malformed: a bad rate, a bad date, overlapping periods. */
336
+ | "INVALID_TABLES"
337
+ /** No period of the table covers the date of the supply. */
338
+ | "NO_RATE_PERIOD"
339
+ /** The supply precedes the seller's `regimeEffectiveFrom`. */
340
+ | "REGIME_NOT_IN_EFFECT"
341
+ /** The official calculator answered something that is not integer cents and basis points. */
342
+ | "INVALID_ORACLE_ANSWER";
343
+ declare class FiscalEngineError extends Error {
344
+ readonly code: FiscalEngineErrorCode;
345
+ constructor(code: FiscalEngineErrorCode, message: string);
346
+ }
347
+
348
+ /** round_half_even(baseCents × rateBp/10⁴ × (1 − reductionBp/10⁴)), in cents. */
349
+ declare function roundTaxCents(baseCents: number, rateBp: number, reductionBp: number): number;
350
+
351
+ /**
352
+ * Input and table validation. Every check names the field it refused, and
353
+ * every shape is checked before it is read, so a malformed input — a missing
354
+ * object, an `undefined` where `null` is required, a `null` line — is a
355
+ * `FiscalEngineError`, never a TypeError and never a NaN on a document.
356
+ */
357
+
358
+ /** Refuse a table the engine cannot trust: bad rates, bad dates, overlapping periods. */
359
+ declare function assertRateTables(tables: unknown): asserts tables is RateTables;
360
+
361
+ export { type BreakdownDisagreement, FiscalEngineError, type FiscalEngineErrorCode, type IbsMunRates, type IbsSphereRates, type IbsUfRates, type IsoDate, type LineFigures, type LineSource, type LineTax, type OfficialCalculator, type OfficialCalculatorItemAnswer, type OfficialCalculatorItemRequest, type RatePeriod, type RateTables, type RegimeEspecifico, type RetainedIntermediationInput, type SellerProfile, type ServiceChargeInput, type TaxBreakdown, type TaxClass, type TaxClassCode, type TaxExclusions, type TaxInput, type TaxLineInput, type TaxRegime, type TaxTreatment, assertRateTables, compareBreakdowns, computeTax, computeTaxWithOracle, ratesAt, roundTaxCents };