Source: https://guthlabs.ai/docs/instruments/roi-calculator/mechanism/

instrument mechanism / verified-clean

# ROI Calculator mechanism

The inspectable method record for ROI Calculator, kept separate from implementation and qualification.

Status: **VERIFIED_CLEAN**Lifecycle: **verified-clean**

## Model scope

The educational-only and not-investment-advice label is appropriate. Before release, rename or define "gain" explicitly as final_value, document that annualized ROI means CAGR, and enforce initial_cost>0, holding_period_years>0, and final_value>=0 for real-valued annualization.

- The input list provides initial cost and final value, but the formula uses an undefined variable named "gain". The standard formula with these inputs is ROI=(final_value-initial_cost)/initial_cost. The supplied formula is correct only if "gain" actually means final value, which is nonstandard terminology; if gain means profit, the supplied formula is incorrect.

- The annualized formula is a valid compound annual growth rate (CAGR) formula for one initial outflow and one final value: (1+ROI)^(1/years)-1. It is not a general annualized return formula for investments with interim cash flows or contributions.

- The specification does not state the required domain constraints initial_cost>0 and years>0, nor that final_value must be nonnegative for a real-valued annualized result.

## Units and conventions

- Initial cost and final value must use the same currency and price basis; currency conversion is not performed.

- Holding period is measured in years. For a six-month period, years must be entered as 0.5, not 6.

- ROI and annualized ROI are computed internally as decimal rates and displayed as percentages by multiplying by 100.

## Inspectable vector

One of 4 source-bound review vectors:

````
{
  "inputs": {
    "initial_cost": 1000,
    "final_value": 1200,
    "holding_period_years": 2
  },
  "expected_outputs": {
    "roi_percent": 20,
    "annualized_roi_percent": 9.544511501
  },
  "working": "ROI=(1200-1000)/1000=200/1000=0.20=20%. Annualized ROI=(1+0.20)^(1/2)-1=1.20^0.5-1=1.095445115-1=0.095445115=9.544511501%."
}
````

## Failure boundary

**BREAK_CLAIMED** · SELF_FLAGGED

An initial cost of zero makes the ROI denominator vanish, producing an undefined result. The specification does not state an input-validation rule, so the calculator must explicitly reject this case rather than emit Infinity or NaN.

## Other records

[01**Overview**](<https://guthlabs.ai/docs/instruments/roi-calculator/>)[03**Implementation**](<https://guthlabs.ai/docs/instruments/roi-calculator/implementation/>)[04**Qualification**](<https://guthlabs.ai/docs/instruments/roi-calculator/qualification/>)

## Sources and evidence

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

- `VERIFIED_LEDGER.json`

- `evidence-tranche4/tranche4-results.json`

- `BOUNDARY_HAZARD_CATALOG.json`