AA-Events/docs/superpowers/specs/2026-07-28-local-acf-override-compatibility-design.md

Local ACF Override Compatibility Design

Problem

AA Events suppresses its built-in ACF field group when the MNBC theme's local field group is enabled. The theme group stores repeating dates under multiple_dates and returns dates and times as F j, Y and g:i a. The plugin's occurrence reader only reads event_dates and strictly parses Y-m-d dates and 24-hour times. As a result, the plugin detects the local group as an override but cannot turn its schedule values into occurrences, so the events do not appear in schedule-driven views.

Scope

This change makes the plugin compatible with the existing MNBC schedule fields and normalizes the theme's local ACF JSON to the documented AA Events schedule contract. It does not rename or otherwise change unrelated cost, location, or contact fields.

Plugin Compatibility

aa_events_get_occurrences() will use schedule sources in this order:

1. The canonical event_dates repeater when it contains rows.
2. The legacy local-override multiple_dates repeater when it contains rows.
3. The existing event_datetime fallback.
4. The existing standalone date and start_time fallback.

Canonical rows take precedence when both repeaters contain data. Legacy multiple_dates rows will normalize to the same public occurrence shape as canonical rows, without adding a new public source type.

The occurrence parsing boundary will accept the plugin's canonical return formats and the formats emitted by the existing theme override:

• Dates: Y-m-d, compact ACF Ymd, and F j, Y.
• Times: H:i:s, H:i, and g:i a.

All accepted values will be normalized to Y-m-d and H:i:s before existing range validation, sorting, and rendering logic runs. Invalid or ambiguous values will continue to be rejected rather than guessed.

Metadata-change synchronization will recognize both repeater names and their schedule subfields. ACF value-cache flushing will include multiple_dates, so direct metadata changes cannot leave stale canonical occurrence indexes.

Theme ACF JSON

The MNBC theme field group at wp-content/themes/MNBC/acf/group_69fb58894f83f.json will be updated as follows:

• Rename the repeater field from multiple_dates to event_dates, retaining its stable ACF field key.
• Change the standalone and repeater Date fields' return format to Y-m-d.
• Change the standalone and repeater Start Time and End Time fields' return format to H:i:s.

The existing field keys remain unchanged. No unrelated field definitions will be modified.

Existing Data

Renaming the ACF field does not rename previously saved WordPress metadata. Existing rows stored as multiple_dates_* therefore remain in place and are read through the plugin compatibility fallback. Newly edited schedule data will be saved under canonical event_dates_* keys.

No destructive or automatic bulk database migration is included. If both old and new repeater data exist on an event, canonical event_dates data is authoritative.

Testing

Regression tests will first reproduce the current theme override:

• multiple_dates rows using F j, Y dates and g:i a times produce normalized occurrences.
• Standalone legacy fields in those formats produce an occurrence.
• Canonical event_dates rows win when both repeater names contain data.
• Invalid formatted values remain excluded.
• Metadata synchronization recognizes and flushes the legacy repeater.

The focused occurrence tests and complete plugin test suite must pass after the implementation. The theme JSON will also be parsed to confirm it remains valid JSON and contains the canonical schedule names and return formats.