feat: support Doris-lineage distribution version brands via configurable aliases

[Jmmt-mingrui]

Summary

Doris-lineage distributions can report @@version_comment strings that carry their own brand token instead of the literal doris token. The strict version pattern leaves them unparsed, so the fail-closed gate marks all 55 child capabilities as DORIS_VERSION_UNKNOWN and the server is unusable against those clusters.

This PR relaxes only the brand check while keeping every numeric version check and making certification provenance-aware — all vendor-neutral: the codebase ships no distribution-specific brand names.

The three concepts are now cleanly separated:

1. Recognized distribution — brand registry (doris by default; operators add their distribution's token via CAPABILITY_VERSION_BRAND_ALIASES)
2. Numerically compatible feature — unchanged feature matrix: minimum version, per-variant patch ranges, conservative mixed-component evaluation all apply to registered brands
3. Evidence-backed Apache Doris certification — requires uniform Apache Doris brand provenance across the observed version vector; never transfers to a distribution solely because the three-part version matches

What changed

• utils/version_brands.py (new): canonical alias normalization/validation shared by configuration validation and the runtime brand registry — one contract, no drift.
• doris_version.py: version pattern compiled from the brand registry; configure_version_brands() validates and rebuilds; DorisVersion records brand / exposes brand_verified. Unrecognized brands, bare version numbers, and malformed comments still fail closed.
• capability_detector.py: _component_version propagates the @@version_comment brand to brandless FE/BE Version columns (e.g. bare 4.0.5) instead of force-prepending the doris brand — distribution provenance survives component probing, and a bare component build can no longer masquerade as Apache Doris.
• doris_feature_matrix.py:
  • PatchCertificationEvidence.brand (default doris): evidence only certifies clusters whose components uniformly carry the same brand. Distribution evidence comments are validated registry-independently (brand token + core literal), so committed distribution evidence never depends on runtime alias configuration.
  • DorisPatchCertificationMatrix.evaluate(): brand-matched evidence lookup; clusters without uniform Apache Doris provenance report PATCH_CERTIFICATION_DISTRIBUTION_UNVERIFIED (target-uncertified or outside-target).
  • _certification_status() (feature level): CERTIFIED requires brand_verified across the whole observed version vector, so availability keeps the _UNCERTIFIED qualification for distributions.
  • CERTIFIED_DORIS_VERSIONS counts Apache Doris evidence only.
• config.py / main.py / tools_manager.py: CAPABILITY_VERSION_BRAND_ALIASES (CSV), validated with the shared contract (including type validation for JSON config), re-exported to workers, applied before the first version probe.
• doris_feature_matrix.py feature ranges / capability_registry.py gating: untouched.

Operator usage

# The distribution's @@version_comment brand token, e.g. "<mydist> version 2.1.5"
export CAPABILITY_VERSION_BRAND_ALIASES=mydist

Evidence-integrity behavior (review scenarios)

Cluster	Result
Distribution, uniform 4.0.5 (Apache-certified patch)	TARGET_UNCERTIFIED, PATCH_CERTIFICATION_DISTRIBUTION_UNVERIFIED, certified=false — Apache evidence does not transfer
Distribution with its own committed evidence for 4.0.5	CERTIFIED with the distribution's evidence ID — the explicit escape hatch
Mixed-brand components (doris FE + distribution BE, same patch)	TARGET_UNCERTIFIED at both patch and feature level
Apache Doris 4.0.5	CERTIFIED with doris_4_0_5_linux_amd64 (unchanged)
Distribution 1.2.8	DORIS_VERSION_BELOW_MINIMUM (numeric gates intact)

Test plan

• Parser: unregistered brands fail closed; registered aliases parse with brand_verified=False; replace semantics; invalid/reserved (version, apache), non-string, and empty alias handling.
• Detector: comment brand propagates to brandless FE/BE components (distribution stays unverified through certification); brandless components under a doris comment still reach CERTIFIED.
• Certification: distribution ≠ Apache evidence, mixed-brand rejection, distribution-branded evidence certifies only its own brand, evidence brand canonicalization and registry-independent comment validation.
• Feature matrix: registered brands still hit below-minimum rejection, per-variant patch ranges (native lineage >=4.0.6 falls back to audit variant on 2.1.x), conservative mixed-component minimum, fail-closed on unrecognized formats.
• Config: env loading, to_dict() serialization, reserved-token rejection, non-string and non-list JSON values fail with the same messages configure_version_brands() produces.
• No existing test was skipped or weakened. Full suite: 1842 passed, 0 failed; ruff check and mypy pass.

Follow-up question for reviewers

Distribution-branded evidence currently lifts only the patch-level certification report (get_runtime_capabilities); the feature-level certified flag remains Apache-only by design. Should committed distribution evidence also propagate to feature-level certification status?

[FreeOnePlus]

Thanks for addressing compatibility with downstream and enterprise distributions. The compatibility goal is valid, but this implementation disables the capability-version contract by default, so I cannot approve it in its current form.

Blocking issues:

1. VERSION_GATING_ENABLED = False does much more than relax product-name parsing. It disables the project minimum version, per-feature version ranges and exclusions, mixed FE/BE checks, and native-lineage version checks.
2. The feature matrix returns compatible=True and matches every requested variant. In a direct reproduction, a SelectDB 2.1.5 comment was treated as compatible with native lineage (>=4.0.6), Python UDF discovery (>=4.1.3), and unified task progress (>=4.1.1). A parsed Apache Doris 1.2.8 cluster also passed the project >=2.0.0 baseline.
3. The default test run skips the tests that protect these contracts. The focused version/capability suite reports 205 passed and 26 skipped; forcing the gate back on runs all 231 tests successfully. Skipping regression coverage does not validate enterprise-distribution compatibility.

Requested direction:

• Keep version gating enabled.
• Make version-comment parsing distribution-neutral: extract a well-formed three-part version from SELECT @@version_comment; without requiring the Apache Doris product label, while preserving the raw comment and deployment metadata.
• Preserve project-minimum, range, exclusion, mixed-component, and feature-variant checks.
• For a genuinely unparseable version, expose an explicit unknown or degraded state. A runtime probe may override version uncertainty only for a feature that explicitly declares such a proof policy; there must be no global bypass.
• Add coverage for Apache Doris, SelectDB, generic enterprise/cloud product labels, malformed comments, versions below 2.0.0, the 4.0.5/4.0.6 lineage boundary, 4.1.x-only features, and mixed FE/BE versions.

The existing runtime probes should remain an additional source of evidence, not a replacement for the version matrix.

[FreeOnePlus]

Thanks for reworking the approach. The global version-gating bypass is gone, and the new alias mechanism keeps the numeric version contract intact. I verified locally that the project minimum, per-feature ranges, lineage fallback, and conservative mixed-component evaluation still work. The focused suite passes with 285 tests, the full suite passes with 1,835 tests (83 skipped), and Ruff/MyPy pass.

There is still one blocking evidence-integrity issue and one configuration-validation issue:

1. A registered distribution currently inherits Apache Doris patch certification. After registering selectdb, a uniform selectdb version 4.0.5 cluster is reported as CERTIFIED, certified=true, with the Apache Doris doris_4_0_5_linux_amd64 evidence. The feature-level result is also marked certified, so availability loses the expected _UNCERTIFIED qualification. Version compatibility may remain callable, but Apache Doris real-cluster certification must not be transferred to an untested distribution solely because the three-part version matches. Please make certification provenance-aware: aliases should be target-uncertified/outside-target unless separate evidence explicitly certifies that distribution.

2. Brandless FE/BE component versions erase distribution provenance. _component_version("4.0.5") is wrapped as Doris version doris-4.0.5, so brand_verified=True even when @@version_comment identified a registered distribution. If certification starts consuming brand_verified, this fallback still permits a false Apache certification. Please propagate the cluster/comment brand to brandless component values, or preserve distribution identity separately on the version vector.

3. Config validation and runtime validation disagree. DorisConfig.validate() accepts reserved aliases such as version and apache, while configure_version_brands() rejects them later with ValueError. The same normalization/validation contract should run during configuration validation, including type validation for JSON configuration.

The configurable, vendor-neutral alias mechanism itself is acceptable and does not need to be replaced with a global permissive parser. The remaining fix should separate three concepts cleanly: recognized distribution, numerically compatible feature, and evidence-backed Apache Doris certification.

[FreeOnePlus]

Thanks for addressing the previous review. The three original paths are materially improved: distribution comments no longer inherit Apache certification by version alone, brandless components inherit the cluster brand, and configuration/runtime alias validation now share one contract. I verified the submitted head locally: 292 focused tests pass, the complete suite reports 1,842 passed and 83 skipped, and Ruff/MyPy pass.

Three blocking edge cases remain, plus the branch currently conflicts with master:

1. Unparsed components are excluded from the feature-level provenance check. _certification_status() uses all(... for component in components if component.is_parsed). With an Apache Doris 4.0.5 master and an unparseable backend (unknown-build), doris_catalog.list_tables remains compatible, which is acceptable for a master-scoped feature, but it is also reported as certification_status=certified and certified=true. An unparsed observed component cannot prove Apache provenance. Compatibility may stay callable; certification must become unknown/uncertified unless every component required by the certification contract is parsed and provenance-verified.

2. Component brand detection uses substring matching. _component_version() checks any(brand in raw.casefold() ...). After registering the valid alias db, the valid brandless component value 4.0.5-adb1234 is treated as already branded because the commit hash contains db; direct parsing then fails and the component becomes unknown instead of inheriting the cluster brand. Please make this token/parser based: first attempt strict parsing of the raw value, then apply the brandless fallback when the strict parser does not match. Do not use arbitrary substring presence as the discriminator.

3. Distribution certification evidence validation still uses unbounded substring checks. A brand=enterprisedb, version=4.0.5 evidence record currently accepts comments such as notenterprisedb version 14.0.50 and notenterprisedb-14.0.50-abc1234. Both the brand and version only occur as substrings. Certification evidence needs exact token and three-part-version boundaries, preferably through a dedicated single-brand parser that does not depend on the mutable runtime registry.

4. The branch has real merge conflicts with current master (97ebfac). The conflicts are in doris_mcp_server/tools/capability_detector.py and test/tools/test_capability_detector.py, where recently merged cluster-history and active-task fixes overlap this change. Please rebase onto the latest master, preserve those fixes while resolving the new _component_version signature, and rerun the complete CI suite on the resolved tree.

Regarding the follow-up question: committed distribution evidence should eventually be able to qualify feature-level certification for that same brand, but that can be a separate focused change. For this PR, keeping feature-level certification Apache-only is acceptable as long as the behavior is documented and no distribution is falsely presented as Apache-certified.

[FreeOnePlus]

Superseded by #213. The replacement preserves the original implementation authorship, resolves the conflicts with current master, closes the remaining certification/parser review blockers, and carries fresh full-suite verification. GitHub rejected maintainer pushes to this fork branch with a remote commit_refs error, so the reconciled tree had to be published from the maintainer fork.

[FreeOnePlus]

Closing in favor of #213 so review and CI can continue on a conflict-free branch.