Currency-Adjusted Salary Comparator (Cost of Living) mechanism

Model scope

The core ratio is mathematically standard under matched-index and same-currency assumptions. Production use NEEDS_REVIEW because the specification names a Numbeo-style dataset but supplies no exact source, license, vintage, basket definition, normalization rule, or bundled table. The product should display the dataset name, edition or retrieval date, coverage limitations, interpolation policy, currency/FX policy, and the precise definition of percent difference. Labeling as an index-based educational estimate is appropriate and should remain prominent.

• The equivalent_salary formula is correct only when both indices use the same normalization, geographic scope, expenditure basket, and vintage: equivalent_salary = current_salary × target_index ÷ base_index.
• The % difference output is not defined in the specification. These vectors assume percent_difference = (equivalent_salary - current_salary) ÷ current_salary × 100.
• A lookup-table interpolation rule is not specified. The interpolation vector assumes linear interpolation between adjacent dated index rows.
• The specification does not state whether salaries must be entered in the same currency. Cost-of-living indices do not perform currency conversion; an FX rate is required when current and target salaries are denominated in different currencies.

Units and conventions

• Salary amounts are nominal monetary amounts in the same currency, here USD; the formula itself is currency-neutral only when both salary figures use the same currency.
• Cost-of-living indices are dimensionless relative indices with the same basket, geography definition, normalization, and data vintage.
• Index values use a base-city convention in which the reference city equals exactly 100.
• Percent difference is relative to the current salary, not relative to the equivalent target salary.
• For the interpolation vector, index values are assumed to vary linearly with the stated year.

Inspectable vector

One of 4 source-bound review vectors:

{
  "inputs": {
    "current_salary": 60000,
    "currency": "USD",
    "base_city": "Reference City",
    "base_index": 100,
    "target_city": "Reference City",
    "target_index": 100
  },
  "expected_outputs": {
    "equivalent_salary": 60000,
    "percent_difference": 0
  },
  "reference_data": {
    "base_city_index": {
      "city": "Reference City",
      "year": 2024,
      "index": 100
    },
    "target_city_index": {
      "city": "Reference City",
      "year": 2024,
      "index": 100
    },
    "source_convention": "Widely tabulated standard relative-index convention: reference city = 100; exact value is a normalization convention, not a universal city dataset entry."
  },
  "working": "equivalent_salary = 60,000 × (100 ÷ 100) = 60,000 × 1 = 60,000 USD.\npercent_difference = ((60,000 - 60,000) ÷ 60,000) × 100 = 0%."
}

Failure boundary

BREAK_CLAIMED · SELF_FLAGGED

A zero current-city index produces division by zero and must be rejected. The specification does not state validation behavior for zero or nonpositive indices, so an implementation that passes such values to the formula can return an error, infinity, or an invalid numeric result.

Other records

Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

• VERIFIED_LEDGER.json
• evidence-tranche7/tranche7-results.json
• BOUNDARY_HAZARD_CATALOG.json