# Grandfathered Records

This document records prod data rows whose values intentionally violate a
current invariant or schema convention because they pre-date a tightening of
the rule, and where the business has decided to **leave them in place rather
than rewrite history**.

Grandfathered rows are tolerated by the runtime via env-var escape hatches
(typically `AUTONUMBER_SEED_TOLERATE_LEGACY=true` for autonumber-related
exceptions; see `infra/ecs.tf` and `infra/entrypoint.sh`). The deploy comes up
clean; the `cmd/setup verify` invariants log these rows as WARN instead of
failing closed.

When you see a `cmd/setup verify` warning that mentions one of the rows below,
**do not file a new bug** — the exception is documented and accepted.

## Schema

| Field | Description |
|-------|-------------|
| Object | The SObject the row belongs to |
| Id / business key | Stable identifier (Id when known, otherwise a business field) |
| Violated rule | Which invariant / convention this row trips |
| Reason for grandfathering | Why we accepted instead of fixing |
| Decided | Date + decision-maker / issue link |
| Tolerated by | Env var, code path, or other mechanism that suppresses the failure |
| Future review | When (if ever) this exception should be revisited |

---

## Records

*No current entries.*

The original entry (2 legacy 2024 Contract.Name rows `IDMA-24020501` and
`USMA-24020502`) was removed on 2026-04-22: the rows were renamed to the
v2-compliant format (`ID-MA-24020501` and `US-MA-24020502`) per
`data-specs/2026-04-22-rename-legacy-contract-names.md`. The business
accepted the downstream-reference risk that had originally motivated
grandfathering. The `AUTONUMBER_SEED_TOLERATE_LEGACY=true` flag remains set
on prod as a safety net but has nothing to tolerate today.

---

## Adding a new entry

1. Confirm the row pre-dates the invariant being tripped (use `git blame` on the
   spec file or the field metadata to find when the rule was added).
2. Confirm the business has explicitly decided **not** to rewrite the row (vs.
   rename / fix / delete).
3. Add a section above with all 7 fields filled in. Cite the issue / PR where
   the decision was made.
4. Reference this doc from the data-spec or runbook that explains the WARN, so
   future audits land here.

## When to remove an entry

- The row is fixed / renamed / deleted (the invariant no longer trips).
- The invariant itself is removed or relaxed so the row is no longer
  "grandfathered" but simply normal.
- Business changes its mind and approves a rewrite — leave the entry but mark
  `~~strikethrough~~` with the date until the cleanup spec lands.