Add testEveryRuleHasParseableSince to assert that every discovered
DeprecatedConfigRule classifies as WARNING under the soft-launch policy.
Under SOFT_LAUNCH_WARNING_ONLY=true the only way to get a non-WARNING
severity is an unparseable since string, so a single assertion locks the
"every since must be MAJOR.MINOR[.PATCH]" invariant at build time.

Without this guard, an empty or malformed since on any annotation would
classify as ERROR. Today that surfaces as a soft warning, but the moment
the soft-launch flag flips, every PUT/POST that touches that path
becomes a 400. Catching it in JUnit means a since-typo can never reach
production.

Expose DeprecatedConfigRule.since() as a package-private accessor so the
test message can quote the offending raw value.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Drop scope creep that crept in alongside the deprecation work:
- Revert the speculative segmentAssignmentConfigMap blocks added to 11
  example/sample JSONs. The string "BalanceNumSegmentAssignmentStrategy"
  did not match any canonical AssignmentStrategy constant; it worked only
  by falling through SegmentAssignmentStrategyFactory's permissive
  default. The block was not part of any deprecated-key migration.
- Revert KafkaIncreaseDecreasePartitionsIntegrationTest. Under the
  soft-launch policy the original test passes without modification — the
  refactor was unrelated to the validator change.

Harden the wire contract on ConfigSuccessResponse:
- Annotate the canonical constructor with @JsonCreator + @JsonProperty
  so Jackson deserializes without depending on the -parameters flag.
- Add round-trip tests: full-shape deserialize plus the new-client /
  old-controller compatibility direction (no deprecationWarnings field).

Make PinotTableRestletResourceTest order-insensitive on
deprecationWarnings. The discovery walk relies on Class.getMethods(),
whose order is not specified, so asserting the exact JSON string was
fragile. Helpers now parse the response and compare the warning SET.

Add a SUNSET TARGET section to SOFT_LAUNCH_WARNING_ONLY's Javadoc so
the flip is anchored to a release (≥1.7.0) and the validator is not
left as a permanent logging shim.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- TableConfigSerDeUtils.toRawJsonNode: guard null simpleField values.
  ZNRecord.getSimpleFields() permits null values; the previous code
  NPE'd inside looksLikeJsonContainer on the update-path diff read.
  Add a targeted unit test that pushes a null value directly into the
  simpleFields map and asserts the diff sees NullNode.

- CopyTableResponse: mark status and msg @nullable in the @JsonCreator
  signature. The class is @JsonInclude(NON_NULL) so both fields have
  always been omittable; the constructor's non-null typing was
  misleading SDK / OpenAPI generators. Also drop the new
  setDeprecationWarnings setter — deprecation warnings are immutable
  after the response is built.

- DeprecatedTableConfigValidationUtilsTest: lock SOFT_LAUNCH_WARNING_ONLY
  at true so the flag cannot flip without an intentional edit to this
  test. The test message reminds the next author of the four promotion
  pre-conditions (CAS, concurrency test, version seam, ERROR integration
  test). Also replace inline FQCNs with imports per CLAUDE.md.

- Realtime sample JSONs: drop speculative batchIngestionConfig
  blocks. The segmentPushType -> batchIngestionConfig migration is
  meaningful for OFFLINE tables only; REALTIME tables don't push
  segments in the OFFLINE sense.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- DeprecatedConfig.since: spell out in the SPI Javadoc that unparseable
  values classify as ERROR and therefore become 400 BAD_REQUEST under
  the soft-launch policy. Names the in-tree controller test that locks
  the invariant so external annotators know where the contract lives.

- DeprecatedTableConfigValidationUtils.isJsonAccessor: document why
  @JsonIgnore getters are intentionally traversed. The validator
  detects deprecated JSON input keys; @JsonIgnore prevents the bean
  from re-emitting the key on output but does not prevent the
  @JsonCreator / setters from accepting it on input. FieldConfig.indexType
  is the canonical example.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The deprecation-validator pre-reads the stored ZNRecord to compute the
diff, then later issues an update write. Previously these were two
separate ZK operations with no version check binding them, so a
concurrent writer that landed between the read and the write could
slip a deprecated key past the diff. Documented as the #1 promotion
pre-condition in SOFT_LAUNCH_WARNING_ONLY's Javadoc; now landed.

Plumbing:
- ZKMetadataProvider.getTableConfigZNRecord(propertyStore, name, stat):
  new overload that populates the supplied Stat so callers can capture
  the znode version.
- PinotHelixResourceManager.updateTableConfig(tableConfig, expectedVersion, force):
  new overload that forwards expectedVersion to setExistingTableConfig
  for the CAS write.
- PinotTableRestletResource.updateTableConfig: thread the stat.getVersion
  through to the write call. If the stored config didn't exist (the
  hasTable check above would have already 404'd, but for defense in
  depth we still pass -1 to skip the version check in that case).
- TableConfigsRestletResource.validateNoDeprecatedConfigs: return a
  DeprecationValidationResult holder carrying per-sub-type versions
  alongside the warnings, so the offline/realtime update calls can
  each issue their own CAS write.

The Javadoc for SOFT_LAUNCH_WARNING_ONLY now lists pre-condition #1 as
done; the three remaining (concurrency regression test, classifySeverity
version-injection seam, ERROR-path integration test) are still required
before the flip.

Also: switch the test reflective-ctor String placeholder from "_test"
to "" so a future failure surfaces as a real default mismatch rather
than a confusing "got `_test`, expected default" message.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CAS conflict is now a typed exception (TableConfigVersionConflictException
in pinot-common) so the REST resources can return HTTP 409 CONFLICT with
retry guidance rather than burning a generic 500 with an opaque message.
The legacy updateTableConfig(tableConfig) / updateTableConfig(tc, force)
overloads use expectedVersion=-1 so they cannot trigger the CAS branch;
they wrap any unexpected throw as IllegalStateException to preserve the
pre-existing two-checked-exception signature for back-compat with
existing callers (PinotDdlRestletResource, ControllerRequestClient,
RealtimeOffsetAutoResetKafkaHandler).

For TableConfigs PUT, the 409 message explicitly notes the partial-
success semantics — TableConfigs writes offline and realtime
sequentially, so the offline sub-config may have committed before the
realtime CAS lost. The client is told to re-read both and retry.

Adds testDiscoveryWalkDoesNotThrowAtClassLoad to lock the build-time
invariant that the validator's static lazy holder loads cleanly. A
duplicate @JsonProperty annotation across two getters on the same bean,
an unparseable since="…", or a bean cycle exceeding MAX_WALK_DEPTH would
otherwise surface only at deploy time as an ExceptionInInitializerError
that permanently breaks every controller table endpoint.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Lands two of the four promotion pre-conditions in this PR (the other two
— version-injection seam for classifySeverity, and the REST integration
test — are now done or no longer applicable):

Concurrency regression test (testUpdateTableConfigCasConflictThrowsConflictException)
in PinotHelixResourceManagerStatelessTest: exercises the CAS read→write
window end-to-end. T1 reads znode version v; T2 commits an update at v+1;
T1 attempts a write at v and must receive TableConfigVersionConflictException
(not a generic 5xx). Asserts T2's commit survives.

ERROR-path REST integration test (testErrorSeverityRuleRejectsCreateAs400)
in PinotTableRestletResourceTest: under SOFT_LAUNCH_WARNING_ONLY no
in-tree annotation can produce an ERROR severity. Inject a synthetic
ERROR rule via the new setRulesOverrideForTesting test seam, POST a
table that triggers the rule, and assert the REST surface returns 400.
Restores the override in finally.

The test seam (setRulesOverrideForTesting / clearRulesOverrideForTesting
/ makeRuleForTesting) lets tests substitute the rule list end-to-end
without flipping SOFT_LAUNCH_WARNING_ONLY. DeprecatedConfigRule is now
public so cross-package tests can construct synthetic rules; the
constructor remains package-private so production code cannot fabricate
rules outside the reflective discovery walk.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

setExistingTableConfig now performs the version check before the
backward-compatibility validation. Previously the back-compat read ran
against a potentially newer znode than the caller's expectedVersion,
which could surface a misleading 400 TableConfigBackwardIncompatibleException
when the right answer is 409 TableConfigVersionConflictException. The
short-circuit reads a Stat-bearing snapshot, compares, and throws
immediately if the versions differ. The CAS write below remains the
source of truth for the atomic write.

Add @VisibleForTesting (com.google.common.annotations) to the three
rule-override test seams so static analysis surfaces any inadvertent
production callers. The methods stay public (cross-package tests in
controller.api need them) but are now self-documenting as test-only.

Document the non-atomic offline-then-realtime semantics on the
/tableConfigs/{tableName} PUT endpoint Javadoc: clients receiving 409
MUST re-read both sub-configs and retry the full transaction; the
offline write may have already landed before realtime CAS failed.

Add a cross-reference comment in DeprecatedTableConfigValidationUtilsTest
mapping each of the four SOFT_LAUNCH_WARNING_ONLY promotion
pre-conditions to its in-tree coverage. This makes the promotion-PR
checklist discoverable from a single test file.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…arsal

Three changes addressing reviewer-flagged MAJORs:

1. Move DeprecatedTableConfigValidationUtils (and its test) from
   pinot-controller/api/resources to pinot-common/utils/config.
   The class does not depend on any controller-specific type — only
   pinot-spi annotations and Jackson — so it can live in
   pinot-common alongside TableConfigSerDeUtils. This unblocks future
   reuse from pinot-broker / pinot-server / ops tooling without
   pulling in pinot-controller. Pure relocation; package-private
   members are preserved (the test moves with the class to keep
   access to them).

2. Add DeprecatedTableConfigValidationUtils#warmUp(): public method
   that eagerly triggers the Rules.ALL lazy holder so the first REST
   request after controller startup doesn't pay the reflective
   discovery cost. Called from BaseControllerStarter#setUpPinotController
   and logs the discovered rule count.

3. Add testErrorSeverityRuleAllowsUnchangedLegacyValueOnUpdate: post-flip
   rehearsal that uses the existing @VisibleForTesting rule-override
   seam to simulate SOFT_LAUNCH_WARNING_ONLY=false semantics. Verifies
   the two non-obvious post-flip cases:
   - PUT re-submitting an UNCHANGED legacy value on a table that
     already holds it must succeed (diff sees no change, ERROR
     severity does not fire). This is the operability guarantee the
     promotion PR depends on — without it, every PUT to every
     existing table holding a legacy field would 400 the moment
     the flag flips.
   - PUT INTRODUCING a value change at the same deprecated path must
     be rejected as 400.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- setExistingTableConfig: in CAS mode (expectedVersion >= 0), REUSE
  the byte-snapshot fetched by the pre-flight version check for the
  backward-compatibility validation that follows. Previously the two
  reads were independent — back-compat validation could run against
  a fresher znode than the one whose version the caller checked,
  producing a misleading 400 BAD_REQUEST in the race window. Now a
  single TableConfig instance drives both decisions in the CAS path.
  Legacy non-CAS callers (-1 expectedVersion) keep the original
  getTableConfig() path.

- TableConfigsRestletResource: extend the documented atomicity caveat
  to enumerate the schema-then-tables non-rollback semantics, not
  just the offline-then-realtime case. Clients receiving 409 must
  re-read schema AND both sub-configs and merge against observed
  state.

- DeprecationValidationResult: drop the unused warnings() accessor;
  callers all read the field directly so the getter was dead code.

- TableConfigSerDeUtils.toRawJsonNode: log WARN when a stored
  simpleField looks like a JSON container (starts with '{' or '[')
  but fails to parse. The fallback to a text-node representation is
  preserved so the table stays usable, but operators now have a
  signal when a corrupt ZK record could be producing spurious
  "newly introduced" deprecation warnings on update.

- ConfigSuccessResponse: add @JsonIgnoreProperties(ignoreUnknown=true)
  so strict-parsing older clients (FAIL_ON_UNKNOWN_PROPERTIES=true)
  tolerate future controller-emitted fields. Locked by new
  testStrictParserToleratesUnknownFutureField in
  ConfigSuccessResponseTest.

- DeprecatedTableConfigValidationUtils.findMatchingOldElement: when
  the stored array carries DUPLICATE `name` keys (Pinot does not
  enforce uniqueness at the JSON layer), log WARN with the duplicate
  name and count so the corruption is visible. Behaviour-preserving:
  first-match wins, matching the historical contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- DeprecatedConfig annotation Javadoc: rewrite to describe current
  soft-launch semantics (every parseable since classifies as warning,
  only unparseable since fires the throw branch) and clearly mark the
  post-flip semantics as future-tense.

- PinotTableRestletResource.updateTableConfig: handle the
  hasTable-then-delete race. When the stored ZNRecord disappears
  between the existence check and the diff read, return 404 with an
  explicit message rather than letting an NPE inside validateOnUpdate
  bubble out as an opaque 5xx.

- PinotHelixResourceManager.setExistingTableConfig: correct the
  comment that claimed the pre-flight version check "closes" the
  race window. The atomicity boundary is the propertyStore.set CAS,
  not the pre-flight read; the early throw is an optimisation that
  gives a precise 409 in the obvious-stale-read case.

- TableConfigBuilder: restore the named constant
  APPEND_SEGMENT_PUSH_TYPE and reference it from both the field
  default and the setSegmentPushType("APPEND") branch, eliminating
  duplicated string literals (C7.14).

- PinotTableRestletResourceTest: belt-and-braces cleanup in the
  @AfterMethod always clears the deprecation-validator rule override
  so a failing ERROR-path test cannot poison subsequent tests.

- TableConfigSerDeUtilsTest: add three round-trip tests covering
  malformed JSON container fallback, primitive-looking text values
  (123, true, null) that must stay as text nodes, and the existing
  null-value branch. Locks the load-bearing diff-driving contract
  for toRawJsonNode.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…re shape

Reviewer flagged that broadening the checked-exception throws clause on
PinotHelixResourceManager.setExistingTableConfig(TableConfig, int [,
boolean]) is a source-incompat for external callers (forks, plugins)
compiled against the prior signature. Convert
TableConfigVersionConflictException from `extends Exception` to
`extends RuntimeException` so the binary contract of the pre-existing
two-arg / three-arg public methods is preserved. The REST resources
still catch the specific subclass to translate to HTTP 409; the
"callers SHOULD return 409" recommendation is unchanged, just no
longer forced by the compiler.

Cleanup that flows from the change:
- Strip the now-unnecessary `throws TableConfigVersionConflictException`
  from setExistingTableConfig(...,int) / (...,int,boolean) and
  updateTableConfig(...,int,boolean) public signatures.
- Drop the catch-and-rewrap blocks in the legacy
  setExistingTableConfig(TableConfig) and
  updateTableConfig(TableConfig, boolean) overloads. They no longer
  need to convert a checked exception that the underlying methods
  cannot throw with expectedVersion=-1.

Concurrent-delete race (reviewer MAJOR #4): in CAS mode, when the
pre-flight read returns null because a concurrent thread deleted the
table, throw TableConfigVersionConflictException with a clear "was
deleted concurrently" message instead of silently proceeding (which
could re-create the table at expectedVersion — Lazarus pattern — or
emit a misleading "modified by a concurrent writer" message).

Wire-shape rolling-upgrade docs (reviewer MAJORs #2 and #3): expand
the pinot-java-client README to enumerate the response-shape changes
- FieldConfig.indexType elided via @JsonIgnore (read indexTypes
  instead), and several boolean getters gain @JsonInclude(NON_DEFAULT)
  so the field disappears when at the type default. New
  @JsonIgnoreProperties(ignoreUnknown=true) on ConfigSuccessResponse
  covers strict-parsing old clients. Recommends FAIL_ON_UNKNOWN_PROPERTIES=false
  for strict parsers OR upgrade in lockstep with the controller.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>