Jira progress: loading…

GHG-NACE

Supply Chain Carbon Engine

1. Identity

Loading identity…

Depends on module:

Purpose
...

ZAYAZ GHG Spend Engine Developer Pack v1

This pack contains the formal developer-ready extension for the Country Similarity & Inheritance Layer (CSIL) and the NACE-Specific Country Adjustment Model (NSCAM) for MEID_CALC_GHG_SPEND_NACE_v1.

Included artifacts

• schema.sql
• openapi.yaml
• seed_templates.csv
• test_cases.json

---

schema.sql

-- ZAYAZ Developer Pack v1
-- Engine: MEID_CALC_GHG_SPEND_NACE_v1
-- Extension: Country Similarity & Inheritance Layer (CSIL)
-- Extension: NACE-Specific Country Adjustment Model (NSCAM)
-- Canonical unit: tCO2e_per_musd
-- Canonical currency: USD
-- Price basis: real_2022

BEGIN;

CREATE EXTENSION IF NOT EXISTS "pgcrypto";

CREATE TABLE IF NOT EXISTS dim_nace (
    nace_id BIGSERIAL PRIMARY KEY,
    nace_code VARCHAR(16) NOT NULL,
    nace_rev VARCHAR(10) NOT NULL DEFAULT '2.1',
    nace_level SMALLINT NOT NULL,
    nace_title TEXT NOT NULL,
    parent_nace_code VARCHAR(16),
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    valid_from DATE,
    valid_to DATE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE (nace_code, nace_rev)
);

CREATE INDEX IF NOT EXISTS idx_dim_nace_code ON dim_nace(nace_code);
CREATE INDEX IF NOT EXISTS idx_dim_nace_parent ON dim_nace(parent_nace_code);

CREATE TABLE IF NOT EXISTS dim_region (
    region_id BIGSERIAL PRIMARY KEY,
    region_code VARCHAR(20) NOT NULL UNIQUE,
    region_name TEXT NOT NULL,
    region_type VARCHAR(20) NOT NULL,
    parent_region_code VARCHAR(20),
    iso2_code VARCHAR(2),
    iso3_code VARCHAR(3),
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_dim_region_parent ON dim_region(parent_region_code);

CREATE TABLE IF NOT EXISTS dim_currency (
    currency_code VARCHAR(3) PRIMARY KEY,
    currency_name TEXT NOT NULL,
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE IF NOT EXISTS dim_source_dataset (
    source_dataset_id BIGSERIAL PRIMARY KEY,
    source_key VARCHAR(50) NOT NULL UNIQUE,
    source_name TEXT NOT NULL,
    source_version VARCHAR(50),
    source_url TEXT,
    methodology_notes TEXT,
    default_quality_grade VARCHAR(10),
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE IF NOT EXISTS src_sector_intensity_raw (
    raw_factor_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    source_dataset_id BIGINT NOT NULL REFERENCES dim_source_dataset(source_dataset_id),
    source_sector_code VARCHAR(64) NOT NULL,
    source_sector_name TEXT NOT NULL,
    source_region_code VARCHAR(20),
    source_year INT,
    ghg_value NUMERIC(20,8) NOT NULL,
    ghg_unit VARCHAR(50) NOT NULL,
    currency_code VARCHAR(3),
    price_basis VARCHAR(30),
    ghg_scope_boundary VARCHAR(40),
    uncertainty_p25 NUMERIC(20,8),
    uncertainty_p75 NUMERIC(20,8),
    metadata_json JSONB,
    ingested_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_src_sector_raw_dataset
    ON src_sector_intensity_raw(source_dataset_id);

CREATE INDEX IF NOT EXISTS idx_src_sector_raw_sector
    ON src_sector_intensity_raw(source_sector_code);

CREATE INDEX IF NOT EXISTS idx_src_sector_raw_region_year
    ON src_sector_intensity_raw(source_region_code, source_year);

CREATE TABLE IF NOT EXISTS xwalk_nace_to_source_sector (
    xwalk_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    nace_code VARCHAR(16) NOT NULL,
    nace_rev VARCHAR(10) NOT NULL DEFAULT '2.1',
    source_dataset_id BIGINT NOT NULL REFERENCES dim_source_dataset(source_dataset_id),
    source_sector_code VARCHAR(64) NOT NULL,
    mapping_method VARCHAR(30) NOT NULL,
    mapping_weight NUMERIC(10,6) NOT NULL DEFAULT 1.0,
    mapping_confidence NUMERIC(5,4) NOT NULL DEFAULT 0.7000,
    notes TEXT,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_xwalk_nace_code
    ON xwalk_nace_to_source_sector(nace_code, nace_rev);

CREATE INDEX IF NOT EXISTS idx_xwalk_source_sector
    ON xwalk_nace_to_source_sector(source_dataset_id, source_sector_code);

CREATE TABLE IF NOT EXISTS fact_ghg_intensity_harmonized (
    factor_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    library_version VARCHAR(30) NOT NULL,
    nace_code VARCHAR(16) NOT NULL,
    nace_rev VARCHAR(10) NOT NULL DEFAULT '2.1',
    region_code VARCHAR(20) NOT NULL,
    reporting_year INT NOT NULL,
    boundary VARCHAR(40) NOT NULL DEFAULT 'supply_chain_avg',
    canonical_unit VARCHAR(40) NOT NULL DEFAULT 'tco2e_per_musd',
    canonical_currency_code VARCHAR(3) NOT NULL DEFAULT 'USD',
    price_basis VARCHAR(30) NOT NULL DEFAULT 'real_2022',
    median_value NUMERIC(20,8) NOT NULL,
    p25_value NUMERIC(20,8),
    p75_value NUMERIC(20,8),
    min_value NUMERIC(20,8),
    max_value NUMERIC(20,8),
    standard_deviation NUMERIC(20,8),
    confidence_score NUMERIC(5,4) NOT NULL,
    quality_grade VARCHAR(10) NOT NULL,
    source_blend_method VARCHAR(50) NOT NULL,
    fallback_level VARCHAR(30) NOT NULL,
    lineage_hash VARCHAR(128) NOT NULL,
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    valid_from DATE NOT NULL,
    valid_to DATE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE (library_version, nace_code, nace_rev, region_code, reporting_year, boundary)
);

CREATE INDEX IF NOT EXISTS idx_fact_ghg_lookup
    ON fact_ghg_intensity_harmonized(library_version, nace_code, region_code, reporting_year, boundary);

CREATE INDEX IF NOT EXISTS idx_fact_ghg_region_year
    ON fact_ghg_intensity_harmonized(region_code, reporting_year);

CREATE TABLE IF NOT EXISTS fact_ghg_intensity_lineage (
    lineage_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    factor_id UUID NOT NULL REFERENCES fact_ghg_intensity_harmonized(factor_id) ON DELETE CASCADE,
    source_dataset_id BIGINT NOT NULL REFERENCES dim_source_dataset(source_dataset_id),
    source_sector_code VARCHAR(64) NOT NULL,
    source_region_code VARCHAR(20),
    source_year INT,
    mapping_method VARCHAR(30) NOT NULL,
    mapping_weight NUMERIC(10,6),
    transformed_value NUMERIC(20,8),
    original_unit VARCHAR(50),
    transformation_notes TEXT,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_lineage_factor ON fact_ghg_intensity_lineage(factor_id);

CREATE OR REPLACE VIEW vw_ghg_intensity_best_available AS
SELECT *
FROM fact_ghg_intensity_harmonized
WHERE is_active = TRUE
  AND valid_to IS NULL;

CREATE TABLE IF NOT EXISTS dim_country_profile (
    country_code VARCHAR(20) PRIMARY KEY,
    country_name TEXT NOT NULL,
    macro_region_code VARCHAR(20),
    income_band VARCHAR(20),
    industrialization_band VARCHAR(20),
    trade_dependence_band VARCHAR(20),
    electricity_grid_intensity_index NUMERIC(10,6),
    manufacturing_share_index NUMERIC(10,6),
    heavy_industry_index NUMERIC(10,6),
    services_share_index NUMERIC(10,6),
    agriculture_share_index NUMERIC(10,6),
    logistics_import_dependence_index NUMERIC(10,6),
    infrastructure_maturity_index NUMERIC(10,6),
    energy_exporter_index NUMERIC(10,6),
    urbanization_index NUMERIC(10,6),
    data_completeness_score NUMERIC(5,4),
    profile_version VARCHAR(30) NOT NULL,
    valid_from DATE NOT NULL,
    valid_to DATE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE IF NOT EXISTS country_similarity_score (
    similarity_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    source_country_code VARCHAR(20) NOT NULL,
    target_country_code VARCHAR(20) NOT NULL,
    geography_score NUMERIC(5,4) NOT NULL,
    grid_intensity_score NUMERIC(5,4) NOT NULL,
    industrial_structure_score NUMERIC(5,4) NOT NULL,
    income_score NUMERIC(5,4) NOT NULL,
    trade_profile_score NUMERIC(5,4) NOT NULL,
    infrastructure_score NUMERIC(5,4) NOT NULL,
    composite_similarity_score NUMERIC(5,4) NOT NULL,
    similarity_method VARCHAR(50) NOT NULL,
    similarity_version VARCHAR(30) NOT NULL,
    valid_from DATE NOT NULL,
    valid_to DATE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE (source_country_code, target_country_code, similarity_version)
);

CREATE INDEX IF NOT EXISTS idx_country_similarity_target
    ON country_similarity_score(target_country_code, similarity_version, composite_similarity_score DESC);

CREATE TABLE IF NOT EXISTS nace_adjustment_archetype (
    archetype_code VARCHAR(40) PRIMARY KEY,
    archetype_name TEXT NOT NULL,
    description TEXT,
    version VARCHAR(30) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE IF NOT EXISTS nace_adjustment_profile (
    nace_code VARCHAR(16) NOT NULL,
    nace_rev VARCHAR(10) NOT NULL DEFAULT '2.1',
    archetype_code VARCHAR(40) REFERENCES nace_adjustment_archetype(archetype_code),
    grid_intensity_weight NUMERIC(10,6) NOT NULL DEFAULT 0,
    heavy_industry_weight NUMERIC(10,6) NOT NULL DEFAULT 0,
    manufacturing_weight NUMERIC(10,6) NOT NULL DEFAULT 0,
    services_weight NUMERIC(10,6) NOT NULL DEFAULT 0,
    agriculture_weight NUMERIC(10,6) NOT NULL DEFAULT 0,
    logistics_weight NUMERIC(10,6) NOT NULL DEFAULT 0,
    trade_dependence_weight NUMERIC(10,6) NOT NULL DEFAULT 0,
    infrastructure_weight NUMERIC(10,6) NOT NULL DEFAULT 0,
    adjustment_profile_version VARCHAR(30) NOT NULL,
    valid_from DATE NOT NULL,
    valid_to DATE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    PRIMARY KEY (nace_code, nace_rev, adjustment_profile_version)
);

CREATE TABLE IF NOT EXISTS country_nace_similarity_score (
    nace_similarity_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    source_country_code VARCHAR(20) NOT NULL,
    target_country_code VARCHAR(20) NOT NULL,
    nace_code VARCHAR(16) NOT NULL,
    nace_rev VARCHAR(10) NOT NULL DEFAULT '2.1',
    baseline_similarity_score NUMERIC(5,4) NOT NULL,
    sector_adjustment_score NUMERIC(5,4) NOT NULL,
    final_similarity_score NUMERIC(5,4) NOT NULL,
    sector_adjustment_method VARCHAR(50) NOT NULL,
    similarity_version VARCHAR(30) NOT NULL,
    valid_from DATE NOT NULL,
    valid_to DATE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE (source_country_code, target_country_code, nace_code, nace_rev, similarity_version)
);

CREATE INDEX IF NOT EXISTS idx_country_nace_similarity_target
    ON country_nace_similarity_score(target_country_code, nace_code, similarity_version, final_similarity_score DESC);

CREATE TABLE IF NOT EXISTS country_reference_set (
    reference_set_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    target_country_code VARCHAR(20) NOT NULL,
    nace_code VARCHAR(16) NOT NULL,
    nace_rev VARCHAR(10) NOT NULL DEFAULT '2.1',
    proxy_class VARCHAR(10) NOT NULL,
    inheritance_method VARCHAR(50) NOT NULL,
    composite_similarity_score NUMERIC(5,4) NOT NULL,
    base_uncertainty_uplift_pct NUMERIC(10,4) NOT NULL,
    reference_set_version VARCHAR(30) NOT NULL,
    valid_from DATE NOT NULL,
    valid_to DATE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE (target_country_code, nace_code, nace_rev, reference_set_version)
);

CREATE INDEX IF NOT EXISTS idx_country_reference_set_target
    ON country_reference_set(target_country_code, nace_code, reference_set_version);

CREATE TABLE IF NOT EXISTS country_reference_set_member (
    reference_member_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    reference_set_id UUID NOT NULL REFERENCES country_reference_set(reference_set_id) ON DELETE CASCADE,
    reference_country_code VARCHAR(20) NOT NULL,
    weight NUMERIC(10,6) NOT NULL,
    final_similarity_score NUMERIC(5,4) NOT NULL,
    adjustment_multiplier NUMERIC(12,6) NOT NULL DEFAULT 1.0,
    uncertainty_uplift_pct NUMERIC(10,4) NOT NULL DEFAULT 0.0,
    role_code VARCHAR(30),
    notes TEXT,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_country_reference_member_set
    ON country_reference_set_member(reference_set_id);

CREATE TABLE IF NOT EXISTS fact_ghg_intensity_inherited (
    inherited_factor_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    library_version VARCHAR(30) NOT NULL,
    target_country_code VARCHAR(20) NOT NULL,
    nace_code VARCHAR(16) NOT NULL,
    nace_rev VARCHAR(10) NOT NULL DEFAULT '2.1',
    reporting_year INT NOT NULL,
    boundary VARCHAR(40) NOT NULL,
    canonical_unit VARCHAR(40) NOT NULL DEFAULT 'tco2e_per_musd',
    canonical_currency_code VARCHAR(3) NOT NULL DEFAULT 'USD',
    price_basis VARCHAR(30) NOT NULL DEFAULT 'real_2022',
    median_value NUMERIC(20,8) NOT NULL,
    p25_value NUMERIC(20,8),
    p75_value NUMERIC(20,8),
    inheritance_method VARCHAR(50) NOT NULL,
    proxy_class VARCHAR(10) NOT NULL,
    direct_factor_available BOOLEAN NOT NULL DEFAULT FALSE,
    composite_similarity_score NUMERIC(5,4) NOT NULL,
    total_adjustment_multiplier NUMERIC(12,6) NOT NULL,
    total_uncertainty_uplift_pct NUMERIC(10,4) NOT NULL,
    confidence_score NUMERIC(5,4) NOT NULL,
    quality_grade VARCHAR(10) NOT NULL,
    lineage_hash VARCHAR(128) NOT NULL,
    valid_from DATE NOT NULL,
    valid_to DATE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE (library_version, target_country_code, nace_code, nace_rev, reporting_year, boundary)
);

CREATE INDEX IF NOT EXISTS idx_fact_ghg_inherited_lookup
    ON fact_ghg_intensity_inherited(library_version, target_country_code, nace_code, reporting_year, boundary);

CREATE TABLE IF NOT EXISTS fact_ghg_intensity_inherited_lineage (
    inherited_lineage_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    inherited_factor_id UUID NOT NULL REFERENCES fact_ghg_intensity_inherited(inherited_factor_id) ON DELETE CASCADE,
    reference_country_code VARCHAR(20) NOT NULL,
    reference_factor_id UUID,
    weight NUMERIC(10,6) NOT NULL,
    baseline_similarity_score NUMERIC(5,4) NOT NULL,
    nace_adjusted_similarity_score NUMERIC(5,4) NOT NULL,
    adjustment_multiplier NUMERIC(12,6) NOT NULL,
    uncertainty_uplift_pct NUMERIC(10,4) NOT NULL,
    rule_notes TEXT,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_fact_ghg_inherited_lineage
    ON fact_ghg_intensity_inherited_lineage(inherited_factor_id);

CREATE TABLE IF NOT EXISTS calc_ghg_spend_estimate (
    estimate_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    estimation_timestamp TIMESTAMP NOT NULL DEFAULT NOW(),
    eco_number VARCHAR(32),
    supplier_id VARCHAR(64),
    supplier_name TEXT,
    supplier_nace_code VARCHAR(16),
    supplier_country_code VARCHAR(20),
    spend_amount NUMERIC(20,4) NOT NULL,
    spend_currency_code VARCHAR(3) NOT NULL,
    spend_amount_usd NUMERIC(20,8) NOT NULL,
    reporting_year INT NOT NULL,
    invoice_date DATE,
    factor_id UUID,
    inherited_factor_id UUID,
    factor_library_version VARCHAR(30) NOT NULL,
    factor_nace_used VARCHAR(16) NOT NULL,
    factor_region_used VARCHAR(20) NOT NULL,
    factor_value_tco2e_per_musd NUMERIC(20,8) NOT NULL,
    estimated_emissions_tco2e NUMERIC(20,8) NOT NULL,
    uncertainty_p25_tco2e NUMERIC(20,8),
    uncertainty_p75_tco2e NUMERIC(20,8),
    method_code VARCHAR(50) NOT NULL DEFAULT 'spend_based_eeio',
    scope3_category_code VARCHAR(50),
    mapping_method VARCHAR(30),
    fallback_level VARCHAR(30),
    proxy_class VARCHAR(10),
    confidence_score NUMERIC(5,4) NOT NULL,
    quality_grade VARCHAR(10) NOT NULL,
    lineage_hash VARCHAR(128),
    request_payload_json JSONB,
    response_payload_json JSONB,
    created_by_engine VARCHAR(100) NOT NULL DEFAULT 'MEID_CALC_GHG_SPEND_NACE_v1',
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    CONSTRAINT chk_calc_factor_ref_present CHECK (factor_id IS NOT NULL OR inherited_factor_id IS NOT NULL)
);

CREATE INDEX IF NOT EXISTS idx_calc_ghg_supplier ON calc_ghg_spend_estimate(supplier_id);
CREATE INDEX IF NOT EXISTS idx_calc_ghg_year ON calc_ghg_spend_estimate(reporting_year);
CREATE INDEX IF NOT EXISTS idx_calc_ghg_scope3 ON calc_ghg_spend_estimate(scope3_category_code);

CREATE TABLE IF NOT EXISTS calc_ghg_spend_estimate_lineage (
    estimate_lineage_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    estimate_id UUID NOT NULL REFERENCES calc_ghg_spend_estimate(estimate_id) ON DELETE CASCADE,
    factor_id UUID,
    inherited_factor_id UUID,
    lineage_hash VARCHAR(128),
    rule_path TEXT,
    notes TEXT,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_calc_est_lineage_estimate
    ON calc_ghg_spend_estimate_lineage(estimate_id);

CREATE TABLE IF NOT EXISTS mice_engine_registry (
    engine_id VARCHAR(100) PRIMARY KEY,
    engine_name TEXT NOT NULL,
    readable_name TEXT,
    domain VARCHAR(50) NOT NULL,
    input_type VARCHAR(50) NOT NULL,
    primary_functions JSONB NOT NULL,
    supported_modes JSONB NOT NULL,
    status VARCHAR(20) NOT NULL,
    mode_docs_url TEXT,
    metric_types_supported JSONB,
    zayaz_input_source_type VARCHAR(100),
    default_config JSONB,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

INSERT INTO mice_engine_registry (
    engine_id, engine_name, readable_name, domain, input_type,
    primary_functions, supported_modes, status, metric_types_supported,
    zayaz_input_source_type, default_config
)
VALUES (
    'MEID_CALC_GHG_SPEND_NACE_v1',
    'Spend-Based GHG by NACE Engine',
    'GHG Spend Factor Engine',
    'GHG',
    'json',
    '["scope3_estimation","spend_based_emissions","factor_lookup","uncertainty_estimation","country_inheritance"]'::jsonb,
    '["estimate","estimate_with_lineage","estimate_with_uncertainty"]'::jsonb,
    'active',
    '["scope3_purchased_goods_and_services","scope3_upstream_transport","procurement_emissions"]'::jsonb,
    'invoice_or_procurement_record',
    '{"active_factor_library_version":"2026.04","active_similarity_version":"2026.04","confidence_block_threshold":0.55}'::jsonb
)
ON CONFLICT (engine_id) DO NOTHING;

COMMIT;

---

openapi.yaml

openapi: 3.1.0
info:
  title: ZAYAZ GHG Spend Engine API
  version: 1.0.0
  description: >
    API specification for the ZAYAZ spend-based GHG estimation engine
    (MEID_CALC_GHG_SPEND_NACE_v1), including country inheritance and
    NACE-specific adjustment support.
servers:
  - url: https://api.zayaz.io
tags:
  - name: Estimation
  - name: Factors
  - name: ReferenceSets
paths:
  /api/mice/MEID_CALC_GHG_SPEND_NACE_v1:
    post:
      tags: [Estimation]
      summary: Estimate spend-based GHG emissions
      operationId: estimateSpendBasedGhg
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EstimateRequest'
      responses:
        '200':
          description: Estimation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimateResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Factor not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Confidence below policy threshold
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/ghg/factors/resolve:
    get:
      tags: [Factors]
      summary: Resolve best available factor for country and NACE
      operationId: resolveFactor
      parameters:
        - in: query
          name: country_code
          required: true
          schema: { type: string }
        - in: query
          name: nace_code
          required: true
          schema: { type: string }
        - in: query
          name: reporting_year
          required: true
          schema: { type: integer }
        - in: query
          name: boundary
          required: false
          schema:
            type: string
            default: supply_chain_avg
        - in: query
          name: factor_library_version
          required: false
          schema:
            type: string
            default: active
      responses:
        '200':
          description: Resolved factor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedFactorResponse'
        '404':
          description: Factor not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/ghg/reference-sets/{target_country_code}/{nace_code}:
    get:
      tags: [ReferenceSets]
      summary: Retrieve sector-aware country reference set
      operationId: getReferenceSet
      parameters:
        - in: path
          name: target_country_code
          required: true
          schema: { type: string }
        - in: path
          name: nace_code
          required: true
          schema: { type: string }
        - in: query
          name: reference_set_version
          required: false
          schema:
            type: string
            default: active
      responses:
        '200':
          description: Country reference set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferenceSetResponse'
        '404':
          description: Reference set not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    EstimateRequest:
      type: object
      required:
        - supplier_nace_code
        - supplier_country_code
        - spend_amount
        - spend_currency_code
        - reporting_year
      properties:
        request_id:
          type: string
        eco_number:
          type: string
        supplier_id:
          type: string
        supplier_name:
          type: string
        supplier_nace_code:
          type: string
        supplier_country_code:
          type: string
        spend_amount:
          type: number
          exclusiveMinimum: 0
        spend_currency_code:
          type: string
          minLength: 3
          maxLength: 3
        invoice_date:
          type: string
          format: date
        reporting_year:
          type: integer
        scope3_category_code:
          type: string
          default: purchased_goods_and_services
        factor_library_version:
          type: string
          default: active
        boundary:
          type: string
          default: supply_chain_avg
        return_lineage:
          type: boolean
          default: true
        return_uncertainty:
          type: boolean
          default: true

    EstimateResponse:
      type: object
      required:
        - estimate_id
        - engine_id
        - engine_version
        - input
        - normalized_input
        - result
        - factor_used
        - created_at
      properties:
        request_id:
          type: string
        estimate_id:
          type: string
          format: uuid
        engine_id:
          type: string
        engine_version:
          type: string
        input:
          $ref: '#/components/schemas/EstimateInput'
        normalized_input:
          type: object
          properties:
            spend_amount_usd:
              type: number
        result:
          type: object
          required: [estimated_emissions_tco2e, method_code]
          properties:
            estimated_emissions_tco2e:
              type: number
            method_code:
              type: string
            scope3_category_code:
              type: string
        factor_used:
          $ref: '#/components/schemas/FactorUsed'
        uncertainty:
          $ref: '#/components/schemas/Uncertainty'
        inheritance:
          $ref: '#/components/schemas/Inheritance'
        lineage:
          $ref: '#/components/schemas/Lineage'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Warning'
        created_at:
          type: string
          format: date-time

    EstimateInput:
      type: object
      properties:
        supplier_id:
          type: string
        supplier_nace_code:
          type: string
        supplier_country_code:
          type: string
        spend_amount:
          type: number
        spend_currency_code:
          type: string
        reporting_year:
          type: integer

    FactorUsed:
      type: object
      required:
        - factor_library_version
        - factor_nace_used
        - factor_region_used
        - factor_value_tco2e_per_musd
        - canonical_unit
        - boundary
        - confidence_score
        - quality_grade
      properties:
        factor_id:
          type: string
          format: uuid
          nullable: true
        inherited_factor_id:
          type: string
          format: uuid
          nullable: true
        factor_library_version:
          type: string
        factor_nace_used:
          type: string
        factor_region_used:
          type: string
        factor_value_tco2e_per_musd:
          type: number
        canonical_unit:
          type: string
        boundary:
          type: string
        mapping_method:
          type: string
        fallback_level:
          type: string
        confidence_score:
          type: number
        quality_grade:
          type: string
        proxy_class:
          type: string
          nullable: true
        direct_factor_available:
          type: boolean
          nullable: true

    Uncertainty:
      type: object
      properties:
        p25_tco2e:
          type: number
        p75_tco2e:
          type: number

    Inheritance:
      type: object
      nullable: true
      properties:
        inheritance_method:
          type: string
        composite_similarity_score:
          type: number
        total_adjustment_multiplier:
          type: number
        total_uncertainty_uplift_pct:
          type: number
        reference_countries:
          type: array
          items:
            $ref: '#/components/schemas/ReferenceCountry'

    ReferenceCountry:
      type: object
      properties:
        country_code:
          type: string
        weight:
          type: number
        baseline_similarity_score:
          type: number
        nace_adjusted_similarity_score:
          type: number
        adjustment_multiplier:
          type: number
        uncertainty_uplift_pct:
          type: number

    Lineage:
      type: object
      properties:
        lineage_hash:
          type: string
        rule_path:
          type: string

    Warning:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

    ResolvedFactorResponse:
      type: object
      properties:
        country_code:
          type: string
        nace_code:
          type: string
        reporting_year:
          type: integer
        boundary:
          type: string
        resolved_source:
          type: string
          enum: [harmonized_direct, inherited, parent_inherited, regional_fallback]
        factor:
          $ref: '#/components/schemas/FactorUsed'
        inheritance:
          $ref: '#/components/schemas/Inheritance'
        lineage:
          $ref: '#/components/schemas/Lineage'

    ReferenceSetResponse:
      type: object
      properties:
        target_country_code:
          type: string
        nace_code:
          type: string
        reference_set_version:
          type: string
        proxy_class:
          type: string
        inheritance_method:
          type: string
        composite_similarity_score:
          type: number
        base_uncertainty_uplift_pct:
          type: number
        members:
          type: array
          items:
            $ref: '#/components/schemas/ReferenceCountry'

    ErrorResponse:
      type: object
      required: [error_code, message]
      properties:
        error_code:
          type: string
        message:
          type: string
        details:
          type: object
          additionalProperties: true

---

seed_templates.csv

table_name,template_group,version,key_1,key_2,key_3,field_name,sample_value,notes
dim_region,base,2026.04,GLOBAL,,,,region_name,Global,Global aggregate region
dim_region,base,2026.04,EEA,,,,parent_region_code,GLOBAL,Regional fallback example
dim_country_profile,country_profile,2026.04,NOR,,,,electricity_grid_intensity_index,0.120000,Low-carbon grid example
dim_country_profile,country_profile,2026.04,ALB,,,,manufacturing_share_index,0.410000,Target country structural profile
nace_adjustment_archetype,archetype,2026.04,heavy_industry,,,,description,High grid/heavy industry sensitivity,Archetype seed
nace_adjustment_profile,nace_profile,2026.04,C24,2.1,,,archetype_code,heavy_industry,Steel/metals example
nace_adjustment_profile,nace_profile,2026.04,C24,2.1,,,grid_intensity_weight,0.300000,Weights should sum to ~1.0
country_similarity_score,country_similarity,2026.04,GRC,ALB,,,composite_similarity_score,0.790000,Baseline country similarity
country_nace_similarity_score,country_nace_similarity,2026.04,GRC,ALB,C24,final_similarity_score,0.810000,NACE-adjusted similarity
country_reference_set,reference_set,2026.04,ALB,C24,,,proxy_class,C,Weighted multi-reference example
country_reference_set_member,reference_set_member,2026.04,ALB,C24,GRC,weight,0.450000,Reference member weight
country_reference_set_member,reference_set_member,2026.04,ALB,C24,BGR,weight,0.350000,Reference member weight
country_reference_set_member,reference_set_member,2026.04,ALB,C24,HRV,weight,0.200000,Reference member weight
fact_ghg_intensity_harmonized,direct_factor,2026.04,GRC,C24,2025,median_value,1650.00000000,Direct reference factor example
fact_ghg_intensity_harmonized,direct_factor,2026.04,BGR,C24,2025,median_value,1820.00000000,Direct reference factor example
fact_ghg_intensity_harmonized,direct_factor,2026.04,HRV,C24,2025,median_value,1580.00000000,Direct reference factor example
fact_ghg_intensity_inherited,inherited_factor,2026.04,ALB,C24,2025,median_value,1719.20000000,Computed inherited factor example
mice_engine_registry,engine,2026.04,MEID_CALC_GHG_SPEND_NACE_v1,,,,status,active,Runtime engine registration

---

test_cases.json

{
  "engine_id": "MEID_CALC_GHG_SPEND_NACE_v1",
  "engine_version": "1.0.0",
  "test_cases": [
    {
      "id": "TC001_direct_country_child_nace_hit",
      "description": "Exact country + child NACE direct factor exists and should be used without inheritance.",
      "request": {
        "supplier_nace_code": "C24.10",
        "supplier_country_code": "NOR",
        "spend_amount": 1000000,
        "spend_currency_code": "USD",
        "reporting_year": 2025,
        "boundary": "supply_chain_avg"
      },
      "expected": {
        "http_status": 200,
        "resolved_source": "harmonized_direct",
        "warnings": [],
        "factor_used": {
          "proxy_class": null
        }
      }
    },
    {
      "id": "TC002_inherited_country_nace_hit",
      "description": "No direct ALB C24 child factor; inherited ALB C24 factor should be used.",
      "request": {
        "supplier_nace_code": "C24.10",
        "supplier_country_code": "ALB",
        "spend_amount": 2500000,
        "spend_currency_code": "EUR",
        "reporting_year": 2025,
        "boundary": "supply_chain_avg",
        "return_lineage": true,
        "return_uncertainty": true
      },
      "expected": {
        "http_status": 200,
        "resolved_source": "inherited",
        "factor_used": {
          "factor_nace_used": "C24",
          "factor_region_used": "ALB",
          "proxy_class": "C"
        },
        "inheritance": {
          "inheritance_method": "weighted_multi_ref",
          "reference_countries_count": 3
        },
        "warnings_contains": [
          "PARENT_FALLBACK_USED",
          "INHERITED_FACTOR_USED"
        ]
      }
    },
    {
      "id": "TC003_parent_nace_inherited_hit",
      "description": "Child NACE missing in inherited layer, but parent NACE inherited factor exists.",
      "request": {
        "supplier_nace_code": "J62.01",
        "supplier_country_code": "MKD",
        "spend_amount": 300000,
        "spend_currency_code": "EUR",
        "reporting_year": 2025
      },
      "expected": {
        "http_status": 200,
        "resolved_source": "parent_inherited",
        "factor_used": {
          "fallback_level": "country_parent_nace"
        }
      }
    },
    {
      "id": "TC004_global_fallback",
      "description": "No direct or inherited factor exists; runtime falls back to regional/global harmonized factor.",
      "request": {
        "supplier_nace_code": "A03.11",
        "supplier_country_code": "FJI",
        "spend_amount": 900000,
        "spend_currency_code": "USD",
        "reporting_year": 2025
      },
      "expected": {
        "http_status": 200,
        "resolved_source": "regional_fallback",
        "warnings_contains": [
          "GLOBAL_FALLBACK_USED"
        ]
      }
    },
    {
      "id": "TC005_low_confidence_block",
      "description": "Best available factor confidence below platform threshold should be blocked when policy is enabled.",
      "request": {
        "supplier_nace_code": "B05",
        "supplier_country_code": "SSD",
        "spend_amount": 500000,
        "spend_currency_code": "USD",
        "reporting_year": 2025
      },
      "expected": {
        "http_status": 422,
        "error_code": "LOW_CONFIDENCE_FACTOR_BLOCKED"
      }
    },
    {
      "id": "TC006_invalid_currency",
      "description": "Unsupported currency code returns validation error.",
      "request": {
        "supplier_nace_code": "C24",
        "supplier_country_code": "DEU",
        "spend_amount": 1000,
        "spend_currency_code": "ZZZ",
        "reporting_year": 2025
      },
      "expected": {
        "http_status": 400,
        "error_code": "UNSUPPORTED_CURRENCY"
      }
    },
    {
      "id": "TC007_non_positive_spend",
      "description": "Spend amount must be greater than zero.",
      "request": {
        "supplier_nace_code": "C24",
        "supplier_country_code": "DEU",
        "spend_amount": 0,
        "spend_currency_code": "USD",
        "reporting_year": 2025
      },
      "expected": {
        "http_status": 400,
        "error_code": "INVALID_REQUEST"
      }
    },
    {
      "id": "TC008_reference_set_lookup",
      "description": "Reference set endpoint returns members and similarity metadata.",
      "request": {
        "method": "GET",
        "path": "/api/ghg/reference-sets/ALB/C24?reference_set_version=2026.04"
      },
      "expected": {
        "http_status": 200,
        "proxy_class": "C",
        "members_count": 3
      }
    },
    {
      "id": "TC009_factor_resolution_endpoint",
      "description": "Factor resolution endpoint returns inherited factor metadata without calculation.",
      "request": {
        "method": "GET",
        "path": "/api/ghg/factors/resolve?country_code=ALB&nace_code=C24&reporting_year=2025&boundary=supply_chain_avg"
      },
      "expected": {
        "http_status": 200,
        "resolved_source": "inherited"
      }
    },
    {
      "id": "TC010_lineage_persistence",
      "description": "Every successful estimate must persist estimate lineage with rule path.",
      "request": {
        "supplier_nace_code": "C24.10",
        "supplier_country_code": "ALB",
        "spend_amount": 1200000,
        "spend_currency_code": "EUR",
        "reporting_year": 2025,
        "return_lineage": true
      },
      "expected": {
        "http_status": 200,
        "lineage_required": true,
        "rule_path_required": true
      }
    }
  ]
}

---