update-feature-config

Update Feature Config

Feature config (authgear.features.yaml) is merged across layers — code default ← cluster ← plan ← app override — via FeatureConfig.Merge (pkg/lib/config/feature.go), which reflects over every top-level field and dispatches to that section's own Merge in pkg/lib/config/feature_*.go.

Hard requirement: merge must be field-level, never whole-section replace

Historically, most sections implemented Merge as a wholesale swap:

// WRONG for any section with more than one leaf field
func (c *XFeatureConfig) Merge(layer *FeatureConfig) MergeableFeatureConfig {
	if layer.X == nil {
		return c
	}
	return layer.X
}

This is a real, reachable bug class, not a theoretical one: if a lower layer (e.g. a plan) sets field A and a higher layer (e.g. an app override) later sets a sibling field B — without repeating A — the whole-section swap silently resets A back to its code default. Plan/app documents are routinely partial, hand-authored YAML, so this triggers in practice, not just in edge cases. It was found and fixed across identity, authentication, authenticator, ui, hook, collaborator, messaging.rate_limits, and test_mode — do not reintroduce it in a new section or a new field on an existing section.

Every new field on an existing multi-field section, and every new top-level section, must merge field-level:

• Follow the reference pattern in OAuthClientFeatureConfig.Merge (pkg/lib/config/feature_oauth.go): nil-safe guards first (if c == nil && layer == nil { return nil }, if c == nil { return layer }, if layer == nil { return c }), then per-field if layer.X != nil { c.X = layer.X } for every field.
• If a section/sub-object genuinely has only one field, a whole-object replace at that level is fine — there's nothing else to lose. But if that one field is itself an object with siblings further down, cascade the field-level merge all the way down to where the real siblings are, even through single-field wrapper levels. See feature_authenticator.go's Authenticator → Password → Policy cascade: Authenticator and Password each have only one field, but Policy has three siblings that must merge independently — so the cascade goes three levels deep, not stopping at the first single-field level.
• Never write if layer.Section == nil { return c }; return layer.Section for a section with more than one leaf field, directly or transitively.