ADR-3: Replace PB fee waive flag with a Zero scheme override

Date: 31/07/2026 Author(s): David McNair

Status

Accepted

Context

Partner–Brand “no fee” today is a boolean (no_partner_issuance_fee). That flag is not a real Transaction Fee Scheme, has no Management Hub edit surface aligned with other fee overrides, and cannot participate in a single Partner–Brand override model alongside Competitive Requirement and Premium. Reloadable Commercials / TFS override work (FOUND-1533) needs one override shape so sale-time resolution and MH commercials stay coherent.

Downstream relationship and sale exports may still expose the legacy field. Dropping it or rewriting historical export contracts before consumers are checked would risk breaking those contracts.

Decision

We will replace the PB waive boolean with a Competitive Requirement override pointing at a normal catalogue Zero TFS (Flat, or Percentage whose parameters guarantee a zero fee), so there is one override model.

During migration, sale-time fee resolution treats a complete Competitive Requirement pair as authoritative, whether its TFS is zero or non-zero. The legacy waive flag is a fallback only when no current PB override pair exists; a legacy-only waive still resolves to zero.

We will not drop the flag or rewrite historical export contracts until consumers of relationship/sale exports are confirmed not to depend on the old field; then migrate remaining rows and retire the boolean. An MH apply, replace, or clear transition clears the legacy flag for that PB without dropping the column or bulk-migrating remaining legacy-only rows.

An active PB override must be cleared or re-pointed before its TFS is retired. Zero TFSs are provisioned through the existing MH catalogue surface in this slice; production use is not dependent on the demo-only permanent seeder.

Consequences

Positive

• One PB override model for no-fee and other Competitive Requirement rates
• Zero fee is a real catalogue TFS, so a waived PB participates in the same override model (scheme + reason) as any other Competitive Requirement rate
• Dual-read keeps fees correct while exports and data consumers are checked
• Sale provenance stamps the override reason only (not scheme identity) — see ADR-0005

Negative

• Temporary dual-path complexity in sale-time resolution until the flag is retired
• Ops/data must confirm export consumers before the boolean can be removed
• Catalogue Zero scheme(s) must be provisioned before waive-via-scheme is usable in MH