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.
Two entry points, one shared core
Section titled “Two entry points, one shared core”reconcileSections(initialValue, sectionConfigs, preserveLostValues, sectionLists): the entry point for the sections-based model, where the root data is aSection[].reconcileValues(initialValues, fieldConfigs, preserveLostValues, sectionLists): the entry point for the fields-based model, where the root is a flatRecord<string, Field>. It treats that record as a “virtual section” and delegates straight toreconcileFields.
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.
The discriminator-driven descent
Section titled “The discriminator-driven descent”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 toreconcileSections. 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,reconcileSectionspreserves it as a handle-only lost-value stub (flattenSectionToLostValues, below) whenpreserveLostValuesis true.type: 'children': resolves the field’s section configs the same way, but reconciles the array inline rather than delegating toreconcileSections: for each stored item, it looks up a matching config by handle and callsreconcileSectiondirectly. An item whose handle has no match in the resolved configs is silently dropped from the reconciled array: unlike thesectionsbranch above,childrendoes 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:sectionsfields are reconciled through the full top-level entry point (with its own orphan-preservation step), whilechildrenfields inline a narrower reconcile-or-drop loop.type: 'tabs': each tab in the storedTaggedTabsValueis reconciled independently:reconcileFieldsis called again with that tab’s ownconfigFields, and the tab’s lost values (if any) are re-keyed with a dottedfield.tab.prefix before being merged into this level’slostValues. 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 configvalue, 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.
The three-step process at each level
Section titled “The three-step process at each level”Within one reconcileFields call:
- Build values from config. Walk
configFieldsin order, producingvalues[handle]for every current field (the descent above). - Reapply lost values for empty primitives. For every key in
currentLostValuesthat now matches a config field, and whose type is notsections/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.” - Track newly orphaned values. Any key present in
currentValuesbut absent from the config is filed into this level’slostValues. Any previously-lost key that wasn’t reapplied in step 2, and isn’t now present incurrentValues, is carried forward unchanged.
The lostValues store
Section titled “The lostValues store”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.
Template-path updates
Section titled “Template-path updates”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.
Where to go next
Section titled “Where to go next”- Reconciliation: the concept-level summary this page expands on.
- Changing a section’s config safely: the practical safe/breaking checklist this mechanics page underpins.
- Per-section migration rules: the explicit mechanism for content changes reconciliation alone won’t do for you (an old value landing directly at a new handle).