@classytic/ca-tax 0.0.19 → 0.0.20

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.0.20] - 2026-09-09
+
+### Added — every shipped rate table declares its own provenance, and the declaration is enforced
+
+A new `@statutory-data` doc block on every module exporting a `RateBook` (and the two
+effective-dated rate tables) states its coverage years, sourcing status
+(`primary-sourced`/`partially-sourced`/`reference-only`), last-verified date, cited sources, and
+known gaps. `tests/statutory-data-provenance.test.ts` enforces four things a comment alone
+cannot: a new rate book cannot ship without the block; a cited vendored document must actually
+exist on disk; the declared `covers:` years must match the years the book actually ships (this
+one would have caught a real defect — every reference book in this package stops at 2024 while
+a host may already have registered 2026); and the roster of unsourced/unverified files is
+pinned, so provenance debt can shrink but never grow silently.
+
+Result of running the check against this package's own five rate books: general corporate rates,
+CCA rates, and the Québec CO-17 rate table are `partially-sourced` or `reference-only` and have
+never been checked against a primary document (`verified: never`); the 22-figure
+`PROVINCE_RATE_BOOK` (11 provinces × general + small-business) has zero sourced figures at all —
+the single largest provenance gap in the package. Alberta's rate stack and the GST/HST rate table
+are `primary-sourced` and dated. None of this changes any shipped rate value; it makes the
+package's real sourcing position visible and machine-checked rather than asserted in a comment
+that could go stale unnoticed.
+
+### Fixed — AT1 Schedule 21 line 059 cited no federal source at all
+
+Line 059's own printed caption reads "as reported on Federal Schedule 4 line 220" — the ABILs
+expired as non-capital losses — but the field carried no `from` reference, while line 057 right
+above it (current-year capital loss, from Schedule 4 line 210) did. The two are genuinely
+different federal lines; 059 now cites S4 220, pinned by a test asserting both citations point
+at their own line rather than one having been generalized onto the other.
+
+### Changed — Schedule 21's capital-loss pool columns now say GROSS in their own heading
+
+The column already carried a note warning that Schedule 12 wants the allowable half and that
+carrying the raw figure over-deducts by roughly two — the heading and all ten row captions in
+the pool now say "gross" up front, so a preparer reading the grid knows which figure the column
+holds before reaching that note.
+
 ## [0.0.19] - 2026-09-09
 
 ### Fixed — AT1 Schedule 12 was missing three mandatory computed lines entirely

package/dist/forms.mjs

@@ -3443,7 +3443,7 @@ const AT1_SCHEDULE_21_POOLS = [
 	},
 	{
 		key: "capital",
-		label: "Net capital losses",
+		label: "Net capital losses (Gross amount)",
 		carriedForward: "051",
 		windUpTransfer: "055",
 		currentYearLoss: "057",
@@ -3791,6 +3791,7 @@ const continuityFields = AT1_SCHEDULE_21_POOLS.flatMap((pool) => CONTINUITY_ORDE
 	const isAppliedLine = k === "appliedAgainstIncome";
 	const isOpening = k === "opening";
 	const isCurrentYearLoss = k === "currentYearLoss";
+	const isAbilExpired = k === "abilExpired";
 	let role = "input";
 	let from;
 	const closingFootnotes = {
@@ -3814,6 +3815,11 @@ const continuityFields = AT1_SCHEDULE_21_POOLS.flatMap((pool) => CONTINUITY_ORDE
 		line: pool.key === "farm" ? "310" : "410",
 		note: "Defaults to this federal figure — override only where Alberta genuinely diverges."
 	};
+	else if (isAbilExpired) from = {
+		form: "T2SCH4",
+		line: "220",
+		note: "Printed on the form: \"as reported on Federal Schedule 4 line 220\" — federal line 220 is \"ABILs expired as non-capital losses (line 215 multiplied by 2)\". An expiring ABIL leaves the non-capital pool and arrives here as a net capital loss."
+	};
 	else if (isCarryBack) role = "computed";
 	const footnoteMarks = isClosing ? closingFootnotes[pool.key] : void 0;
 	return {

package/dist/index3.d.mts

@@ -92,6 +92,23 @@ declare function resolveAlbertaTaxRates(taxYear: number, book?: RateBook<Alberta
  *   after 2020-06-30                          8.0%
  *
  * Pure, no I/O. Whole dollars.
+ *
+ * @statutory-data
+ *   covers:   2006-04-01 onward (effective-dated bands, not year-versioned)
+ *   status:   primary-sourced
+ *   verified: 2026-09-09
+ *   sources:
+ *     - research/sources/tra-spec/AT1-Chapter3-2026.4-full.txt §3.2.3.1 line 068
+ *       ("Basic Alberta Tax Payable"). The spec defines the day counts B–F and
+ *       their multipliers H–L; every band above is a transcription of that pair:
+ *         B  after 2006-03-31, before 2015-07-01   H = A x .100 x B/H
+ *         C  after 2015-06-30, before 2019-07-01   I = A x .120 x C/H
+ *         D  after 2019-06-30, before 2020-01-01   J = A x .110 x D/H
+ *         E  after 2019-12-31, before 2020-07-01   K = A x .100 x E/H
+ *         F  after 2020-06-30                      L = A x .080 x F/H
+ *       "Value = H + I + J + K + L. Round up at $.50 to the nearest dollar. If
+ *       the value is negative, default = zero." — the rounding and floor this
+ *       module implements.
  */
 interface GeneralRateBand {
   /** Inclusive start of the band, ISO `YYYY-MM-DD`. */

package/dist/t2.mjs

@@ -57,6 +57,23 @@ function extendRateBook(base, overrides) {
 * Never mutate a shipped year — add a new {@link RateBookEntry} to the host book.
 * A host wires future Alberta years / TRA-published values via the same
 * effective-dated seam the federal engine uses (see rates/rate-book.ts).
+*
+* @statutory-data
+*   book:     AB_TAX_RATE_BOOK
+*   covers:   2024
+*   status:   partially-sourced
+*   verified: 2026-09-09
+*   sources:
+*     - research/sources/tra-spec/AT1-Chapter3-2026.4-full.txt §3.2.3.1 line 068 —
+*       GENERAL_RATE 8%, as band F of the day-weighted table (`L = A x .080 x F/H`,
+*       days after 2020-06-30). See rates/general-rate-bands.ts for the full table.
+*     - research/sources/tra-spec/AT1-Chapter3-2026.4-full.txt §3.2.3.2 —
+*       BUSINESS_LIMIT $500,000, in effect since 2009-04-01.
+*   gaps:
+*     - SMALL_BUSINESS_RATE (2%) appears in NO vendored source. The AT1 spec states
+*       no small-business rate at all: its only rate multipliers are the five
+*       general-rate bands above. Verify against the Alberta Corporate Tax Act /
+*       TRA's published rate page before relying on it to file.
 */
 const AB_TAX_2024 = Object.freeze({
 	GENERAL_RATE: .08,
@@ -4442,6 +4459,23 @@ function albertaCurrentYearLoss(result) {
 *
 * Rates per CRA T4012 / ITR Schedule II. T2 CCA amounts are whole dollars (GIFI
 * convention), so the CCA calculator works in integer dollars — NOT cents.
+*
+* @statutory-data
+*   book:     CCA_RATE_BOOK
+*   covers:   2024
+*   status:   partially-sourced
+*   verified: never
+*   sources:
+*     - research/sources/legislation/ITR-section-1100-cca-deductions.txt —
+*       the Reg 1100(1) allowance rates these classes are drawn from.
+*     - research/sources/legislation/ITR-schedule-III-class-13-leasehold.txt —
+*       class 13, which is straight-line and deliberately NOT in this table.
+*   gaps:
+*     - The per-class rates are transcribed from ITR Schedule II, which is not
+*       vendored; ITR s.1100 above is the deduction mechanism, not the class list.
+*     - No class rate has been checked against a primary document on a recorded
+*       date. Class rates move rarely, so staleness is a lower risk here than in
+*       the year-tagged tax tables — but it is unmeasured, not measured-as-fine.
 */
 const CCA_DECLINING_BALANCE_RATES_2024 = Object.freeze({
 	"1": .04,
@@ -6196,6 +6230,28 @@ function federalSchedulePayloads(r) {
 *
 * Never mutate a shipped year — add a new {@link RateBookEntry} for the new
 * year (in the host book) so prior-year returns stay reproducible.
+*
+* @statutory-data
+*   book:     CORP_TAX_RATE_BOOK
+*   covers:   2024
+*   status:   partially-sourced
+*   verified: never
+*   sources:
+*     - research/sources/legislation/ITA-section-123.4-general-rate-reduction.txt —
+*       GENERAL_RATE_REDUCTION (13%).
+*     - research/sources/legislation/T4012-lines-638-639-general-tax-reduction.txt —
+*       the general tax reduction as CRA states it on the return.
+*     - research/sources/legislation/ITA-section-191.1-part-vi-1-tax.txt —
+*       the PART_VI_1_* rates.
+*   gaps:
+*     - The rate stack itself (BASIC_RATE 38%, FEDERAL_ABATEMENT 10%, SBD_RATE 19%)
+*       is transcribed from ITA s.123/124/125, which are NOT vendored.
+*     - The thresholds (BUSINESS_LIMIT, TC_GRIND_*, AAII_*, SRED_*) and the
+*       refundable fractions have no vendored source.
+*     - No value in this file has been checked against a primary document on a
+*       recorded date, which is what `verified: never` means. It is a REFERENCE
+*       table: a host filing a real return supplies CRA-published figures through
+*       CORP_TAX_RATE_BOOK.
 */
 const CORP_TAX_2024 = Object.freeze({
 	BASIC_RATE: .38,
@@ -6478,6 +6534,21 @@ function blendProvinceRateTable(baseTable, changes, periodStart, periodEnd) {
 * ⚠ REFERENCE VALUES for tax year 2024 — verify against each province's current
 * schedule before filing. They are year-versioned in {@link PROVINCE_RATE_BOOK}
 * so a host wires the authoritative figures without an engine change.
+*
+* @statutory-data
+*   book:     PROVINCE_RATE_BOOK
+*   covers:   2024
+*   status:   reference-only
+*   verified: never
+*   sources: none
+*   gaps:
+*     - All 22 figures (11 provinces × general + small-business) are unsourced.
+*       Each province legislates its own rate and publishes its own schedule;
+*       none of those are vendored, and several provinces have changed rates
+*       since 2024 — so these values are a plausible starting shape, not a
+*       filing authority, and the header above says so.
+*     - A host MUST supply its own PROVINCE_RATE_BOOK before filing a T2 with a
+*       Schedule 5. This is the single largest provenance gap in the package.
 */
 /** 2024 reference rates (general / small-business). Host overrides via the book. */
 const PROVINCE_RATES_2024 = Object.freeze({
@@ -9255,6 +9326,21 @@ function formatConformanceReport(summary) {
 * 2026-04-29 — wire that year via the rate book.
 *
 * Never mutate a shipped year — add a host rate-book entry for a new year.
+*
+* @statutory-data
+*   book:     QC_TAX_RATE_BOOK
+*   covers:   2024
+*   status:   reference-only
+*   verified: never
+*   sources: none
+*   gaps:
+*     - GENERAL_RATE (11.5%), SMALL_BUSINESS_RATE (3.2%), BUSINESS_LIMIT and
+*       SBD_HOURS_THRESHOLD (5,500) are transcribed from the Taxation Act (Québec)
+*       and Revenu Québec guidance, neither of which is vendored. The CO-17 forms
+*       under research/sources/rq-forms carry line captions, not rates.
+*     - The doc comment above notes the SBD rate rises (small-business rate 2.2%)
+*       for tax years beginning after 2026-04-29. That year is NOT in this book —
+*       resolving 2026 returns the 2024 entry. A host must wire it.
 */
 const QC_TAX_2024 = Object.freeze({
 	name: "Québec",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/ca-tax",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "Canadian corporate tax engine for @classytic/tax-core — federal T2, Alberta AT1 and Québec CO-17 with form definitions traced to the published forms, plus GST/HST/PST/QST with dated provincial regimes.",
   "type": "module",
   "license": "MIT",