Layer a local config beneath the remote one, per environment

[andyyhope]

An app that talks to more than one backend usually wants two config layers for the
environment it is in: one bundled with the build, one fetched. EnvironmentConfiguration
holds both and keeps them in step with the environment you switch to.

let config = EnvironmentConfiguration(
    AppFlags.self,
    local:  { env in Bundle.main.data(named: "\(env).json") },   // ships with the app
    remote: { env in try await api.fetchConfig(for: env) }       // fetched, async
)
let pole = FlagPole(AppFlags.self, sources: [byHand] + config.sources)

pole.flags.$environment.publisher
    .removeDuplicates()
    .sink { env in Task { await config.load(env) } }   // staging → local, then remote
    .store(in: &cancellables)

Precedence

Highest wins:

by-hand override   (companion / SnapshotSource)
  remote  {env}    (fetched)
    local {env}    (bundled)
      @Flag(default:)   (compiled base)

Remote wins over local for the same flag; config.sources returns them in that order.

Clear-first, so a failure falls back rather than lies

Loading an environment clears each layer before it loads it. A fetch that fails or
returns nothing leaves that layer empty and the one beneath showing through — the
bundled config, then the defaults — rather than leaving an app labelled staging
running the previous environment's values. load(_:) returns a LoadOutcome saying
what happened to each layer, since one can succeed while the other does not.

The framework does no networking and reads no files: the two closures hand it the
bytes, it decodes, validates against the schema, and layers them. Each layer is an
ordinary RemoteOverrideSource, so either can be audited with a FlagMappingAudit.

Adversarial review

One defect, and it was the clear-first failure reached from the other side. Two
overlapping load calls — switch a→b with a slow a fetch — each cleared then applied,
and whichever apply landed last won regardless of which environment was current, so b
could end up showing a's values. Each load now carries a monotonic epoch and re-checks
it after the fetch; a stale result is dropped and reported as LayerOutcome.superseded
rather than written over the newer load.

Clean under review: empty Data() reads as a failure (not valid JSON), not absent;
both-absent is complete.

Demo

Wired through it: a bundled local config per environment beneath the fetched one, driven
by the environment flag. Clearing the remote layer falls back to the local config, not
raw defaults, and the on-device provenance panel shows the sources flip Remote → Local.

Verified

771 tests. DocC clean with --warnings-as-errors, both example apps and the iOS package
scheme build, and the layering was walked through on a simulator: switching environments,
remote-over-local, and the clear-to-local fallback.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NnwCqKNm8rZ63Au6bpYdaD