A financial metric needs a type, not just a number

A cash-flow dashboard can do the arithmetic perfectly and still compare the wrong things. One input might cover a quarter, another a year. Both might say “capex,” while one means cash equipment purchases and the other includes financed additions.

This matters when building tools around the AI infrastructure debate. A field called capex is too vague to protect the calculation. The data contract should carry the meaning you need to preserve.

A small contract

Here is an illustrative JavaScript guard. It is not an accounting engine or a complete filing parser. It accepts two observations only when their period, currency, units, identity and basis are compatible. It also requires the equipment outflow to be normalized as a positive magnitude; a parenthesized filing value must be handled explicitly by the ingestion layer.

function cashRemainder(operating, equipment) {
  for (const key of ['entity', 'start', 'end', 'currency', 'unit']) {
    if (!operating[key] || operating[key] !== equipment[key]) {
      throw new Error(`Incompatible ${key}`);
    }
  }
  if (operating.metric !== 'operating_cash' ||
      equipment.metric !== 'cash_ppe_additions') {
    throw new Error('Unsupported metric basis');
  }
  if (![operating.value, equipment.value].every(Number.isFinite) ||
      equipment.value < 0) {
    throw new Error('Normalize values before calculation');
  }
  if (!operating.sourceUrl || !equipment.sourceUrl) {
    throw new Error('Source required');
  }
  return {
    metric: 'operating_cash_less_cash_ppe',
    value: operating.value - equipment.value,
    entity: operating.entity,
    start: operating.start,
    end: operating.end,
    currency: operating.currency,
    unit: operating.unit,
    sources: [operating.sourceUrl, equipment.sourceUrl]
  };
}

The output name deliberately describes the subtraction. It does not silently rename the result “AI return,” “cash distributable to shareholders,” or an issuer's non-GAAP metric.

Test the mistakes, not only the happy path

Using illustrative values of 120 and 70, a compatible pair returns 50. More useful tests are the ones that must fail:

• Quarter versus year: different start dates.
• Millions versus billions: different units.
• Cash equipment purchases versus capex including financed additions: different metric basis.
• An outflow still stored as -70: normalization is missing.
• A value with no source: no evidence to inspect.

The checks do not verify that the source is correct. They prevent several easy ways of corrupting a comparison after extraction. Source review still has to confirm the financial statement, sign convention and reporting period.

Keep the remaining uncertainty visible

Store retrieval time separately from the period the observation describes. Fetching a June-quarter filing in October does not turn it into October operating performance. Likewise, if you later ingest a restatement, preserve the old observation and record which version your chart uses.

For missing inputs, return an explicit unavailable state upstream. Replacing a missing value with zero manufactures a conclusion. And keep lease disclosures available alongside the simple cash subtraction: the computation does not describe all financing obligations.

Microsoft's FY26 Q4 release and call are useful source material for testing this distinction between cash-flow rows and broader capex language:

• Cash-flow statement
• Earnings-call terminology

This is a proposed engineering pattern, not a claim that this exact function is deployed in Stock Expert AI. The illustrative guard was checked locally against one compatible input and five failure cases. Written with AI assistance and reviewed for source and code consistency.