feat: Add the file-based override source

[kinyoklion]

Summary

This adds the file-based override source that the OVERRIDE specification defines, as FileOverrides.source() in the integrations package, configured through DataSystemBuilder.overrides(...):

LDConfig config = new LDConfig.Builder()
    .dataSystem(Components.dataSystem().defaultMode()
        .overrides(FileOverrides.source().filePaths("/etc/launchdarkly/overrides.json")))
    .build();

The source reads one or more JSON or YAML files in the file data source document format (flags, flagValues, segments) in the configured order. A flagValues entry becomes a flag that is on and serves the value as its single variation by fallthrough, so it evaluates with the FALLTHROUGH reason kind. Entries keep the versions that the documents specify.

• duplicateKeysHandling: FAIL (the default) fails the reload when the same key appears in more than one file; IGNORE keeps the entry from the first configured file.
• changeDetection: POLLING (the default) examines each file's modification time and size on an interval; WATCHING uses file system notifications. The two are alternatives.
• pollInterval: one second by default and at minimum; a smaller value is raised to the minimum with a warning.
• A configured file that does not exist contributes no overrides and is not an error. Creating it later takes effect, and deleting it removes its overrides.
• A file that exists but cannot be read or parsed fails that whole reload: the last good overrides stay in effect, the failure is logged, and the source retries after a bounded delay as well as on the next change.
• The initial load completes during client construction. Every applied change is logged at Info with the overrides in effect and what each file supplied.
• No file paths, a null change detection mode, or a null poll interval is a configuration error that fails client construction. A path listed more than once is logged at Warn and the repeats are ignored; the first occurrence keeps its place in the order.

The source is built on OverrideFileLoader, FileDataReloader, FileDataPoller, and FileDataWatcher from the earlier change. The existing file data source keeps its current behavior; this change does not touch its code paths. Flag overrides are currently experimental and subject to change.

This PR depends on the override layer and the reload infrastructure changes and is based on the events branch (rlamb/overrides-java-override-events); retarget it to feat/overrides once that branch merges.

SDK-3246

---

Note

Overview
Adds FileOverrides.source() as the SDK’s file-based OverrideSource, wired through DataSystemBuilder.overrides(...) so operators can load flag/segment overrides from local JSON/YAML (file data document format) during incidents.

The builder supports multiple ordered files, duplicateKeysHandling (FAIL vs IGNORE), and reload on change via polling (default 1s, with a minimum) or filesystem watching. FileOverrideSourceImpl performs a synchronous initial load before start returns, pushes full snapshots to the override sink, keeps last-good overrides on parse/read failures (with retry), treats missing files as empty, and logs what’s in effect per file.

Docs on OverrideSource and DataSystemBuilder#overrides now point at FileOverrides. A large FileOverrideSourceTest suite covers merge order, hot reload, lifecycle, and config validation.

^{Reviewed by Cursor Bugbot for commit a0f4c55. Bugbot is set up for automated code reviews on this repo. Configure here.}

[kinyoklion]

bugbot review

[cursor]

Stale Bugbot comment from a previous run.

[kinyoklion]

bugbot review

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a0f4c55. Configure here.}

[cursor]

Watching setup failure stops all reloads

Medium Severity

When WATCHING cannot start, the error is logged and start continues, but neither a watcher nor a poller is left running. After a successful initial load the reloader also has no retry armed, so later file creates, edits, and deletes never apply. That breaks the documented contract that a missing file taking effect later, or an operator updating overrides during an incident, will be picked up.

 

^{Reviewed by Cursor Bugbot for commit a0f4c55. Configure here.}