# ADR-002: Acknowledge 'dual_write' naming collision between Mode_Manager and Feature_Flags FSMs

**Status:** Accepted — deferred rename  
**Date:** 2026-05-15  
**Deciders:** wpdev  

---

## Context

Two distinct FSMs in the codebase both use the string `'dual_write'`:

| FSM | Class | Constant | Stored in | Semantics |
|-----|-------|----------|-----------|-----------|
| Entity Bridge | `TMDO_Mode_Manager` | `MODE_DUAL_WRITE` | `wpdo_bridge_modes` | Writes go to both UAE flat table AND `wp_*meta` |
| Zone Migration | `TMDO_Feature_Flags` | `STATUS_DUAL_WRITE` | `wpdo_features` | Writes go to both Zone A/B/C table AND `wp_postmeta` |

The two FSMs are orthogonal — a post type can be in Zone `dual_write`
(actively migrating) while the Entity Bridge is in `aeav_only` mode, or vice
versa. The collision was introduced when the Entity Bridge FSM was added in
v2.5.x alongside the pre-existing Zone Migration FSM.

---

## Decision

**Defer the rename. Document the collision instead.**

Renaming either constant (e.g. Mode_Manager → `bridge_dual`) would require:

1. Updating ~85 call sites across 30+ files.
2. Writing a DB migration to translate stored option values (`'dual_write'` →
   `'bridge_dual'` in `wp_options['wpdo_bridge_modes']`).
3. Updating all WP-CLI commands that accept mode strings as user input.
4. Updating all admin UI dropdowns and confirmation messages.
5. Handling sites that run the old code against a DB that has already been
   migrated (or the reverse — new code on an un-migrated DB).

The risk of introducing bugs via a mechanical rename outweighs the naming
improvement at the current stage of the project.

The collision is mitigated by:
- A disambiguating docblock in `class-tmdo-mode-manager.php` (added 2026-05-15)
- This ADR, which explains the overlap to future developers
- The two FSMs operating on different option keys and being unreachable from
  each other's code paths

---

## Consequences

- **Future rename path**: When a DB migration is warranted (e.g. alongside
  another schema change), rename `MODE_DUAL_WRITE → 'bridge_dual'` and add a
  migration in `TMDO_Installer::maybe_upgrade()` that rewrites the stored string.
- **Linter**: If PHPStan or a custom rule ever flags string literal comparisons
  across FSMs, this ADR is the canonical explanation for why the overlap is
  intentional.

---

## Related

- `includes/engine/class-tmdo-mode-manager.php` — naming note in class docblock
- `includes/class-tmdo-feature-flags.php` — Zone FSM (7 states)
- P1-10 from full-review report (2026-05-15)