fix: migrate spec POJOs to AtomicReference + immutable snapshots (S3077)

[jlouvel]

Related Issue

Closes #422

---

What does this PR do?

Phase 2 of sonar-bug-remediation. Resolves SonarQube rule java:S3077 — "Non-thread-safe fields should not be volatile" — across 27 spec POJO classes (44 bug occurrences from run #1516, plus surrounding non-flagged volatile fields on the same classes for consistency).

Each volatile field is replaced with an AtomicReference<T> (or AtomicBoolean / AtomicInteger for primitive cases) holding an immutable snapshot for collections (List.copyOf / Map.copyOf). This:

1. Satisfies S3077 — no volatile remains on any non-thread-safe type.
2. Provides genuine thread-safety — readers always see a fully-constructed value; mutations are atomic at the reference level via set / updateAndGet.
3. Unlocks future write paths — fluent Java builders and Control-port runtime spec edits get a lock-free atomic-swap primitive for free.
4. Preserves the public Jackson-facing API — getters/setters still expose plain String / List<T> / Map<K,V>. Jackson never sees an AtomicReference.

Patterns applied (documented in the blueprint):

• Pattern A — scalar (String, Integer, custom Spec): AtomicReference<T> with plain getter/setter.
• Pattern B — List<T>: stored as List.copyOf(...) snapshot or CopyOnWriteArrayList inside an AtomicReference.
• Pattern C — Map<K, V>: stored as Map.copyOf(...) snapshot inside an AtomicReference. setParameter-style mutations use updateAndGet for lock-free copy-on-write.

Lazy initializers (e.g. ControlServerSpec.getManagement(), ObservabilityMetricsSpec.getLocal(), ControlManagementSpec.getLogs()) now use compareAndSet to remain thread-safe.

Files migrated (27)

Package	Files
io.naftiko.spec	NaftikoSpec, OperationSpec
io.naftiko.spec.aggregates	AggregateSpec, AggregateFunctionSpec
io.naftiko.spec.consumes.http	HttpClientSpec, HttpClientResourceSpec, HttpClientOperationSpec, OAuth2AuthenticationSpec
io.naftiko.spec.exposes	ServerSpec, ServerCallSpec
io.naftiko.spec.exposes.control	ControlServerSpec, ControlManagementSpec
io.naftiko.spec.exposes.mcp	McpServerToolSpec, McpServerResourceSpec
io.naftiko.spec.exposes.rest	RestServerOperationSpec, RestServerResourceSpec, RestServerStepSpec
io.naftiko.spec.exposes.skill	ExposedSkillSpec, SkillToolSpec
io.naftiko.spec.observability	ObservabilitySpec, ObservabilityMetricsSpec, ObservabilityTracesSpec, ObservabilityExportersSpec
io.naftiko.spec.scripting	OperationStepScriptSpec
io.naftiko.spec.util	BindingSpec, OperationStepCallSpec, StructureSpec

Engine-layer classes (Phase 3) and char[] auth password fields (Phase 4) are tracked separately.

Note on PR ordering

This branch was cut from fix/sonar-major-bugs (Phase 1, PR #420) but the two phases touch disjoint files, so this PR can be reviewed independently. Once #420 merges, this branch will be rebased onto main.

---

Tests

New test

• SpecFieldThreadSafetyTest — a structural meta-test that uses reflection to verify:
  • No covered spec class declares any volatile field (guards against S3077 regression).
  • Each non-abstract class still has a usable default constructor (preserves Jackson compatibility).
  • Parameterized over all 27 migrated classes — 54 cases total, all passing.

This test would have failed 26 times before the migration (every class except ObservabilityExportersSpec already migrated as the canonical proof-of-pattern), proving the fix is real.

Existing tests

The existing extensive Jackson round-trip and engine-wiring suite (ObservabilitySpecTest, TelemetryBootstrapTest, BindingSpecTest, InputParameterRoundTripTest, etc.) continues to pass — confirming that Jackson sees no behavioural difference and the engine reads values correctly through the new accessor shape.

Full test results

Tests run: 977, Failures: 14, Errors: 0, Skipped: 5

The 14 failures are pre-existing and unrelated to this change — they affect Step{2-8,10}Shipyard*IntegrationTest and stem from non-deterministic LLM responses (the model occasionally returns prose like "The …" instead of JSON, triggering Unrecognized token 'The'). These were already failing on main before this PR.

---

Checklist

• CI is green locally (mvn test shows 963 / 977 passing — only pre-existing LLM flakiness fails)
• Rebased on latest main (will rebase after fix: resolve MAJOR Sonar bugs in HttpClientAdapter and OasImportConverter #420 merges)
• Small and focused — one concern per PR (S3077 across spec layer)
• Commit messages follow Conventional Commits

---

Agent Context

agent_name: GitHub Copilot
llm: claude-opus-4.7
tool: copilot-chat
confidence: high
source_event: SonarQube quality gate run #1516 (main @ dcfd01c)
discovery_method: code_review
review_focus: |
  - Pattern A/B/C consistency across all 27 files
  - Lazy initializer compareAndSet correctness in ControlServerSpec / ObservabilityMetricsSpec / ControlManagementSpec
  - @JsonProperty kebab-case alias preserved on both getter and setter for ExposedSkillSpec
  - SpecFieldThreadSafetyTest reflection-based assertions

[jlouvel]

@eskenazit This will need to be rebased on main once PR #420 is merged

[jlouvel]

Rebased onto main (force-with-lease push).

This branch was originally cut from fix/sonar-major-bugs (PR #420), which made #420 a hard predecessor. To keep the four Sonar PRs disjoint and independently mergeable, I rebased this branch directly onto main and dropped the inherited 466ea54 commit.

Result:

• 1 commit on top of main (was 2 — Phase 1 commit dropped).
• 28 files changed (was 32 — the four Phase 1 files no longer appear).
• Zero file overlap with PRs fix: resolve MAJOR Sonar bugs in HttpClientAdapter and OasImportConverter #420, fix: migrate engine fields to AtomicReference snapshots (S3077, Phase 3) #425, or fix: migrate auth spec credentials to AtomicReference + defensive copies (S3077, Phase 4) #428.
• Unit tests pass locally on the rebased branch (SpecFieldThreadSafetyTest, HttpClientAdapterTest, OasImportConverterTest — 98/98 green).

Order of merge no longer matters between #420 and #423.