Origin
Dime Ultrareview cycle-1 on PR #241 (fix/device-validation-level-hardening), tracked finding T5 — surfaced by the documentation-audit agent.
Finding
PR #241's M1 refactor collapses the pre-fix pair (`DeviceValidationLevel _deviceValidationLevel` + `bool _isDeviceValidationLevelExplicit`) into a single nullable field `DeviceValidationLevel? _deviceValidationLevel`. The null-or-not state carries a real semantic (null = "no explicit assignment, mirror IVL on Normalize"; non-null = "explicit latch, no mirror").
Two follow-ups are worth landing before the next stable release:
-
JSON serialisation shape — the `DeviceValidationLevel` property already carries `[JsonPropertyName("deviceValidationLevel")]` and returns `DeviceValidationLevelDefault` (Warning) when the backing field is null, so `JsonSerializer.Serialize` always writes an explicit `"deviceValidationLevel": 1` even when the user never set it. That's a documented-but-subtle contract: round-tripping a config through Save/Load latches DVL as explicit on the second load. Explicitly document this on the property remarks, or introduce `[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]` + expose the nullable via a separate serialisable property.
-
Docstring on the backing field — the M1 commit added an in-line comment on the field, but a `///
` XML doc block would surface in IntelliSense for anyone who navigates to the field directly (e.g. via GoToDefinition). Same content as the in-line comment, formatted as XML.
Rationale for defer
Both changes are documentation / API-clarification work. The M1 commit itself is behaviour-preserving; the round-trip subtlety only matters for consumers who Save + reload configurations from disk, which is not the primary path exercised by the tests. Landing the disclosure atomically with M1 would blur the "collapse explicit flag" review target.
Suggested design (for the follow-up PR)
- Add a `## Remarks` paragraph on the `DeviceValidationLevel` property XML doc calling out the "explicit on second load after Save+ReadJson" behaviour.
- Convert the private-field in-line comment to a `/// ` XML doc.
- (Optional) Add a fixture in `DeviceValidationLevelMigrationTests` that pins the round-trip latch behaviour: `new AgentConfiguration() → SaveJson → ReadJson → assert config2.DeviceValidationLevel == Warning AND backing field is now non-null`.
Refs: dime cycle-1 T5 (documentation-audit) — see PR #241's M1 refactor.
Origin
Dime Ultrareview cycle-1 on PR #241 (
fix/device-validation-level-hardening), tracked finding T5 — surfaced by the documentation-audit agent.Finding
PR #241's M1 refactor collapses the pre-fix pair (`DeviceValidationLevel _deviceValidationLevel` + `bool _isDeviceValidationLevelExplicit`) into a single nullable field `DeviceValidationLevel? _deviceValidationLevel`. The null-or-not state carries a real semantic (null = "no explicit assignment, mirror IVL on Normalize"; non-null = "explicit latch, no mirror").
Two follow-ups are worth landing before the next stable release:
JSON serialisation shape — the `DeviceValidationLevel` property already carries `[JsonPropertyName("deviceValidationLevel")]` and returns `DeviceValidationLevelDefault` (Warning) when the backing field is null, so `JsonSerializer.Serialize` always writes an explicit `"deviceValidationLevel": 1` even when the user never set it. That's a documented-but-subtle contract: round-tripping a config through Save/Load latches DVL as explicit on the second load. Explicitly document this on the property remarks, or introduce `[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]` + expose the nullable via a separate serialisable property.
Docstring on the backing field — the M1 commit added an in-line comment on the field, but a `///
Rationale for defer
Both changes are documentation / API-clarification work. The M1 commit itself is behaviour-preserving; the round-trip subtlety only matters for consumers who Save + reload configurations from disk, which is not the primary path exercised by the tests. Landing the disclosure atomically with M1 would blur the "collapse explicit flag" review target.
Suggested design (for the follow-up PR)
Refs: dime cycle-1 T5 (documentation-audit) — see PR #241's M1 refactor.