Skip to content

Reconciliation in depth

Reconciliation covers what an author experiences: missing fields get defaults, removed fields become recoverable lost values, template paths update. This page is the deeper companion it links forward to: the recursive mechanics, the lostValues store’s actual shape, and why the whole operation lives in the data layer rather than as a visible editor action. Everything here describes the data layer’s reconciliation logic directly, not just the observable effects an author sees.

  • reconcileSections(initialValue, sectionConfigs, preserveLostValues, sectionLists): the entry point for the sections-based model, where the root data is a Section[].
  • reconcileValues(initialValues, fieldConfigs, preserveLostValues, sectionLists): the entry point for the fields-based model, where the root is a flat Record<string, Field>. It treats that record as a “virtual section” and delegates straight to reconcileFields.

Both converge on reconcileFields, which does one level of work per call and recurses into itself (directly, or via reconcileSection / reconcileSections) for every nested level.

reconcileFields dispatches on each field’s type and recurses differently depending on which structural type it hits:

  • type: 'sections': resolves the field’s section configs, then delegates the entire stored array to reconcileSections. This creates mutual recursion: reconcileFields → reconcileSections → reconcileSection → reconcileFields, one full loop per nesting level. If a stored section’s handle has no match in the resolved configs, reconcileSections preserves it as a handle-only lost-value stub (flattenSectionToLostValues, below) when preserveLostValues is true.
  • type: 'children': resolves the field’s section configs the same way, but reconciles the array inline rather than delegating to reconcileSections: for each stored item, it looks up a matching config by handle and calls reconcileSection directly. An item whose handle has no match in the resolved configs is silently dropped from the reconciled array: unlike the sections branch above, children does not preserve an unmatched item as a lost-value stub. This is a real asymmetry between the two structural types, not an oversight to route around: sections fields are reconciled through the full top-level entry point (with its own orphan-preservation step), while children fields inline a narrower reconcile-or-drop loop.
  • type: 'tabs': each tab in the stored TaggedTabsValue is reconciled independently: reconcileFields is called again with that tab’s own configFields, and the tab’s lost values (if any) are re-keyed with a dotted field.tab. prefix before being merged into this level’s lostValues. A stored tab whose handle isn’t in the current config has all of its field values preserved under that same dotted-prefix scheme, so an entire removed tab is recoverable exactly like a single removed field would be.
  • Everything else is a leaf: values[handle] = currentValue ?? <default for that category> (COMPOUND_OBJECT_TYPES → null, COMPOUND_ARRAY_TYPES → [], multi-value fields → [] with a comma-string legacy migration, hidden → its config value, everything else → '').

There is no fixed “depth” to any of this and no enumerable list of “places a section can live”: the descent is driven entirely by the config tree’s own shape. Per-section migration rules documents a second consumer (the migration walker) that mirrors this same descent rather than enumerating a fixed shape of its own.

Within one reconcileFields call:

  1. Build values from config. Walk configFields in order, producing values[handle] for every current field (the descent above).
  2. Reapply lost values for empty primitives. For every key in currentLostValues that now matches a config field, and whose type is not sections/children/tabs (those already handled their own recovery in step 1), and whose freshly-built value is still empty: the lost value is written back in and the key is marked “reapplied”. This is the mechanism behind “re-added fields recover their value automatically.”
  3. Track newly orphaned values. Any key present in currentValues but absent from the config is filed into this level’s lostValues. Any previously-lost key that wasn’t reapplied in step 2, and isn’t now present in currentValues, is carried forward unchanged.

flattenSectionToLostValues(section) is what turns an entire orphaned section (not just one field) into a single flat lostValues record when its handle no longer matches any config: it merges section.values and any existing section.lostValues into one object (values winning on key collision), preserving arrays and tab values as-is rather than trying to recurse into them further: the section becomes an inert stub ({ id, handle, order, templatePath, lostValues }) with no values at all. If that handle’s config is restored later, the stub re-enters reconcileSection on the next mount and its flattened lostValues feed step 2 above, field by field.

reconcileSection always sets templatePath: sectionConfig.templatePath fresh from the current config on every single reconcile, not only when it detects a change. This is why editing a section’s templatePath in YAML silently re-points every existing instance the next time its page is opened, with no separate step.

Why this runs in the data layer, not as a visible action

Section titled “Why this runs in the data layer, not as a visible action”

Reconciliation happens once, synchronously, when the editor loads, before the editor’s context provider hierarchy (ConfigProvider → EditorStateProvider → HistoryProvider → ValidationProvider → WordPressProvider) mounts on top of already-reconciled state, so there is no reconcile step visible in the render tree and no button that triggers it. Any UI surface that reflects a reconciliation outcome (a lost value showing up in the Inactive Fields panel, for example) only becomes visible once the editor has mounted and that UI subscriber exists to receive it; the computation itself is already finished by then. Saving simply writes the reconciled values / lostValues back to _sek_data, so a page’s stored content converges on its current config as an ordinary side effect of being opened and saved, never as a distinct migration you have to remember to run.