Disclosure: this is an AI-generated technical example from the SIGNUM HQ team. The share counts below are synthetic. They are not market observations, and the function is not presented as our production code.

Assume the inputs already use the same security, observation window, unit and revision. Under that assumption, an OTC share percentage can use ATS plus non-ATS shares over consolidated shares. A missing component remains unknown.

from decimal import Decimal

def otc_percent(ats, non_ats, consolidated):
    if any(x is None for x in (ats, non_ats, consolidated)):
        return None
    if not all(isinstance(x, int) and not isinstance(x, bool)
               for x in (ats, non_ats, consolidated)):
        raise ValueError("integer share counts required")
    if min(ats, non_ats) < 0 or consolidated <= 0:
        raise ValueError("invalid volume")
    if ats + non_ats > consolidated:
        raise ValueError("coverage or window mismatch")
    return Decimal(100) * Decimal(ats + non_ats) / Decimal(consolidated)

In the synthetic example, 20 ATS shares plus 30 non-ATS shares against 100 consolidated shares produce 50%. Zero plus zero against a positive denominator produces 0%. Missing ATS volume produces no percentage. Those last two states should not collapse into one.

The local exercise checks eight cases: a valid ratio, observed zero, a missing component, a zero denominator, components exceeding the total, negative volume, a Boolean and a fractional share count. Reproduction: running the example file under Python 3.9.6 on my machine printed otc_denominator: 8 cases passed.

Rejecting a result above 100% is a diagnostic, not permission to clamp it to 100%. The periods, coverage, adjustment or revision may be inconsistent. The function also cannot detect a mismatch that happens to produce a plausible result; the assumptions must be validated upstream.

FINRA distinguishes ATS and non-ATS data and publishes observations with reporting delays. A weekly observation cannot become today's intraday signal merely because it was downloaded today. Nor does the execution venue alone identify buying intent or accumulation.

Reference: FINRA OTC data fields and publication dates.

Product context: a free page that checks a reading of off-exchange share against observed FINRA data (no login, no AI calls): Does this reading hold up?

The symptom

On a single day the calendar had these English events:

• Durable Goods Orders MoM
• Durable Goods Orders Ex Transp MoM
• Durable Goods Orders Ex Defense MoM

All three came out as the same translated name. To a reader that looks like the same number printed three times, when they are three different series with three different values.

I then captured the whole public calendar (106 events at the time) and ran every name through the translator. 12 events collided with another event on the same date. Others in the same family:

• Retail Sales vs Retail Sales Ex Autos vs Retail Sales Ex Gas/Autos
• Retail Inventories vs Retail Inventories Ex Autos
• Unemployment Rate vs U-6 Unemployment Rate
• GDP vs GDP Price Index
• Initial Jobless Claims vs Jobless Claims 4-Week Average

The cause

The translator is an ordered list of rules. Each rule is a regex plus the localized name, and the first rule that matches wins. The variants above had no rule of their own, so the general rule caught all of them:

// simplified
const RULES = [
  { match: /durable goods orders/i, ko: '내구재 주문' },   // swallows Ex Transp, Ex Defense, ...
];

Nothing crashes. The output is a plausible-looking string, just the wrong one, which is the worst kind of bug in a localization layer.

Two other traps in the same area

Suffixes carry the meaning. MoM, YoY, QoQ (rate of change versus a level), Ex Autos, Ex Defense, and the reporting period (Sep) or (Oct/16) are not noise. If you strip them to "normalize" the name, you merge events that should stay separate. An earlier change had already started preserving the qualifiers in localized names; this one finished the job for the remaining families.

Fix the locale you are fixing. After the change, English output went through a code path that re-spaced CamelCase names and one feed value (FedWallerSpeech, no spaces) leaked through raw. The English and "translation off" path must behave exactly as before; I restored it and added it to the tests.

The fix

1. Add explicit rules for the specific variants (ex transp, ex defense, ex gas/autos, ex autos, u-6, price index, 4-week average) and keep them before the general ones, because the first match wins.
2. Add a test that does not depend on me remembering which events exist: capture the real public calendar once, translate every name, and assert that no two events on the same date map to the same localized name, for each locale.

for (const locale of ['ko', 'ja']) {
  const seen = new Map();                       // key: date + localized name
  for (const ev of capturedCalendar.events) {
    const key = ev.date + '|' + localize(ev.event, locale);
    assert(!seen.has(key), `collision: ${seen.get(key)} / ${ev.event}`);
    seen.set(key, ev.event);
  }
}

The captured file is a snapshot of the real production names, so the test fails the day a new vendor event name collides, instead of the day a user screenshots it.

What I would tell my past self

• In an ordered-rule system, order is part of the logic. Write a test that checks uniqueness of outputs, not just that each input maps somewhere.
• Test against captured production data, not just hand-written examples. My examples always looked fine.
• A wrong translation is more damaging than an untranslated name. A user can read the English, but they cannot know the Korean is wrong.

I build this in SIGNUM HQ, a solo-developer US-stock app (options flow, dark pool prints, earnings calendar).

Disclosure: I used an AI assistant to help draft and edit this post. The bug, the fix and the conclusions come from my own project.