@carbonbox/domain 0.51.0 → 0.52.0

package/build/carbonbox/emission-calculation-formulas/emission-factors/domain/entity/EmissionFactor.js

@@ -10,7 +10,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _EmissionFactor_code, _EmissionFactor_name, _EmissionFactor_description, _EmissionFactor_greenhouseGasValues, _EmissionFactor_informationSource, _EmissionFactor_ipccCode, _EmissionFactor_ipccSubcategory, _EmissionFactor_methodologicalTier;
+var _EmissionFactor_code, _EmissionFactor_name, _EmissionFactor_description, _EmissionFactor_greenhouseGasValues, _EmissionFactor_informationSource, _EmissionFactor_ipccCode, _EmissionFactor_ipccSubcategory, _EmissionFactor_methodologicalTier, _EmissionFactor_biogenicContent;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EmissionFactor = void 0;
 const AggregateRoot_1 = require("../../../../shared/domain/entities/AggregateRoot");
@@ -23,6 +23,9 @@ const EmissionFactorIpccCode_1 = require("../value-objects/EmissionFactorIpccCod
 const EmissionFactorIpccSubcategory_1 = require("../value-objects/EmissionFactorIpccSubcategory");
 const EmissionFactorMethodologicalTier_1 = require("../value-objects/EmissionFactorMethodologicalTier");
 const EmissionFactorName_1 = require("../value-objects/EmissionFactorName");
+const EmissionFactorBiogenicContent_1 = require("../value-objects/EmissionFactorBiogenicContent");
+const InconsistentEmissionFactorBiogenicContentError_1 = require("../exceptions/InconsistentEmissionFactorBiogenicContentError");
+const StandardGreenhouseGasSpecies_1 = require("../../../../shared/domain/enums/StandardGreenhouseGasSpecies");
 class EmissionFactor extends AggregateRoot_1.AggregateRoot {
     constructor(props, skipDomainValidation) {
         const id = skipDomainValidation
@@ -37,6 +40,7 @@ class EmissionFactor extends AggregateRoot_1.AggregateRoot {
         _EmissionFactor_ipccCode.set(this, void 0);
         _EmissionFactor_ipccSubcategory.set(this, void 0);
         _EmissionFactor_methodologicalTier.set(this, void 0);
+        _EmissionFactor_biogenicContent.set(this, void 0);
         if (skipDomainValidation === false) {
             // Initialize with domain validation
             __classPrivateFieldSet(this, _EmissionFactor_code, EmissionFactorCode_1.EmissionFactorCode.create(props.code), "f");
@@ -47,6 +51,8 @@ class EmissionFactor extends AggregateRoot_1.AggregateRoot {
             __classPrivateFieldSet(this, _EmissionFactor_ipccCode, EmissionFactorIpccCode_1.EmissionFactorIpccCode.create(props.ipccCode), "f");
             __classPrivateFieldSet(this, _EmissionFactor_ipccSubcategory, EmissionFactorIpccSubcategory_1.EmissionFactorIpccSubcategory.create(props.ipccSubcategory), "f");
             __classPrivateFieldSet(this, _EmissionFactor_methodologicalTier, EmissionFactorMethodologicalTier_1.EmissionFactorMethodologicalTier.create(props.methodologicalTier), "f");
+            __classPrivateFieldSet(this, _EmissionFactor_biogenicContent, EmissionFactorBiogenicContent_1.EmissionFactorBiogenicContent.create(props.biogenicContent), "f");
+            EmissionFactor.guardAgainstInconsistentBiogenicContent(__classPrivateFieldGet(this, _EmissionFactor_biogenicContent, "f"), __classPrivateFieldGet(this, _EmissionFactor_greenhouseGasValues, "f"));
         }
         else {
             // Initialize from primitives (no domain validation)
@@ -58,6 +64,7 @@ class EmissionFactor extends AggregateRoot_1.AggregateRoot {
             __classPrivateFieldSet(this, _EmissionFactor_ipccCode, EmissionFactorIpccCode_1.EmissionFactorIpccCode.fromPrimitives(props.ipccCode), "f");
             __classPrivateFieldSet(this, _EmissionFactor_ipccSubcategory, EmissionFactorIpccSubcategory_1.EmissionFactorIpccSubcategory.fromPrimitives(props.ipccSubcategory), "f");
             __classPrivateFieldSet(this, _EmissionFactor_methodologicalTier, EmissionFactorMethodologicalTier_1.EmissionFactorMethodologicalTier.fromPrimitives(props.methodologicalTier), "f");
+            __classPrivateFieldSet(this, _EmissionFactor_biogenicContent, EmissionFactorBiogenicContent_1.EmissionFactorBiogenicContent.fromPrimitives(props.biogenicContent), "f");
         }
     }
     static create(props) {
@@ -74,6 +81,7 @@ class EmissionFactor extends AggregateRoot_1.AggregateRoot {
             ipccCode: primitives.ipccCode,
             ipccSubcategory: primitives.ipccSubcategory,
             methodologicalTier: primitives.methodologicalTier,
+            biogenicContent: primitives.biogenicContent,
         };
         return new EmissionFactor(props, true);
     }
@@ -88,6 +96,7 @@ class EmissionFactor extends AggregateRoot_1.AggregateRoot {
             ipccCode: __classPrivateFieldGet(this, _EmissionFactor_ipccCode, "f").toPrimitives(),
             ipccSubcategory: __classPrivateFieldGet(this, _EmissionFactor_ipccSubcategory, "f").toPrimitives(),
             methodologicalTier: __classPrivateFieldGet(this, _EmissionFactor_methodologicalTier, "f").toEnum(),
+            biogenicContent: __classPrivateFieldGet(this, _EmissionFactor_biogenicContent, "f").toEnum(),
         };
     }
     get code() {
@@ -114,6 +123,39 @@ class EmissionFactor extends AggregateRoot_1.AggregateRoot {
     get methodologicalTier() {
         return __classPrivateFieldGet(this, _EmissionFactor_methodologicalTier, "f");
     }
+    get biogenicContent() {
+        return __classPrivateFieldGet(this, _EmissionFactor_biogenicContent, "f");
+    }
+    /**
+     * Coherencia entre el contenido biogénico declarado y las especies del factor
+     * (GHG Protocol cap. 9 / ISO 14064-1 §9.3.1): evita, p.ej., una leña cargada con `CO2` fósil
+     * (se sumaría al inventario) o una mezcla con biocombustible sin su `CO2-BIOGENIC`.
+     *   - NONE: no declara `CO2-BIOGENIC` ni `CH4-NON-FOSSIL`.
+     *   - FULL: no declara `CO2` ni `CH4-FOSSIL`, y declara `CO2-BIOGENIC` o `CH4-NON-FOSSIL`.
+     *   - PARTIAL: declara `CO2` y `CO2-BIOGENIC`.
+     * N2O y las especies de texto libre se aceptan con cualquier contenido.
+     */
+    static guardAgainstInconsistentBiogenicContent(biogenicContent, greenhouseGasValues) {
+        const declaredSpecies = greenhouseGasValues.toPrimitives().map((value) => value.greenhouseGasSpecies);
+        const declares = (species) => declaredSpecies.includes(species);
+        const forbiddenSpecies = [];
+        const missingSpecies = [];
+        if (biogenicContent.isNone()) {
+            forbiddenSpecies.push(...[StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CO2_BIOGENIC, StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CH4_NON_FOSSIL].filter(declares));
+        }
+        if (biogenicContent.isFull()) {
+            forbiddenSpecies.push(...[StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CO2, StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CH4_FOSSIL].filter(declares));
+            if (!declares(StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CO2_BIOGENIC) && !declares(StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CH4_NON_FOSSIL)) {
+                missingSpecies.push(`${StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CO2_BIOGENIC} or ${StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CH4_NON_FOSSIL}`);
+            }
+        }
+        if (biogenicContent.isPartial()) {
+            missingSpecies.push(...[StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CO2, StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CO2_BIOGENIC].filter((species) => !declares(species)));
+        }
+        if (forbiddenSpecies.length > 0 || missingSpecies.length > 0) {
+            throw InconsistentEmissionFactorBiogenicContentError_1.InconsistentEmissionFactorBiogenicContentError.create(biogenicContent.toEnum(), declaredSpecies, forbiddenSpecies, missingSpecies);
+        }
+    }
 }
 exports.EmissionFactor = EmissionFactor;
-_EmissionFactor_code = new WeakMap(), _EmissionFactor_name = new WeakMap(), _EmissionFactor_description = new WeakMap(), _EmissionFactor_greenhouseGasValues = new WeakMap(), _EmissionFactor_informationSource = new WeakMap(), _EmissionFactor_ipccCode = new WeakMap(), _EmissionFactor_ipccSubcategory = new WeakMap(), _EmissionFactor_methodologicalTier = new WeakMap();
+_EmissionFactor_code = new WeakMap(), _EmissionFactor_name = new WeakMap(), _EmissionFactor_description = new WeakMap(), _EmissionFactor_greenhouseGasValues = new WeakMap(), _EmissionFactor_informationSource = new WeakMap(), _EmissionFactor_ipccCode = new WeakMap(), _EmissionFactor_ipccSubcategory = new WeakMap(), _EmissionFactor_methodologicalTier = new WeakMap(), _EmissionFactor_biogenicContent = new WeakMap();

package/build/carbonbox/emission-calculation-formulas/emission-factors/domain/enums/BiogenicContent.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BiogenicContent = void 0;
+/**
+ * Biogenic carbon content of an emission factor
+ * Declares the carbon origin of the activity so the greenhouse gas species of the factor can be
+ * checked for coherence (GHG Protocol Corporate Standard cap. 9; ISO 14064-1:2018 §9.3.1)
+ */
+var BiogenicContent;
+(function (BiogenicContent) {
+    /**
+     * No biogenic carbon - fossil fuels, grid electricity, refrigerants, industrial processes.
+     * Must not declare `CO2-BIOGENIC` nor `CH4-NON-FOSSIL`
+     */
+    BiogenicContent["NONE"] = "NONE";
+    /**
+     * Fully biogenic carbon - biomass, organic waste, wastewater.
+     * Must not declare `CO2` nor `CH4-FOSSIL`, and must declare `CO2-BIOGENIC` or `CH4-NON-FOSSIL`
+     */
+    BiogenicContent["FULL"] = "FULL";
+    /**
+     * Fossil and biogenic carbon - fuels blended with biofuels.
+     * Must declare both `CO2` and `CO2-BIOGENIC`
+     */
+    BiogenicContent["PARTIAL"] = "PARTIAL";
+})(BiogenicContent || (exports.BiogenicContent = BiogenicContent = {}));

package/build/carbonbox/emission-calculation-formulas/emission-factors/domain/exceptions/InconsistentEmissionFactorBiogenicContentError.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InconsistentEmissionFactorBiogenicContentError = void 0;
+const CodedRootError_1 = require("../../../../shared/domain/exceptions/CodedRootError");
+const ErrorCode_1 = require("../../../../shared/domain/enums/ErrorCode");
+class InconsistentEmissionFactorBiogenicContentError extends CodedRootError_1.CodedRootError {
+    constructor(biogenicContent, declaredSpecies, forbiddenSpecies, missingSpecies) {
+        const problems = [];
+        if (forbiddenSpecies.length > 0) {
+            problems.push(`must not declare [${forbiddenSpecies.join(', ')}]`);
+        }
+        if (missingSpecies.length > 0) {
+            problems.push(`must declare [${missingSpecies.join(', ')}]`);
+        }
+        const technicalMessage = `Emission factor with biogenic content '${biogenicContent}' ${problems.join(' and ')} `
+            + `(declared species: [${declaredSpecies.join(', ')}]).`;
+        const context = {
+            biogenicContent,
+            declaredSpecies,
+            forbiddenSpecies,
+            missingSpecies,
+            timestamp: new Date().toISOString(),
+        };
+        const suggestions = [
+            'NONE (fossil fuels, grid electricity, refrigerants): use CO2 and CH4-FOSSIL, never CO2-BIOGENIC nor CH4-NON-FOSSIL',
+            'FULL (biomass, organic waste, wastewater): use CO2-BIOGENIC and/or CH4-NON-FOSSIL, never CO2 nor CH4-FOSSIL',
+            'PARTIAL (fuels blended with biofuels): split the carbon dioxide into CO2 (fossil share) and CO2-BIOGENIC (biofuel share)',
+            'N2O and non-standard species are allowed with any biogenic content',
+        ];
+        super(ErrorCode_1.ErrorCode.INCONSISTENT_EMISSION_FACTOR_BIOGENIC_CONTENT, technicalMessage, context, suggestions);
+        this.name = 'InconsistentEmissionFactorBiogenicContentError';
+    }
+    static create(biogenicContent, declaredSpecies, forbiddenSpecies, missingSpecies) {
+        return new InconsistentEmissionFactorBiogenicContentError(biogenicContent, declaredSpecies, forbiddenSpecies, missingSpecies);
+    }
+    logError() {
+        return `${this.name}: ${this.technicalMessage}`;
+    }
+}
+exports.InconsistentEmissionFactorBiogenicContentError = InconsistentEmissionFactorBiogenicContentError;

package/build/carbonbox/emission-calculation-formulas/emission-factors/domain/exceptions/InvalidBiogenicContentError.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidBiogenicContentError = void 0;
+const CodedRootError_1 = require("../../../../shared/domain/exceptions/CodedRootError");
+const ErrorCode_1 = require("../../../../shared/domain/enums/ErrorCode");
+class InvalidBiogenicContentError extends CodedRootError_1.CodedRootError {
+    constructor(receivedValue, validValues) {
+        const validValuesList = validValues.join(', ');
+        const technicalMessage = `Invalid biogenic content value '${receivedValue}': must be one of ${validValuesList}.`;
+        const context = {
+            receivedValue,
+            validValues,
+            validValuesList,
+            timestamp: new Date().toISOString(),
+        };
+        const suggestions = [
+            `Use one of the valid biogenic content values: ${validValuesList}`,
+            'Use NONE for fossil fuels, grid electricity, refrigerants and industrial processes',
+            'Use FULL for biomass, organic waste and wastewater',
+            'Use PARTIAL for fuels blended with biofuels',
+        ];
+        super(ErrorCode_1.ErrorCode.INVALID_BIOGENIC_CONTENT, technicalMessage, context, suggestions);
+        this.name = 'InvalidBiogenicContentError';
+    }
+    static create(receivedValue, validValues) {
+        return new InvalidBiogenicContentError(receivedValue, validValues);
+    }
+    logError() {
+        return `${this.name}: ${this.technicalMessage}`;
+    }
+}
+exports.InvalidBiogenicContentError = InvalidBiogenicContentError;

package/build/carbonbox/emission-calculation-formulas/emission-factors/domain/value-objects/EmissionFactorBiogenicContent.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmissionFactorBiogenicContent = void 0;
+const String_1 = require("../../../../shared/domain/value-objects/String");
+const BiogenicContent_1 = require("../enums/BiogenicContent");
+const InvalidBiogenicContentError_1 = require("../exceptions/InvalidBiogenicContentError");
+class EmissionFactorBiogenicContent extends String_1.String {
+    constructor(value, skipDomainValidation) {
+        super(value, skipDomainValidation, EmissionFactorBiogenicContent.PROPERTY_NAME);
+        if (skipDomainValidation === false) {
+            EmissionFactorBiogenicContent.validateBiogenicContent(value);
+        }
+    }
+    static create(value) {
+        String_1.String.guardAgainstEmptyValue(value, EmissionFactorBiogenicContent.PROPERTY_NAME);
+        String_1.String.guardAgainstInvalidType(value, EmissionFactorBiogenicContent.PROPERTY_NAME);
+        return new EmissionFactorBiogenicContent(value, false);
+    }
+    static fromPrimitives(primitive) {
+        return new EmissionFactorBiogenicContent(primitive, true);
+    }
+    /**
+     * Valida que el valor sea un contenido biogénico soportado.
+     */
+    static validateBiogenicContent(value) {
+        if (!EmissionFactorBiogenicContent.VALID_BIOGENIC_CONTENTS.includes(value)) {
+            throw InvalidBiogenicContentError_1.InvalidBiogenicContentError.create(value, EmissionFactorBiogenicContent.VALID_BIOGENIC_CONTENTS);
+        }
+    }
+    /**
+     * Obtiene los contenidos biogénicos válidos.
+     */
+    static getValidBiogenicContents() {
+        return Object.freeze([...EmissionFactorBiogenicContent.VALID_BIOGENIC_CONTENTS]);
+    }
+    /**
+     * Verifica si un valor es un contenido biogénico válido.
+     */
+    static isValidBiogenicContent(value) {
+        return EmissionFactorBiogenicContent.VALID_BIOGENIC_CONTENTS.includes(value);
+    }
+    isNone() {
+        return this.value === BiogenicContent_1.BiogenicContent.NONE;
+    }
+    isFull() {
+        return this.value === BiogenicContent_1.BiogenicContent.FULL;
+    }
+    isPartial() {
+        return this.value === BiogenicContent_1.BiogenicContent.PARTIAL;
+    }
+    toPrimitives() {
+        return this.value;
+    }
+    toEnum() {
+        return this.value;
+    }
+}
+exports.EmissionFactorBiogenicContent = EmissionFactorBiogenicContent;
+EmissionFactorBiogenicContent.PROPERTY_NAME = 'biogenicContent';
+EmissionFactorBiogenicContent.VALID_BIOGENIC_CONTENTS = Object.values(BiogenicContent_1.BiogenicContent);

package/build/carbonbox/emission-calculation-formulas/emission-factors/domain/value-objects/EmissionFactorGreenhouseGasValues.js

@@ -50,6 +50,8 @@ class EmissionFactorGreenhouseGasValues extends ValueObject_1.ValueObject {
         EmissionFactorGreenhouseGasValues.guardAgainstInvalidCategory(value.greenhouseGasCategory, `${propertyName}.greenhouseGasCategory`);
         // Normaliza + valida el código de especie (lanza si el formato es inválido).
         GreenhouseGasSpecies_1.GreenhouseGasSpecies.create(value.greenhouseGasSpecies);
+        // CO2 / CH4 / N2O solo aceptan sus especies estándar (p.ej. nada de `CH4` a secas).
+        GreenhouseGasSpecies_1.GreenhouseGasSpecies.guardAgainstCategoryMismatch(value.greenhouseGasCategory, value.greenhouseGasSpecies, `${propertyName}.greenhouseGasSpecies`);
         EmissionFactorGreenhouseGasValues.guardAgainstInvalidCountryValues(value.countryValues, `${propertyName}.countryValues`);
         EmissionFactorGreenhouseGasValues.guardAgainstInvalidUnit(value.unit, `${propertyName}.unit`);
         EmissionFactorGreenhouseGasValues.guardAgainstInvalidDataSource(value.dataSource, `${propertyName}.dataSource`);

package/build/carbonbox/emission-calculation-formulas/global-warming-potentials/domain/value-objects/GlobalWarmingPotentialGreenhouseGasPotentials.js

@@ -46,6 +46,8 @@ class GlobalWarmingPotentialGreenhouseGasPotentials extends ValueObject_1.ValueO
         GlobalWarmingPotentialGreenhouseGasPotentials.guardAgainstInvalidCategory(value.greenhouseGasCategory, `${propertyName}.greenhouseGasCategory`);
         // Normaliza + valida el código de especie (lanza si el formato es inválido).
         GreenhouseGasSpecies_1.GreenhouseGasSpecies.create(value.greenhouseGasSpecies);
+        // CO2 / CH4 / N2O solo aceptan sus especies estándar (p.ej. nada de `CH4` a secas).
+        GreenhouseGasSpecies_1.GreenhouseGasSpecies.guardAgainstCategoryMismatch(value.greenhouseGasCategory, value.greenhouseGasSpecies, `${propertyName}.greenhouseGasSpecies`);
         GlobalWarmingPotentialGreenhouseGasPotentials.guardAgainstInvalidPotentialValue(value.potentialValue, `${propertyName}.potentialValue`);
     }
     static guardAgainstInvalidCategory(category, propertyName) {

package/build/carbonbox/shared/domain/enums/ErrorCode.js

@@ -136,7 +136,7 @@ var ErrorCode;
     ErrorCode["INVALID_FORMULA"] = "CBX-EMC-003";
     ErrorCode["JOB_NOT_FOUND"] = "CBX-EMC-004";
     ErrorCode["JOB_ALREADY_RUNNING"] = "CBX-EMC-005";
-    // Emission Calculation Formulas Errors (CBX-EMC-006 to CBX-EMC-013)
+    // Emission Calculation Formulas Errors (CBX-EMC-006 to CBX-EMC-015)
     ErrorCode["INVALID_CALCULATION_VARIABLE_ACTIVITY_DATA_CONDITIONS_FOR_STRATEGY"] = "CBX-EMC-006";
     ErrorCode["INVALID_CALCULATION_VARIABLE_RESOLUTION_STRATEGY"] = "CBX-EMC-007";
     ErrorCode["DUPLICATE_GREENHOUSE_GAS"] = "CBX-EMC-008";
@@ -145,6 +145,8 @@ var ErrorCode;
     ErrorCode["UNAUTHORIZED_FORMULA_CREATION_ROLE"] = "CBX-EMC-011";
     ErrorCode["INVALID_IPCC_CODE"] = "CBX-EMC-012";
     ErrorCode["INVALID_METHODOLOGICAL_TIER"] = "CBX-EMC-013";
+    ErrorCode["INVALID_BIOGENIC_CONTENT"] = "CBX-EMC-014";
+    ErrorCode["INCONSISTENT_EMISSION_FACTOR_BIOGENIC_CONTENT"] = "CBX-EMC-015";
     // Emission Calculation Results Errors (CBX-ECR-XXX)
     ErrorCode["UNKNOWN_GREENHOUSE_GAS_CATEGORY"] = "CBX-ECR-001";
     // Reporting Errors (CBX-RPT-XXX)

package/build/carbonbox/shared/domain/enums/StandardGreenhouseGasSpecies.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StandardGreenhouseGasSpecies = void 0;
+/**
+ * Standard greenhouse gas species: the codes the system knows and gives meaning to.
+ * Any other species (refrigerants, blends, SF6, NF3...) is still accepted as free text
+ * by `GreenhouseGasSpecies`, but only under a category that has no standard species
+ * (HFC, PFC, SF6, NF3, HCFC, OTHER).
+ *
+ * Biogenic accounting (GHG Protocol Corporate Standard cap. 9; ISO 14064-1:2018 §9.3.1):
+ * only `CO2-BIOGENIC` stays outside the inventory total; `CH4-NON-FOSSIL` counts with its
+ * own potential (IPCC AR6: 27.0 vs 29.8 for fossil methane).
+ */
+var StandardGreenhouseGasSpecies;
+(function (StandardGreenhouseGasSpecies) {
+    /**
+     * Fossil carbon dioxide
+     */
+    StandardGreenhouseGasSpecies["CO2"] = "CO2";
+    /**
+     * Carbon dioxide from biomass / biofuel combustion: informational item outside the total
+     */
+    StandardGreenhouseGasSpecies["CO2_BIOGENIC"] = "CO2-BIOGENIC";
+    /**
+     * Methane of fossil origin
+     */
+    StandardGreenhouseGasSpecies["CH4_FOSSIL"] = "CH4-FOSSIL";
+    /**
+     * Methane of non-fossil origin (biomass, waste, wastewater): counts towards the total
+     */
+    StandardGreenhouseGasSpecies["CH4_NON_FOSSIL"] = "CH4-NON-FOSSIL";
+    /**
+     * Nitrous oxide
+     */
+    StandardGreenhouseGasSpecies["N2O"] = "N2O";
+})(StandardGreenhouseGasSpecies || (exports.StandardGreenhouseGasSpecies = StandardGreenhouseGasSpecies = {}));

package/build/carbonbox/shared/domain/value-objects/GreenhouseGasSpecies.js

@@ -3,18 +3,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GreenhouseGasSpecies = void 0;
 const String_1 = require("./String");
 const InvalidPropertyValueError_1 = require("../exceptions/InvalidPropertyValueError");
+const GreenhouseGasCategory_1 = require("../enums/GreenhouseGasCategory");
+const StandardGreenhouseGasSpecies_1 = require("../enums/StandardGreenhouseGasSpecies");
 /**
  * Código canónico de la especie de gas de efecto invernadero (p.ej. `CO2`, `CH4-FOSSIL`,
  * `R-410A`, `HFC-134A`). La especie es la llave real con la que se cruzan EmissionFactor y
  * GlobalWarmingPotential: por eso se normaliza al ingresar (trim + colapsar espacios + UPPERCASE)
  * para que un mismo refrigerante escrito con espacios/casing distintos matchee siempre igual.
- * La categoría (GreenhouseGasCategory) viaja al lado; aquí no se valida coherencia química
- * especie↔categoría (decisión de diseño: validación permisiva, match por especie).
+ *
+ * Especies estándar (`StandardGreenhouseGasSpecies`): `CO2`, `CO2-BIOGENIC`, `CH4-FOSSIL`,
+ * `CH4-NON-FOSSIL`, `N2O`. Las categorías CO2, CH4 y N2O SOLO aceptan sus especies estándar
+ * (`guardAgainstCategoryMismatch`); el resto de categorías (HFC, PFC, SF6, NF3, HCFC, OTHER)
+ * acepta texto libre (refrigerantes, mezclas).
  *
  * CO₂ biogénico: el CO₂ liberado al quemar biomasa o biocombustibles se reporta por separado,
  * fuera de los alcances y del total del inventario (GHG Protocol Corporate Standard cap. 9;
  * ISO 14064-1:2018 §9.3.1). Se modela como la especie `CO2-BIOGENIC` de la categoría CO2
- * (paralela a `CH4-BIOGENIC`, que SÍ cuenta en el total con su PCG). Este VO es el único lugar
+ * (paralela a `CH4-NON-FOSSIL`, que SÍ cuenta en el total con su PCG). Este VO es el único lugar
  * que conoce esa convención: toda suma de inventario pregunta `isBiogenicCarbonDioxide`.
  */
 class GreenhouseGasSpecies extends String_1.String {
@@ -39,6 +44,19 @@ class GreenhouseGasSpecies extends String_1.String {
         String_1.String.guardAgainstInvalidType(value, GreenhouseGasSpecies.PROPERTY_NAME);
         return value.trim().replace(/\s+/g, ' ').toUpperCase();
     }
+    /**
+     * True si la especie es una de las estándar (`StandardGreenhouseGasSpecies`).
+     */
+    static isStandard(value) {
+        return GreenhouseGasSpecies.STANDARD_SPECIES_CATEGORIES.has(GreenhouseGasSpecies.normalize(value));
+    }
+    /**
+     * Especies estándar de una categoría (vacío si la categoría acepta texto libre).
+     */
+    static standardSpeciesOf(category) {
+        return Object.values(StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies)
+            .filter((species) => GreenhouseGasSpecies.STANDARD_SPECIES_CATEGORIES.get(species) === category);
+    }
     /**
      * True para la especie `CO2-BIOGENIC` (en cualquier casing/espaciado): CO₂ que NO cuenta en
      * el total del inventario y se reporta como partida informativa.
@@ -46,9 +64,46 @@ class GreenhouseGasSpecies extends String_1.String {
     static isBiogenicCarbonDioxide(value) {
         return GreenhouseGasSpecies.normalize(value) === GreenhouseGasSpecies.BIOGENIC_CARBON_DIOXIDE;
     }
+    /**
+     * True para la especie `CH4-NON-FOSSIL`: metano de origen biogénico que SÍ cuenta en el total.
+     */
+    static isNonFossilMethane(value) {
+        return GreenhouseGasSpecies.normalize(value) === StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CH4_NON_FOSSIL;
+    }
+    /**
+     * True para las especies de carbono biogénico (`CO2-BIOGENIC`, `CH4-NON-FOSSIL`): las que un
+     * factor con contenido biogénico declara y una fórmula sobre ese factor no puede omitir.
+     */
+    static isBiogenic(value) {
+        return GreenhouseGasSpecies.isBiogenicCarbonDioxide(value) || GreenhouseGasSpecies.isNonFossilMethane(value);
+    }
+    /**
+     * Las categorías con especies estándar (CO2, CH4, N2O) solo aceptan esas especies, y cada
+     * especie estándar solo su propia categoría. Evita, p.ej., un `CH4` a secas (¿fósil o no fósil?).
+     */
+    static guardAgainstCategoryMismatch(category, species, propertyName) {
+        const normalizedSpecies = GreenhouseGasSpecies.normalize(species);
+        const standardCategory = GreenhouseGasSpecies.STANDARD_SPECIES_CATEGORIES.get(normalizedSpecies);
+        if (standardCategory !== undefined && standardCategory !== category) {
+            throw InvalidPropertyValueError_1.InvalidPropertyValueError.create(propertyName, `category ${standardCategory} for standard species ${normalizedSpecies}`, `"${category}"`);
+        }
+        const standardSpecies = GreenhouseGasSpecies.standardSpeciesOf(category);
+        if (standardSpecies.length > 0 && standardCategory === undefined) {
+            throw InvalidPropertyValueError_1.InvalidPropertyValueError.create(propertyName, `one of the standard species of category ${category} (${standardSpecies.join(', ')})`, `"${normalizedSpecies}"`);
+        }
+    }
     isBiogenicCarbonDioxide() {
         return GreenhouseGasSpecies.isBiogenicCarbonDioxide(this.value);
     }
+    isNonFossilMethane() {
+        return GreenhouseGasSpecies.isNonFossilMethane(this.value);
+    }
+    isBiogenic() {
+        return GreenhouseGasSpecies.isBiogenic(this.value);
+    }
+    isStandard() {
+        return GreenhouseGasSpecies.isStandard(this.value);
+    }
     static guardAgainstInvalidSpecies(value) {
         String_1.String.guardAgainstEmptyValue(value, GreenhouseGasSpecies.PROPERTY_NAME);
         if (!GreenhouseGasSpecies.SPECIES_REGEX.test(value)) {
@@ -61,7 +116,15 @@ class GreenhouseGasSpecies extends String_1.String {
 }
 exports.GreenhouseGasSpecies = GreenhouseGasSpecies;
 GreenhouseGasSpecies.PROPERTY_NAME = 'greenhouseGasSpecies';
-GreenhouseGasSpecies.BIOGENIC_CARBON_DIOXIDE = 'CO2-BIOGENIC';
+GreenhouseGasSpecies.BIOGENIC_CARBON_DIOXIDE = StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CO2_BIOGENIC;
 // Letras, dígitos, espacio, guion y barra: cubre ASHRAE (R-410A) y químicos/mezclas
 // (HFC-134A, MEZCLA HFC 365MFC/HFC 227EA, POLYCOLD 1102HC).
 GreenhouseGasSpecies.SPECIES_REGEX = /^[A-Z0-9][A-Z0-9 /-]*$/;
+// Categoría de cada especie estándar. Una categoría presente aquí solo acepta sus especies estándar.
+GreenhouseGasSpecies.STANDARD_SPECIES_CATEGORIES = new Map([
+    [StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CO2, GreenhouseGasCategory_1.GreenhouseGasCategory.CO2],
+    [StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CO2_BIOGENIC, GreenhouseGasCategory_1.GreenhouseGasCategory.CO2],
+    [StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CH4_FOSSIL, GreenhouseGasCategory_1.GreenhouseGasCategory.CH4],
+    [StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.CH4_NON_FOSSIL, GreenhouseGasCategory_1.GreenhouseGasCategory.CH4],
+    [StandardGreenhouseGasSpecies_1.StandardGreenhouseGasSpecies.N2O, GreenhouseGasCategory_1.GreenhouseGasCategory.N2O],
+]);