[Feature] resolveSettings helper for DRY settings-merge boilerplate

[pathosDev]

Size / Priority

• Size: S (~80 lines saved)
• Category: C.2 Simplifications & DRY.
• Risk: low (depends on [Feature] Generic broker-settings reader (DRY across 8+ brokers) #248 — broker settings).

Affected files

• Same files as [Feature] Generic broker-settings reader (DRY across 8+ brokers) #248 — every broker + cache + journal that merges defaults + config + ctor args.

Background

This is the general-purpose version of #248. The broker-specific helper in #248 is one application; the framework has at least:

• Broker settings (8 brokers).
• Cache settings (3 caches).
• Journal settings (3 journals).
• Cluster settings.
• HTTP backend settings.

All do similar three-source merging. A single typed helper:

// src/util/Settings.ts (new)

export function applyDefaults<S extends Record<string, unknown>>(
  partial: Partial<S>,
  defaults: S,
): S;

export function resolveSettings<S extends Record<string, unknown>>(
  defaults: S,
  configKey: string,
  configObj: Config,
  ctorArgs?: Partial<S>,
): S;

applyDefaults is the simple "missing fields filled in" case; resolveSettings is the three-source version (delegate to applyDefaults for the merging logic).

Coordination

• [Feature] Generic broker-settings reader (DRY across 8+ brokers) #248 (broker settings) — uses resolveSettings internally.
• [Feature] applyDefaults helper for repeated settings.x ?? DEFAULT_X pattern #266 (defaults at call sites) — covers applyDefaults consolidation across the codebase.

This issue is largely the umbrella for both (and a few more sites — cache, journal, cluster settings). Coordinated implementation.

Integration / risk

• No behavioural change.
• Migrate site-by-site.

Test plan

1. Per-site regression — each settings consumer behaves identically.
2. Edge cases — empty config, partial config, missing keys fall through to defaults.

Acceptance criteria

• applyDefaults + resolveSettings exported.
• All major settings consumers (broker, cache, journal, cluster, http) migrated.
• Per-site regression tests pass.
• No CHANGELOG entry needed.
• Close [Feature] Generic broker-settings reader (DRY across 8+ brokers) #248 + [Feature] applyDefaults helper for repeated settings.x ?? DEFAULT_X pattern #266 as covered if this lands.

[pathosDev]

Closing as won't-do — the project has since decided the opposite, and AGENTS.md records it:

There is no resolve helper: const s = options as XOptionsType

the merge stays a plain spread; validation is a separate void assertion

A generic resolveSettings would contradict the documented convention, so this is a decision rather than pending work. The reasoning: OptionsBuilder.set writes each field as an own enumerable property, so a builder is structurally a bag of its fields — a plain object and a builder are already interchangeable, and a spread is enough.

No scope is lost, because the practical need this issue and its duplicate #266 described was met — by two targeted helpers instead of one generic one:

• mergeOptions (src/io/broker/BrokerOptions.ts:118) for broker actors — see [Feature] Generic broker-settings reader (DRY across 8+ brokers) #248
• mergeLeafOptions (src/persistence/relational/RelationalPlugin.ts) for the persistence plugin composites

and validation moved to OptionsValidator, run once at consume time on the merged settings (#274) — which is the part that actually removed the repeated settings.x ?? DEFAULT_X checking this issue was reacting to.