You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hudi.apache.org by vh...@apache.org on 2026/08/25 08:52:10 UTC

(hudi) branch master updated: feat(variant): auto-infer per-file variant shredding schemas on shredding inference (#18961)

This is an automated email from the ASF dual-hosted git repository.

voonhous pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/hudi.git


The following commit(s) were added to refs/heads/master by this push:
     new 476b335c1f31 feat(variant): auto-infer per-file variant shredding schemas on shredding inference (#18961)
476b335c1f31 is described below

commit 476b335c1f31a4d378ebeb254df7e04ec6823154
Author: voonhous <vo...@gmail.com>
AuthorDate: Tue Aug 25 16:52:01 2026 +0800

    feat(variant): auto-infer per-file variant shredding schemas on shredding inference (#18961)
    
    * feat(variant): auto-infer per-file variant shredding schemas
    
    Today typed_value comes only from an explicit table schema or the test-only
    force-shredding DDL, so production tables never shred variants. This adds
    per-file inference of the shredding schema from the first records of each
    base file, for both HoodieRecordType paths and the bulk-insert row writer,
    reusing Spark 4.1's InferVariantShreddingSchema heuristics verbatim
    (SPARK-53659). Gated by hoodie.parquet.variant.shredding.schema.inference.enabled
    (default off); on Spark 4.0/Flink/Java the inferrer is absent from the
    classpath and writes silently stay unshredded.
    
    A buffering HoodieFileWriter decorator (mirroring Spark's
    ParquetOutputWriterWithVariantShredding: 4096 records / 64MB, infer once,
    replay in order) defers the parquet writer until the schema is known. The
    AVRO factory splices the inferred typed_value into the schema argument; the
    SPARK and row-writer factories splice a copied config because the row write
    support resolves its schema from hoodie.write.schema/hoodie.avro.schema.
    Inference failures decline to unshredded (a throwing inference must not fail
    compaction); writer-creation/replay failures latch and rethrow through
    close() so buffered records cannot be dropped silently. The Spark 4.1
    inferrer batches all variant columns into one call (global width budget) and
    drops avro-illegal object keys, which legally fall back to the residual
    value column.
    
    Also fixes latent issues this feature would trip: recursive
    Variant.getPlainTypedValueSchema (depth>=2 objects, arrays, value-only
    wrappers), avro field-reuse (Field already used) in stripVariantShredding
    and VariantReconstruction, and the table-schema footer fallback now strips
    typed_value by shape so per-file layouts never leak into the resolved
    table schema.
    
    Stacked on #18938 (read-side reconstruction); part of #18937.
    
    * fix(variant): repair shredded-base reads and inference splice on multi-variant tables
    
    Fixes surfaced by the auto-inference COW test, which is the first to read a
    shredded base file end to end:
    
    - VariantReconstruction never engaged on real files: the reader's file schema
      comes from converting the parquet footer MessageType, which loses the
      variant logical type, so the shredded group was projected down to
      {metadata, value} and typed_value was silently dropped on the AVRO
      read-then-rewrite path. Detect the on-disk side by shape, anchored on the
      requested column being a variant.
    - The inferred-shredding config splice aliased every variant column: columns
      share one record type named 'variant', which Avro serializes as name
      references after the first occurrence, so replacing one column's record
      with a same-named shredded definition shredded all of them on re-parse.
      Spliced records now get a per-column unique name.
    - getPlainTypedValueSchema named every nesting level '<name>_plain' with a
      null namespace; for nested objects (every spec level is named typed_value)
      the inner record became an Avro self-reference of its ancestor, which
      Spark rejects as recursion. Names now chain the field path.
    - HoodieRowParquetWriteSupport warned 'no corresponding HoodieSchema' for
      every nullable variant column because the top-level check did not unwrap
      the field's nullable union; shredding still happened via the nested
      fallthrough, so this only silenced a misleading warning.
    - Test fixes: cast(variant as string) on a string-typed variant extracts the
      raw string (not its JSON form), and the decline column now uses per-row
      empty objects: inference is per file and a multi-row insert can fan out to
      one file per row, so cross-row type conflicts never reach one inference
      call and cannot decline deterministically.
    
    * perf(variant): skip schema parse in the row-writer factory when inference is off
    
    resolveConfigSchema parses the avro schema string; gate it behind the
    inference flag so the default-off path adds no per-file cost.
    
    * test(variant): gate inference tests on inferrer availability, not Spark version
    
    PR CI runs on the merge ref against current master, whose spark4.2 profile
    satisfies gteqSpark4_1 but builds only hudi-spark4.2.x, which has no
    shredding-schema inferrer yet; the three inference tests then ran without
    one and failed their typed_value assertions on silently-unshredded files.
    Gate them on VariantShreddingRuntime.lookupInferrer() instead so any
    profile without an inferrer cancels rather than fails, and starts running
    again as soon as that version module ships its inferrer.
    
    * review(variant): drop detectProviderClassOnClasspath superseded by VariantShreddingRuntime
    
    The inference work centralizes engine-component classpath detection in
    VariantShreddingRuntime (provider + schema inferrer, memoized). The merge
    converged both call sites on it, leaving the interface helper added earlier in
    this stack unused; remove it and its CLASSPATH_CANDIDATES constant.
    
    * fix(variant): use inlined GroupType.containsField in inference footer assertions
    
    The inference tests cherry-picked here called the groupContainsField test helper,
    which the merged #18065 inlined to GroupType.containsField. The helper no longer
    exists, so the calls failed to compile; switch them to the inlined form.
    
    * review(variant): avoid double delegate.close() in inference writer close()
    
    On the success path the try already called delegate.close(); if it threw, the
    catch closed it again, relying on delegate close() being idempotent. Track a
    delegateClosed flag (set before the try-path close) so the catch only cleans up
    a delegate that materialize() created but never closed. Applied to both
    VariantShreddingInferenceFileWriter and its InternalRow sibling.
    
    * review(variant): read AvroVariantRow typed_value via a typedValue() helper
    
    Route the scalar/struct/array getters through a private typedValue()
    helper instead of repeating record.get(VARIANT_TYPED_VALUE_FIELD). The
    helper name makes it self-evident at every call site that the getters
    ignore ordinal (Spark only invokes them for ordinal == typedIdx), and
    centralizes the rationale in one comment.
    
    * review(variant): hoist SIZE_ESTIMATE_INTERVAL above the instance fields
    
    Move the constant to the top of the class, before the nested interface
    and instance fields, matching the sibling VariantShreddingInferenceFileWriter.
    
    * fix(variant): tag shredded row-writer variant parquet group with VARIANT logical type
    
    A shredded variant column written via the InternalRow row-writer path was
    emitted as a plain parquet group, missing the VARIANT(1) logical type that
    vanilla Spark 4.1 stamps on the variant boundary. Hudi reads round-tripped
    because they identify variants from the table HoodieSchema, but external
    readers (vanilla Spark / Trino) rely on the parquet annotation and would
    see a plain struct.
    
    The shredded variant reaches convertField as a marked struct (the
    VariantType was replaced by its {metadata, value, typed_value} schema), so
    it never hit the VariantType branch that already annotates. Promote
    applyVariantLogicalType onto the SparkAdapter trait (public, no-op default)
    and apply it in convertField when isVariantShreddingStruct is true. Stays a
    no-op on Spark 4.0 (parquet 1.15.2 lacks the annotation) and Spark 3.x
    (never shreds); Spark 4.1/4.2 stamp it. Assert it in assertInferredFooters.
    
    Note: the Avro/HoodieRecord write path (AvroSchemaConverterWithTimestampNTZ)
    has the same gap and is tracked separately.
    
    * fix(variant): tag shredded variant parquet group with VARIANT logical type on the Avro path
    
    Companion to the row-writer fix: the Avro/HoodieRecord write path
    (AvroSchemaConverterWithTimestampNTZ) also emitted shredded variant groups
    as plain parquet groups, missing the VARIANT(1) logical type that vanilla
    Spark 4.1 stamps on the variant boundary.
    
    This module is engine-agnostic and builds against parquet 1.15.2 on Spark
    4.0 where LogicalTypeAnnotation.variantType does not exist, so the
    annotation is resolved reflectively (null on < 1.16). The group is built via
    the Types builder because the annotation-bearing GroupType constructor is
    not public outside org.apache.parquet.schema. A version-aware test asserts
    the annotation is present on parquet 1.16+ and absent otherwise.
    
    * review(variant): rename finalBuilder to taggedBuilder in convertField
    
    In Parquet's builder API .named() is the finalizing call that closes the
    chain, so finalBuilder read as if already completed. taggedBuilder better
    conveys 'the builder we will eventually call .named() on'.
    
    * review(variant): rename detectProviderClass to getProviderClass
    
    The method returns the pre-computed PROVIDER_CLASS field rather than
    scanning the classpath on each call; getProviderClass makes the memoized
    semantics obvious without chasing the class-level Javadoc.
    
    * fix(variant): ship a Spark 4.2 shredding-schema inferrer and harden runtime probing
    
    INFERRER_CANDIDATES listed only the spark4.1 module's inferrer, so a Spark 4.2
    runtime silently wrote unshredded with the flag on (the config doc promised
    "Spark 4.1+"), and every CI lane skipped the three functional inference tests:
    the spark4.1 lanes are trimmed from bot.yml and the active Spark 4 lane is 4.2.
    Spark 4.2's InferVariantShreddingSchema has the same public API, so the 4.2
    module gets a copy of the 4.1 class (the same precedent as the adapters) and
    the candidate list gains it, most recent first.
    
    While here, make the static probes safe against anything but "absent": they run
    from the class's static initializer, so a LinkageError escaping probe() would
    fail <clinit> and every later getProviderClass() call on the main Avro write
    path would see a bare "Could not initialize class" with the cause lost. Load
    candidates without initialization and degrade every LinkageError to absent;
    narrow loadInferrer's catch (Throwable) to Exception | LinkageError.
    
    * test(variant): make TestAvroSchemaConverter variant expectations version-aware
    
    The four variant tests compared exact MessageType strings without an
    annotation; AvroSchemaConverterWithTimestampNTZ now stamps VARIANT(1) on
    variant groups on parquet 1.16+, so they failed under the spark4.1/spark4.2
    profiles (CI hides it: hudi-hadoop-common UTs only run on spark3.5).
    MessageTypeParser cannot parse the annotation, so compare the converter's
    toString() directly against a literal that carries " (VARIANT(1))" exactly
    when the running parquet has LogicalTypeAnnotation.variantType.
    
    * perf(variant): materialize payload-backed records once on the Avro sampling path
    
    AvroVariantSampleExtractor called record.toIndexedRecord per buffered record to
    sample, and HoodieAvroFileWriter.write/writeWithMetadata called it again at
    replay, so payload-backed HoodieAvroRecords deserialized twice for the first
    4096 records of every file (and a MERGE INTO expression payload evaluated its
    assignments twice). Give VariantSampleExtractor a prepare() hook that returns
    the record to buffer; the Avro extractor returns the materialized
    HoodieAvroIndexedRecord, whose toIndexedRecord is a pass-through, so sampling
    and replay both see it once. Records without data (delete payloads) are
    buffered as they are.
    
    * review(variant): detect on the config schema in the Spark factory; namespace generated record names
    
    HoodieSparkFileWriterFactory detected inferable columns on its schema argument
    but spliced into the config keys HoodieRowParquetWriteSupport resolves
    (hoodie.write.schema / hoodie.avro.schema); when the two differ the buffering
    cost is paid for a splice that never applies. Detect on the config schema in
    both Spark factories through VariantSchemaUtils.getInferableVariantColumnsFromConfig
    (which parses the schema only once the cheap config gates pass), replacing the
    row factory's private resolveConfigSchema.
    
    The record names applyInferredShredding and getPlainTypedValueSchema generate
    were unique within their own sets but could collide with a user-declared type
    (<col>_variant) or with each other (typed_value_a_b_c_plain for both a/b_c and
    a_b/c). Put them in Hudi-owned namespaces: hoodie.variant.inferred for the
    spliced variant records, and hoodie.variant.plain.<field path> for the plain
    typed_value records, where '.' separates the path segments so distinct paths
    cannot concatenate to one name.
    
    Also document that stripVariantShreddingByShape has no requested-side anchor
    (the footer fallback runs precisely when no table schema exists to anchor on,
    so a same-shaped user struct is stripped too) and is top-level only, matching
    getInferableVariantColumns.
    
    * docs(variant): inference applies to native parquet log files too; note the buffer memory
    
    The config doc claimed MOR log files are always written unshredded, which is
    false on the default table version (10): native log data files are
    <fileId>_<token>_<instant>_<v>.log.parquet and go through the same wrapped
    newParquetFileWriter(path, ...), so each log file infers its own layout (as
    forced-DDL shredding already does on master; the read path handles it). Say
    so, and note the per-writer 4096-record / 64MB buffer so executor memory can
    be sized for concurrently open handles.
    
    * test(variant): cover the row-writer decorator, extractors, the no-inferrer fallback and schema-utils legs
    
    - TestVariantShreddingInferenceInternalRowFileWriter: the row-writer decorator
      had no tests although its module's UTs run in CI; replay order across both
      writeRow overloads, row copies, record and UnsafeRow byte caps, inferrer
      failure, zero-row close, latched factory and replay failures, canWrite.
    - TestAvroVariantSampleExtractor: ByteBuffer vs byte[] payloads as defensive
      copies, absent column, null variant, delete payload, prepare() materializing
      once and passing indexed records through.
    - TestHoodieAvroFileWriterFactoryVariantInference: the flag with no inferrer
      on the classpath hands out the plain writer and writes unshredded, which is
      the only path most CI lanes (and Flink/Java/Spark 4.0) exercise.
    - TestVariantShreddingInferenceFileWriter: close exactly once (and not retried
      when the delegate's close throws), replay failure latched, getFileFormatMetadata
      before/after materialization and after close, prepared record sampled and
      replayed; the footer-metadata test now asserts forwarding on an open writer.
    - TestVariantSchemaUtils: two same-named variant columns stay apart through the
      config round trip (pins the 5f413b9c fix), every schema key is spliced,
      non-nullable splice, top-level-only detection, config-schema detection, and
      the documented missing anchor of the shape strip; fixtures via the new
      HoodieSchemaTestUtils.createPlainShreddedVariantRecord.
    - TestHoodieSchema uses HoodieSchema.createShreddedFieldStruct instead of a
      hand-rolled wrapper; TestHoodieAvroWriteSupportShredding shares its fixture
      and drops an assertion the sibling test already makes.
    - TestVariantDataType: the inference tests assert through assertVariantLayout
      and a new assertInferredTypedValue helper; the MOR test splits base from
      native log files so the base-file leg cannot pass on log files alone; the
      older shredding tests scope their session settings with withSQLConf instead
      of leaking them for later tests to unset.
    
    * review(variant): budget the byte cap on record payload, gate the Spark factory on the schema argument
    
    - The buffering byte cap estimated each record with a deep object-size walk,
      which charges the shared Avro Schema graph (or the Spark StructType) once per
      buffered record, the HUDI-9499 class of over-estimate; with prepare()
      materializing payload-backed records that now applied to every Avro record,
      shrinking the inference sample well below the intended 4096 rows. Add
      VariantSampleExtractor.sharedSizeEstimate (the Avro extractor measures the
      schema once per schema instance, the Spark extractor the StructType once) and
      subtract it from each estimate.
    - HoodieSparkFileWriterFactory checks the already-parsed schema argument before
      parsing the config schema, and intersects the two: the native log, delete and
      CDC writers share this factory with schemas that have no top-level variant and
      no longer pay a config-schema parse per file.
    - getInferableVariantColumnsFromConfig no longer re-evaluates the config gates.
    - SparkVariantSampleExtractor reuses VariantShreddingInferenceInternalRowFileWriter.resolveOrdinals
      instead of its own copy of the loop.
    - inferTypedValues in both decorators also degrades a LinkageError from the
      inferrer to unshredded instead of failing the write.
    - AvroSchemaConverterWithTimestampNTZ.isVariantLogicalTypeSupported() replaces
      the reflection probe the tests repeated.
    
    * test(variant): make the round-1 tests discriminate, and pin the round-2 changes
    
    - TestHoodieAvroFileWriterFactoryVariantInference names a shredding provider so
      the inferrer gate, not the provider gate, is the one under test.
    - TestHoodieAvroWriteSupportShredding keeps the shredded-group assertion: on
      every CI lane (parquet < 1.16) it was the only one that could fail.
    - TestVariantDataType: the MOR test asserts the native-log leg instead of
      guarding on it and narrows it to *.log.parquet data logs; the bulk-insert test
      pins the BULK_INSERT operation so a silent fallback to the record writers is
      caught; an un-gated test asserts an inferrer is registered on Spark 4.1+ (the
      gap that let the spark4.2 module ship without one); helper tidy-ups.
    - New tests for the shared-size subtraction (extractors and both decorators'
      byte-cap accumulation through the estimator), the row decorator's key copy,
      SparkVariantSampleExtractor's adapter-free branches, the namespace scheme
      keeping concatenating paths apart, and the detect/splice key asymmetry.
    - TestAvroSchemaConverter drops testVariantToParquetConversion (a duplicate of
      testUnshreddedVariantType) and uses the converter's own version probe.
    
    * test(variant): import getLastCommitMetadata from the HoodieSparkSqlTestBase companion
    
    The BULK_INSERT assertion added in 2ce0b7d7 referenced getLastCommitMetadata
    unqualified; it is defined on the HoodieSparkSqlTestBase companion object, not
    the base class, so the scala test compile failed on Azure.
    
    * test(variant): size the estimator-accumulation rows so the rounding slack stays under one row
    
    testByteCapAccumulatesThroughTheEstimator allowed a 100-byte slack for the
    moving average's long truncation, but a GenericInternalRow with one Long is
    about 56 bytes, so the cap landed a row early on Azure. Use kilobyte rows and
    records in both decorator tests and assert that size up front.
    
    * review(variant): drop the stray MarkerCreationStatus enum
    
    Zero references anywhere; a timeline-server marker artifact that slipped in with 09b011b7880b.
    
    * review(variant): null-default the synthesized value field and scope two javadoc claims
    
    The value field synthesized by stripVariantShreddingByShape now carries NULL_VALUE like
    every other optional field on the footer path, so the two- and three-field file layouts
    resolve to equal schemas. The same method's javadoc scopes its top-level claim to the AVRO
    write support (the row writer can force-shred at depth), and the VariantShreddingRuntime
    javadoc no longer claims loadInferrer skips candidate initialization.
    
    * review(variant): harden the inference decorators
    
    - cleanup-close failures now suppress onto the primary via CloseableUtils (both decorators)
    - an Error mid-replay latches like an exception, so close() cannot finish the file without
      the un-replayed records; latch tests added to both suites
    - the byte cap rescales already-buffered records when the size estimate is revised (the row
      writer rescales only estimated rows, keeping the exact UnsafeRow charges)
    - SparkVariantSampleExtractor.prepare() detaches the buffered record from the handle's own
      wrapper, closing the deflate window the Avro extractor already avoided
    - the row suite covers a throwing delegate close; the Spark shared-size test asserts against
      ObjectSizeCalculator instead of itself
    
    * test(variant): make the VARIANT logical-type expectation an independent oracle
    
    The version-aware tests branched on the converter's own isVariantLogicalTypeSupported, so a
    rotted production probe would flip expectation and behavior together. Both suites now
    reflect on LogicalTypeAnnotation directly; the production helper lost its last caller and
    is deleted.
    
    * fix(variant): resolve shredding caps for compaction outside a SQL execution scope
    
    Spark's InferVariantShreddingSchema reads maxSchemaWidth/maxSchemaDepth from SQLConf.get in
    its constructor. Offline and async compaction dispatch via plain RDDs with no SQL conf
    propagation, so user overrides silently fell back to Spark's defaults there. Both inferrers
    now resolve the caps SQLConf-first with a SparkConf fallback (the
    resolveSessionLocalTimeZone pattern) and pin them via SQLConf.withExistingConf.
    
    * review(variant): scope three comments to what the writers actually shred
    
    The native-log data writer does receive a top-level variant through this
    factory, so it drops out of the no-variant list. The by-shape strip's
    javadoc and the resolver comment now say the row writer shreds at any
    depth its write schema asks it to, forced DDL or not, and that a nested
    shredded column can therefore still surface from the footer fallback.
    
    * review(variant): document the internal-schema gate on the inference config
    
    * review(variant): close the delegate when materialization dies with an Error inside close
    
    materialize() latches and rethrows Errors, but the close() catch listed
    only IOException and RuntimeException, so an Error thrown by the first
    materialization inside close() left the just-created delegate open with
    the closed flag already set. Both decorators now catch Error too, with a
    test each pinning the cleanup.
    
    * test(variant): pin non-null typed_value values via block column statistics
    
    The inference assertions read only the footer schema, so a file whose
    rows all fell back to the residual value with typed_value written
    all-null passed every test. Each pinned file must now show a non-null
    count on a typed_value leaf in the block column statistics.
    
    * test(variant): pin the byte-cap rescale and the UnsafeRow charges, count typed leaves only
    
    Round-3 review follow-ups:
    - Reshape both byte-cap tests so the 100th record is much bigger than the
      first 99: the rescale on re-estimation is what meets a one-big-record
      cap, and both tests fail without it (same-sized records tripped the cap
      with or without the rescale).
    - Pin the row writer's incremental rescale with an UnsafeRow interleaved
      among estimated rows; assigning the estimated total would drop its
      exact charge.
    - Count only typed leaves in typedValueNonNullCount; the residual value
      leaves hold the fallbacks.
    - Re-parse the serialized plain schema before asserting the two leaf
      names differ; Avro aliases a repeated name silently.
    - Scope the writeRow comment: no production caller is wrapped today.
    
    * test(variant): pin the 64MB ceiling, the suppressed close failure and the per-schema memo
    
    Round-4 review follow-ups:
    - Both decorators cap the buffer at min(64MB, maxFileSize); no test passed
      a file size above 64MB, so the min was unpinned. One row (UnsafeRow) or
      record (64MB payload) at the ceiling now materializes with the file size
      limit at Long.MAX_VALUE, on both twins.
    - The replay-failure tests also fail the delegate's close and assert the
      close failure arrives as suppressed on the replay failure, so a bare
      swallow in the catch path no longer passes.
    - The shared-size memo test asks about a second schema and the first one
      again, pinning the identity-keyed invalidation.
    - The inference config doc now says data blocks inside Avro-format log
      files stay unshredded whether Avro or parquet: the inline parquet block
      writer goes through the OutputStream overload, which is never wrapped.
    - The writeRow comment names the two factories that build the decorator
      rather than enumerating callers; the Flink row-data handle is a third.
---
 .../io/storage/HoodieSparkFileWriterFactory.java   |  43 ++
 .../io/storage/SparkVariantSampleExtractor.java    |  92 ++++
 .../row/HoodieInternalRowFileWriterFactory.java    |  34 +-
 .../storage/row/HoodieRowParquetWriteSupport.java  |  23 +-
 ...antShreddingInferenceInternalRowFileWriter.java | 260 ++++++++++
 .../org/apache/spark/sql/hudi/SparkAdapter.scala   |  19 +-
 .../storage/TestSparkVariantSampleExtractor.java   | 122 +++++
 ...antShreddingInferenceInternalRowFileWriter.java | 481 +++++++++++++++++
 .../common/avro/AvroVariantSampleExtractor.java    | 131 +++++
 .../hudi/common/avro/VariantSchemaUtils.java       | 249 +++++++++
 .../hudi/common/avro/VariantShreddingProvider.java |  23 -
 .../hudi/common/avro/VariantShreddingRuntime.java  | 119 +++++
 .../avro/VariantShreddingSchemaInferrer.java       |  78 +++
 .../hudi/common/config/HoodieStorageConfig.java    |  24 +
 .../apache/hudi/common/schema/HoodieSchema.java    | 142 +++--
 .../hudi/common/table/TableSchemaResolver.java     |   9 +-
 .../VariantShreddingInferenceFileWriter.java       | 332 ++++++++++++
 .../avro/TestAvroVariantSampleExtractor.java       | 172 +++++++
 .../hudi/common/avro/TestVariantSchemaUtils.java   | 341 ++++++++++++
 .../hudi/common/schema/HoodieSchemaTestUtils.java  |  12 +
 .../hudi/common/schema/TestHoodieSchema.java       | 123 +++++
 .../TestVariantShreddingInferenceFileWriter.java   | 573 +++++++++++++++++++++
 .../hadoop/HoodieAvroFileWriterFactory.java        |  48 +-
 .../hadoop/HoodieVariantReconstruction.java        |   3 +-
 .../avro/AvroSchemaConverterWithTimestampNTZ.java  |  32 +-
 .../avro/TestHoodieAvroWriteSupportShredding.java  |  71 ++-
 ...oodieAvroFileWriterFactoryVariantInference.java | 112 ++++
 .../parquet/avro/TestAvroSchemaConverter.java      |  51 +-
 .../sql/hudi/dml/schema/TestVariantDataType.scala  | 363 +++++++++++--
 .../variant/Spark4VariantShreddingProvider.java    |  35 +-
 .../spark/sql/adapter/BaseSpark4Adapter.scala      |  15 +-
 .../Spark41VariantShreddingSchemaInferrer.scala    | 148 ++++++
 .../apache/spark/sql/adapter/Spark4_1Adapter.scala |   2 +-
 .../Spark42VariantShreddingSchemaInferrer.scala    | 149 ++++++
 .../apache/spark/sql/adapter/Spark4_2Adapter.scala |   2 +-
 35 files changed, 4247 insertions(+), 186 deletions(-)

diff --git a/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/HoodieSparkFileWriterFactory.java b/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/HoodieSparkFileWriterFactory.java
index 53d40b6f1044..3e5e4d716e5a 100644
--- a/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/HoodieSparkFileWriterFactory.java
+++ b/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/HoodieSparkFileWriterFactory.java
@@ -18,6 +18,9 @@
 
 package org.apache.hudi.io.storage;
 
+import org.apache.hudi.common.avro.VariantSchemaUtils;
+import org.apache.hudi.common.avro.VariantShreddingRuntime;
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer;
 import org.apache.hudi.common.bloom.BloomFilter;
 import org.apache.hudi.common.config.HoodieConfig;
 import org.apache.hudi.common.config.HoodieStorageConfig;
@@ -30,6 +33,7 @@ import org.apache.hudi.common.util.collection.Pair;
 import org.apache.hudi.core.io.HoodieParquetConfigInjector;
 import org.apache.hudi.core.io.storage.HoodieFileWriter;
 import org.apache.hudi.core.io.storage.HoodieFileWriterFactory;
+import org.apache.hudi.core.io.storage.VariantShreddingInferenceFileWriter;
 import org.apache.hudi.exception.HoodieIOException;
 import org.apache.hudi.io.storage.row.HoodieRowParquetConfig;
 import org.apache.hudi.io.storage.row.HoodieRowParquetWriteSupport;
@@ -45,6 +49,8 @@ import org.apache.spark.sql.types.StructType;
 
 import java.io.IOException;
 import java.io.OutputStream;
+import java.util.List;
+import java.util.stream.Collectors;
 
 public class HoodieSparkFileWriterFactory extends HoodieFileWriterFactory {
 
@@ -56,6 +62,43 @@ public class HoodieSparkFileWriterFactory extends HoodieFileWriterFactory {
   protected HoodieFileWriter newParquetFileWriter(
       String instantTime, StoragePath path, HoodieConfig config, HoodieSchema schema,
       TaskContextSupplier taskContextSupplier) throws IOException {
+    // The row write support resolves its HoodieSchema from the config (hoodie.write.schema /
+    // hoodie.avro.schema), not the schema argument, so inferable columns are detected on that
+    // config schema (the one the splice below targets) intersected with the schema argument's
+    // (the shape of the rows being written, which the samples come from). The argument is
+    // checked first because it is already parsed: delete and CDC writers share this factory
+    // with schemas that have no top-level variant, and they must not pay a config-schema
+    // parse per file. The schema argument itself stays original: it flows through the global
+    // schema cache (getCachedSchema), which must never see per-file spliced schemas, and its
+    // StructType is identical either way (the variant column remains VariantType).
+    List<String> inferableColumns = inferableColumnsOf(config, schema);
+    if (!inferableColumns.isEmpty()) {
+      Option<VariantShreddingSchemaInferrer> inferrer = VariantShreddingRuntime.lookupInferrer();
+      if (inferrer.isPresent()) {
+        return new VariantShreddingInferenceFileWriter<>(
+            inferableColumns,
+            new SparkVariantSampleExtractor(inferableColumns, HoodieInternalRowUtils.getCachedSchema(schema)),
+            inferrer.get(),
+            inferred -> createParquetFileWriter(instantTime, path,
+                VariantSchemaUtils.applyInferredShreddingToConfig(config, inferred), schema, taskContextSupplier),
+            config.getLongOrDefault(HoodieStorageConfig.PARQUET_MAX_FILE_SIZE));
+      }
+    }
+    return createParquetFileWriter(instantTime, path, config, schema, taskContextSupplier);
+  }
+
+  private static List<String> inferableColumnsOf(HoodieConfig config, HoodieSchema schema) {
+    List<String> inArgument = VariantSchemaUtils.getInferableVariantColumns(config, schema);
+    if (inArgument.isEmpty()) {
+      return inArgument;
+    }
+    List<String> inConfig = VariantSchemaUtils.getInferableVariantColumnsFromConfig(config);
+    return inArgument.stream().filter(inConfig::contains).collect(Collectors.toList());
+  }
+
+  private HoodieFileWriter createParquetFileWriter(
+      String instantTime, StoragePath path, HoodieConfig config, HoodieSchema schema,
+      TaskContextSupplier taskContextSupplier) throws IOException {
     MetaFieldsMode metaFieldsMode = MetaFieldsMode.resolve(config);
 
     Pair<StorageConfiguration, HoodieConfig> injectedConfigs = HoodieParquetConfigInjector.applyConfigInjector(path, storage.getConf(), config);
diff --git a/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/SparkVariantSampleExtractor.java b/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/SparkVariantSampleExtractor.java
new file mode 100644
index 000000000000..6f0725c7a280
--- /dev/null
+++ b/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/SparkVariantSampleExtractor.java
@@ -0,0 +1,92 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hudi.io.storage;
+
+import org.apache.hudi.SparkAdapterSupport$;
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer.VariantSample;
+import org.apache.hudi.common.model.HoodieRecord;
+import org.apache.hudi.common.model.HoodieSparkRecord;
+import org.apache.hudi.common.schema.HoodieSchema;
+import org.apache.hudi.common.util.ObjectSizeCalculator;
+import org.apache.hudi.core.io.storage.VariantShreddingInferenceFileWriter.VariantSampleExtractor;
+import org.apache.hudi.io.storage.row.VariantShreddingInferenceInternalRowFileWriter;
+
+import org.apache.spark.sql.catalyst.InternalRow;
+import org.apache.spark.sql.types.StructType;
+
+import java.util.List;
+import java.util.Properties;
+
+/**
+ * Extracts variant binaries from {@code HoodieRecordType.SPARK} records, whose data is an
+ * {@link InternalRow} aligned to the writer {@link StructType} (the same contract the wrapped
+ * file writer relies on).
+ */
+public class SparkVariantSampleExtractor implements VariantSampleExtractor {
+
+  private final int[] ordinals;
+  private final StructType structType;
+  private final long structTypeBytes;
+
+  public SparkVariantSampleExtractor(List<String> columnNames, StructType structType) {
+    this.ordinals = VariantShreddingInferenceInternalRowFileWriter.resolveOrdinals(structType, columnNames);
+    this.structType = structType;
+    // Every HoodieSparkRecord of the file references this (cached, shared) StructType.
+    this.structTypeBytes = ObjectSizeCalculator.getObjectSize(structType);
+  }
+
+  @Override
+  public long sharedSizeEstimate(HoodieSchema schema) {
+    return structTypeBytes;
+  }
+
+  /**
+   * Re-wraps the row in a record of the decorator's own: {@link HoodieSparkRecord#copy()} deep-copies
+   * the {@link InternalRow} but returns the caller's instance, which a merge handle deflates as soon
+   * as the write call returns -- blanking a record still waiting in the buffer. The row handed in
+   * here is already that fresh copy, so wrapping it again is all the detachment needed. Records
+   * whose data is not a row (delete payloads) have nothing to detach.
+   */
+  @Override
+  public HoodieRecord prepare(HoodieRecord record, HoodieSchema schema, Properties props) {
+    Object data = record.getData();
+    if (!(data instanceof InternalRow)) {
+      return record;
+    }
+    return new HoodieSparkRecord(record.getKey(), (InternalRow) data, structType, record.getOperation(),
+        record.getCurrentLocation(), record.getNewLocation(), true);
+  }
+
+  @Override
+  public VariantSample[] extract(HoodieRecord record, HoodieSchema schema, Properties props) {
+    VariantSample[] out = new VariantSample[ordinals.length];
+    Object data = record.getData();
+    if (!(data instanceof InternalRow)) {
+      // Delete payload: no data to sample.
+      return out;
+    }
+    InternalRow row = (InternalRow) data;
+    for (int i = 0; i < ordinals.length; i++) {
+      if (ordinals[i] >= 0) {
+        out[i] = SparkAdapterSupport$.MODULE$.sparkAdapter().extractVariantBinary(row, ordinals[i]);
+      }
+    }
+    return out;
+  }
+}
diff --git a/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/row/HoodieInternalRowFileWriterFactory.java b/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/row/HoodieInternalRowFileWriterFactory.java
index 2e3c6238b67c..b5a3ab365133 100644
--- a/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/row/HoodieInternalRowFileWriterFactory.java
+++ b/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/row/HoodieInternalRowFileWriterFactory.java
@@ -18,8 +18,12 @@
 
 package org.apache.hudi.io.storage.row;
 
+import org.apache.hudi.common.avro.VariantSchemaUtils;
+import org.apache.hudi.common.avro.VariantShreddingRuntime;
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer;
 import org.apache.hudi.common.bloom.BloomFilter;
 import org.apache.hudi.common.bloom.BloomFilterFactory;
+import org.apache.hudi.common.config.HoodieConfig;
 import org.apache.hudi.common.config.HoodieParquetConfig;
 import org.apache.hudi.common.config.HoodieStorageConfig;
 import org.apache.hudi.common.engine.LocalTaskContextSupplier;
@@ -35,6 +39,7 @@ import org.apache.hadoop.conf.Configuration;
 import org.apache.spark.sql.types.StructType;
 
 import java.io.IOException;
+import java.util.List;
 
 import static org.apache.hudi.common.model.HoodieFileFormat.LANCE;
 import static org.apache.hudi.common.model.HoodieFileFormat.PARQUET;
@@ -79,8 +84,35 @@ public class HoodieInternalRowFileWriterFactory {
                                                                              Option<BloomFilter> bloomFilterOpt
   )
       throws IOException {
+    // The row write support resolves its HoodieSchema from the config (hoodie.write.schema /
+    // hoodie.avro.schema), so inferable columns are detected on that same config schema and the
+    // deferred creation splices a copied config; the StructType argument stays original.
+    // (getInferableVariantColumnsFromConfig only parses the schema once the flag gates pass.)
+    List<String> inferableColumns = VariantSchemaUtils.getInferableVariantColumnsFromConfig(writeConfig);
+    if (!inferableColumns.isEmpty()) {
+      Option<VariantShreddingSchemaInferrer> inferrer = VariantShreddingRuntime.lookupInferrer();
+      if (inferrer.isPresent()) {
+        return new VariantShreddingInferenceInternalRowFileWriter(
+            inferableColumns,
+            VariantShreddingInferenceInternalRowFileWriter.resolveOrdinals(structType, inferableColumns),
+            inferrer.get(),
+            inferred -> createParquetInternalRowFileWriter(path, table, writeConfig,
+                VariantSchemaUtils.applyInferredShreddingToConfig(writeConfig, inferred), structType, bloomFilterOpt),
+            writeConfig.getParquetMaxFileSize());
+      }
+    }
+    return createParquetInternalRowFileWriter(path, table, writeConfig, writeConfig, structType, bloomFilterOpt);
+  }
+
+  private static HoodieInternalRowFileWriter createParquetInternalRowFileWriter(StoragePath path,
+                                                                                HoodieTable table,
+                                                                                HoodieWriteConfig writeConfig,
+                                                                                HoodieConfig writeSupportConfig,
+                                                                                StructType structType,
+                                                                                Option<BloomFilter> bloomFilterOpt)
+      throws IOException {
     HoodieRowParquetWriteSupport writeSupport = HoodieRowParquetWriteSupport
-        .getHoodieRowParquetWriteSupport((Configuration) table.getStorageConf().unwrap(), structType, bloomFilterOpt, writeConfig);
+        .getHoodieRowParquetWriteSupport((Configuration) table.getStorageConf().unwrap(), structType, bloomFilterOpt, writeSupportConfig);
 
     return new HoodieInternalRowParquetWriter(
         path,
diff --git a/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/row/HoodieRowParquetWriteSupport.java b/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/row/HoodieRowParquetWriteSupport.java
index c14a75d314d6..6c55bbd5d487 100644
--- a/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/row/HoodieRowParquetWriteSupport.java
+++ b/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/row/HoodieRowParquetWriteSupport.java
@@ -239,10 +239,16 @@ public class HoodieRowParquetWriteSupport extends WriteSupport<InternalRow> {
           .flatMap(s -> s.hasFields() ? s.getField(field.name()) : Option.empty())
           .map(HoodieSchemaField::schema)
           .orElse(null);
+      // Unwrap the field's own nullable union too (e.g. ["null", variant] -> variant), like
+      // processNestedDataType does; otherwise nullable variant columns fail the VARIANT check
+      // below and emit a false schema-mismatch warning (shredding still happens via the
+      // processNestedDataType fallthrough, so this only affects which branch handles it).
+      HoodieSchema resolvedFieldSchema = fieldHoodieSchema != null && fieldHoodieSchema.isNullable()
+          ? fieldHoodieSchema.getNonNullType() : fieldHoodieSchema;
 
       if (SparkAdapterSupport$.MODULE$.sparkAdapter().isVariantType(dataType)) {
-        if (fieldHoodieSchema != null && fieldHoodieSchema.getType() == HoodieSchemaType.VARIANT) {
-          HoodieSchema.Variant variantSchema = (HoodieSchema.Variant) fieldHoodieSchema;
+        if (resolvedFieldSchema != null && resolvedFieldSchema.getType() == HoodieSchemaType.VARIANT) {
+          HoodieSchema.Variant variantSchema = (HoodieSchema.Variant) resolvedFieldSchema;
           // If typed_value field exists, the variant is shredded
           if (variantSchema.getTypedValueField().isPresent()) {
             // Use plain types for SparkShreddingUtils (unwraps nested {value, typed_value} structs if present)
@@ -902,8 +908,9 @@ public class HoodieRowParquetWriteSupport extends WriteSupport<InternalRow> {
                   .named(MAP_REPEATED_NAME))
           .named(structField.name());
     } else if (dataType instanceof StructType) {
+      StructType nestedStruct = (StructType) dataType;
       Types.GroupBuilder<GroupType> groupBuilder = Types.buildGroup(repetition);
-      Arrays.stream(((StructType) dataType).fields()).forEach(field -> {
+      Arrays.stream(nestedStruct.fields()).forEach(field -> {
         // Note: Cannot use HoodieSchemaField::schema method reference due to Java 17 compilation ambiguity
         HoodieSchema nestedFieldSchema = Option.ofNullable(resolvedSchema)
             .flatMap(s -> s.getField(field.name()))
@@ -911,7 +918,15 @@ public class HoodieRowParquetWriteSupport extends WriteSupport<InternalRow> {
             .orElse(null);
         groupBuilder.addField(convertField(nestedFieldSchema, field));
       });
-      return groupBuilder.named(structField.name());
+      // A shredded variant column reaches here as a marked struct (the VariantType was replaced by
+      // its {metadata, value, typed_value} shredding schema). Tag the parquet group with the VARIANT
+      // logical type so external readers recognize it as a Variant, matching Spark's native shredded
+      // parquet schema. No-op on Spark 4.0/3.x (the annotation only exists in parquet 1.16+).
+      Types.GroupBuilder<GroupType> taggedBuilder =
+          SparkAdapterSupport$.MODULE$.sparkAdapter().isVariantShreddingStruct(nestedStruct)
+              ? SparkAdapterSupport$.MODULE$.sparkAdapter().applyVariantLogicalType(groupBuilder)
+              : groupBuilder;
+      return taggedBuilder.named(structField.name());
     } else {
       throw new UnsupportedOperationException("Unsupported type: " + dataType);
     }
diff --git a/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/row/VariantShreddingInferenceInternalRowFileWriter.java b/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/row/VariantShreddingInferenceInternalRowFileWriter.java
new file mode 100644
index 000000000000..39dc3dc5e4df
--- /dev/null
+++ b/hudi-client/hudi-spark-client/src/main/java/org/apache/hudi/io/storage/row/VariantShreddingInferenceInternalRowFileWriter.java
@@ -0,0 +1,260 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hudi.io.storage.row;
+
+import org.apache.hudi.SparkAdapterSupport$;
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer;
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer.VariantSample;
+import org.apache.hudi.common.schema.HoodieSchema;
+import org.apache.hudi.common.util.CloseableUtils;
+import org.apache.hudi.common.util.DefaultSizeEstimator;
+import org.apache.hudi.core.io.storage.VariantShreddingInferenceFileWriter;
+
+import lombok.extern.slf4j.Slf4j;
+import org.apache.spark.sql.catalyst.InternalRow;
+import org.apache.spark.sql.catalyst.expressions.UnsafeRow;
+import org.apache.spark.sql.types.StructField;
+import org.apache.spark.sql.types.StructType;
+import org.apache.spark.unsafe.types.UTF8String;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A {@link HoodieInternalRowFileWriter} decorator that infers a per-file variant shredding
+ * schema from the first rows before opening the real parquet writer; the row-writer-path
+ * sibling of {@link VariantShreddingInferenceFileWriter}, sharing its buffering thresholds and
+ * failure semantics.
+ *
+ * <p>Meta columns including the commit seqno are composed into the row by the handle BEFORE
+ * {@code writeRow}, so ordered replay is value-exact here by construction. Rows and keys are
+ * copied because Spark iterators reuse their instances.</p>
+ */
+@Slf4j
+public class VariantShreddingInferenceInternalRowFileWriter implements HoodieInternalRowFileWriter {
+
+  private static final int SIZE_ESTIMATE_INTERVAL = 100;
+
+  /** Creates the real row file writer once the inferred typed_value schemas are known. */
+  @FunctionalInterface
+  public interface InferredRowWriterFactory {
+    HoodieInternalRowFileWriter create(Map<String, HoodieSchema> inferredTypedValues) throws IOException;
+  }
+
+  private final List<String> variantColumns;
+  private final int[] ordinals;
+  private final VariantShreddingSchemaInferrer inferrer;
+  private final InferredRowWriterFactory writerFactory;
+  private final long maxBufferedBytes;
+  private final DefaultSizeEstimator<InternalRow> sizeEstimator = new DefaultSizeEstimator<>();
+
+  private final List<BufferedRow> buffer = new ArrayList<>();
+  private final List<VariantSample[]> samples = new ArrayList<>();
+  private long bufferedBytes = 0;
+  private long estimatedRowSize = 0;
+  private long estimatedRowCount = 0;
+  private HoodieInternalRowFileWriter delegate;
+  private IOException fatalFailure;
+  private boolean closed = false;
+
+  public VariantShreddingInferenceInternalRowFileWriter(List<String> variantColumns,
+                                                        int[] ordinals,
+                                                        VariantShreddingSchemaInferrer inferrer,
+                                                        InferredRowWriterFactory writerFactory,
+                                                        long maxFileSize) {
+    this.variantColumns = variantColumns;
+    this.ordinals = ordinals;
+    this.inferrer = inferrer;
+    this.writerFactory = writerFactory;
+    this.maxBufferedBytes = Math.min(VariantShreddingInferenceFileWriter.MAX_BUFFERED_BYTES, Math.max(1, maxFileSize));
+  }
+
+  /** Resolves the buffer ordinal of each variant column in {@code structType}; -1 when absent. */
+  public static int[] resolveOrdinals(StructType structType, List<String> columnNames) {
+    int[] ordinals = new int[columnNames.size()];
+    StructField[] fields = structType.fields();
+    for (int i = 0; i < columnNames.size(); i++) {
+      ordinals[i] = -1;
+      for (int j = 0; j < fields.length; j++) {
+        if (fields[j].name().equals(columnNames.get(i))) {
+          ordinals[i] = j;
+          break;
+        }
+      }
+    }
+    return ordinals;
+  }
+
+  @Override
+  public boolean canWrite() {
+    // Nothing has been physically written while buffering, so size-based rollover cannot apply yet.
+    return delegate == null || delegate.canWrite();
+  }
+
+  @Override
+  public void writeRow(UTF8String key, InternalRow row) throws IOException {
+    rethrowIfFailed();
+    if (delegate != null) {
+      delegate.writeRow(key, row);
+    } else {
+      // copy(): Spark iterators reuse key instances.
+      buffer(key == null ? null : key.copy(), true, row);
+    }
+  }
+
+  @Override
+  public void writeRow(InternalRow row) throws IOException {
+    rethrowIfFailed();
+    if (delegate != null) {
+      delegate.writeRow(row);
+    } else {
+      buffer(null, false, row);
+    }
+  }
+
+  @Override
+  public void close() throws IOException {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    boolean delegateClosed = false;
+    try {
+      rethrowIfFailed();
+      // Materialize even with an empty buffer: handles expect the file to exist at close.
+      materialize();
+      // Mark before close() so a throwing delegate.close() surfaces, not retried in the catch.
+      delegateClosed = true;
+      delegate.close();
+    } catch (IOException | RuntimeException | Error e) {
+      // Error included: materialize() rethrows the Error it latches, and the delegate it
+      // created must still be closed.
+      if (delegate != null && !delegateClosed) {
+        // HoodieInternalRowFileWriter is not an AutoCloseable, hence the method reference.
+        CloseableUtils.closeSuppressing(delegate::close, e);
+      }
+      throw e;
+    }
+  }
+
+  private void buffer(UTF8String key, boolean withKey, InternalRow row) throws IOException {
+    rethrowIfFailed();
+    InternalRow copied = row.copy();
+    samples.add(extractSamples(copied));
+    buffer.add(new BufferedRow(key, withKey, copied));
+    chargeSize(copied);
+    if (buffer.size() >= VariantShreddingInferenceFileWriter.MAX_BUFFERED_RECORDS || bufferedBytes >= maxBufferedBytes) {
+      materialize();
+    }
+  }
+
+  private VariantSample[] extractSamples(InternalRow row) {
+    VariantSample[] out = new VariantSample[ordinals.length];
+    for (int i = 0; i < ordinals.length; i++) {
+      if (ordinals[i] >= 0) {
+        out[i] = SparkAdapterSupport$.MODULE$.sparkAdapter().extractVariantBinary(row, ordinals[i]);
+      }
+    }
+    return out;
+  }
+
+  /** Charges {@code row} against the byte cap: an exact size for an UnsafeRow, an estimate otherwise. */
+  private void chargeSize(InternalRow row) {
+    if (row instanceof UnsafeRow) {
+      bufferedBytes += ((UnsafeRow) row).getSizeInBytes();
+      return;
+    }
+    // Re-estimate periodically so a small first row cannot defeat the byte cap
+    // (same moving-average idiom as ExternalSpillableMap).
+    estimatedRowCount++;
+    if (estimatedRowSize == 0 || estimatedRowCount % SIZE_ESTIMATE_INTERVAL == 0) {
+      long previous = estimatedRowSize;
+      long sampled = Math.max(1, sizeEstimator.sizeEstimate(row));
+      estimatedRowSize = estimatedRowSize == 0
+          ? sampled : (long) (estimatedRowSize * 0.9 + sampled * 0.1);
+      // Rescale the rows already charged at the old estimate, or the cap would trip late once the
+      // estimate grew. Only the estimated ones: the UnsafeRow branch above charges exact sizes.
+      bufferedBytes += (estimatedRowCount - 1) * (estimatedRowSize - previous);
+    }
+    bufferedBytes += estimatedRowSize;
+  }
+
+  private void materialize() throws IOException {
+    if (delegate != null) {
+      return;
+    }
+    try {
+      delegate = writerFactory.create(inferTypedValues());
+      for (BufferedRow buffered : buffer) {
+        if (buffered.withKey) {
+          delegate.writeRow(buffered.key, buffered.row);
+        } else {
+          delegate.writeRow(buffered.row);
+        }
+      }
+      buffer.clear();
+      samples.clear();
+    } catch (IOException e) {
+      fatalFailure = e;
+      throw e;
+    } catch (RuntimeException | Error e) {
+      // Error latches too: inferTypedValues() already treats a LinkageError as reachable, and an
+      // unlatched failure would let close() finish the file without the un-replayed rows.
+      fatalFailure = new IOException("Deferred parquet row writer materialization failed", e);
+      throw e;
+    }
+  }
+
+  private Map<String, HoodieSchema> inferTypedValues() {
+    if (samples.isEmpty()) {
+      return Collections.emptyMap();
+    }
+    try {
+      Map<String, HoodieSchema> inferred = inferrer.inferTypedValueSchemas(variantColumns, samples);
+      return inferred == null ? Collections.emptyMap() : inferred;
+    } catch (Exception | LinkageError e) {
+      // LinkageError too: an inferrer linked against another Spark than the runtime's must
+      // degrade to unshredded like any other inference failure, not fail the write.
+      log.warn("Variant shredding schema inference failed for columns {}; writing unshredded variants.",
+          variantColumns, e);
+      return Collections.emptyMap();
+    }
+  }
+
+  private void rethrowIfFailed() throws IOException {
+    if (fatalFailure != null) {
+      throw fatalFailure;
+    }
+  }
+
+  private static final class BufferedRow {
+    private final UTF8String key;
+    private final boolean withKey;
+    private final InternalRow row;
+
+    BufferedRow(UTF8String key, boolean withKey, InternalRow row) {
+      this.key = key;
+      this.withKey = withKey;
+      this.row = row;
+    }
+  }
+}
diff --git a/hudi-client/hudi-spark-client/src/main/scala/org/apache/spark/sql/hudi/SparkAdapter.scala b/hudi-client/hudi-spark-client/src/main/scala/org/apache/spark/sql/hudi/SparkAdapter.scala
index f0b6292af455..03c266c96666 100644
--- a/hudi-client/hudi-spark-client/src/main/scala/org/apache/spark/sql/hudi/SparkAdapter.scala
+++ b/hudi-client/hudi-spark-client/src/main/scala/org/apache/spark/sql/hudi/SparkAdapter.scala
@@ -20,6 +20,7 @@ package org.apache.spark.sql.hudi
 
 import org.apache.hudi.{HoodiePartitionCDCFileGroupMapping, HoodiePartitionFileSliceMapping}
 import org.apache.hudi.client.model.HoodieInternalRow
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer
 import org.apache.hudi.common.model.FileSlice
 import org.apache.hudi.common.schema.HoodieSchema
 import org.apache.hudi.common.table.HoodieTableMetaClient
@@ -28,7 +29,7 @@ import org.apache.hudi.common.util.{Option => HOption}
 import org.apache.hudi.storage.StorageConfiguration
 
 import org.apache.hadoop.conf.Configuration
-import org.apache.parquet.schema.{MessageType, Type}
+import org.apache.parquet.schema.{GroupType, MessageType, Type, Types}
 import org.apache.parquet.schema.Type.Repetition
 import org.apache.spark.api.java.JavaSparkContext
 import org.apache.spark.rdd.RDD
@@ -484,6 +485,14 @@ trait SparkAdapter extends Serializable {
     repetition: Repetition
   ): Type
 
+  /**
+   * Applies the Parquet VARIANT logical type annotation to a shredded variant group builder so
+   * external readers recognize the column as a Variant. Only meaningful on parquet 1.16+
+   * (Spark 4.1+); the default leaves the builder unchanged because the annotation type does not
+   * exist on earlier parquet (Spark 3.x never shreds variants, Spark 4.0 ships parquet 1.15.2).
+   */
+  def applyVariantLogicalType(builder: Types.GroupBuilder[GroupType]): Types.GroupBuilder[GroupType] = builder
+
   /**
    * Checks if a StructType represents a shredded Variant schema (has special shredding metadata).
    * This is used during writing to identify columns that need special shredding handling.
@@ -564,6 +573,14 @@ trait SparkAdapter extends Serializable {
     writeStruct: Consumer[InternalRow]
   ): BiConsumer[SpecializedGetters, Integer]
 
+  /**
+   * Extracts the raw binaries of a variant column value from a row, as defensive copies.
+   * Used to sample variant binaries for shredding-schema inference.
+   *
+   * Returns null when the value is null or the Spark version has no variant support (3.x).
+   */
+  def extractVariantBinary(row: SpecializedGetters, ordinal: Int): VariantShreddingSchemaInferrer.VariantSample = null
+
   /**
    * Creates a [[HoodieMemoryStream]] wrapper around Spark's MemoryStream.
    * This abstracts the package differences between Spark versions:
diff --git a/hudi-client/hudi-spark-client/src/test/java/org/apache/hudi/io/storage/TestSparkVariantSampleExtractor.java b/hudi-client/hudi-spark-client/src/test/java/org/apache/hudi/io/storage/TestSparkVariantSampleExtractor.java
new file mode 100644
index 000000000000..8cede04759fb
--- /dev/null
+++ b/hudi-client/hudi-spark-client/src/test/java/org/apache/hudi/io/storage/TestSparkVariantSampleExtractor.java
@@ -0,0 +1,122 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hudi.io.storage;
+
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer.VariantSample;
+import org.apache.hudi.common.model.HoodieAvroIndexedRecord;
+import org.apache.hudi.common.model.HoodieKey;
+import org.apache.hudi.common.model.HoodieRecord;
+import org.apache.hudi.common.model.HoodieSparkRecord;
+import org.apache.hudi.common.schema.HoodieSchema;
+import org.apache.hudi.common.schema.HoodieSchemaField;
+import org.apache.hudi.common.schema.HoodieSchemaType;
+import org.apache.hudi.common.util.ObjectSizeCalculator;
+
+import org.apache.avro.generic.GenericData;
+import org.apache.avro.generic.GenericRecord;
+import org.apache.spark.sql.catalyst.InternalRow;
+import org.apache.spark.sql.catalyst.expressions.GenericInternalRow;
+import org.apache.spark.sql.types.DataTypes;
+import org.apache.spark.sql.types.StructType;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.Properties;
+
+import static java.util.Collections.singletonList;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotSame;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+
+/**
+ * The branches of {@link SparkVariantSampleExtractor} that need no Spark adapter: ordinal
+ * resolution, the absent-column and non-row (delete payload) legs, the shared-size estimate and
+ * the detaching prepare(). Extraction of a present column goes through
+ * {@code SparkAdapter.extractVariantBinary} and is covered by the functional inference tests.
+ */
+public class TestSparkVariantSampleExtractor {
+
+  private static final HoodieSchema SCHEMA = HoodieSchema.createRecord("rec", "ns", null, Arrays.asList(
+      HoodieSchemaField.of("id", HoodieSchema.create(HoodieSchemaType.LONG)),
+      HoodieSchemaField.of("v", HoodieSchema.createNullable(HoodieSchema.createVariant()))));
+  private static final StructType STRUCT_TYPE = new StructType()
+      .add("id", DataTypes.LongType)
+      .add("v", DataTypes.BinaryType);
+  private static final Properties PROPS = new Properties();
+  private static final HoodieKey KEY = new HoodieKey("r1", "p");
+
+  @Test
+  public void testAbsentColumnYieldsNullSample() throws Exception {
+    // "w" is not in the row's StructType: sampled as null (ordinal -1), never through the adapter.
+    SparkVariantSampleExtractor extractor = new SparkVariantSampleExtractor(singletonList("w"), STRUCT_TYPE);
+    GenericInternalRow row = new GenericInternalRow(new Object[] {1L, null});
+    VariantSample[] samples = extractor.extract(new HoodieSparkRecord(KEY, row, STRUCT_TYPE, false), SCHEMA, PROPS);
+    assertEquals(1, samples.length);
+    assertNull(samples[0]);
+  }
+
+  @Test
+  public void testNonRowDataYieldsNullSamples() throws Exception {
+    // A record whose data is not an InternalRow (a delete payload) contributes one empty slot per column.
+    SparkVariantSampleExtractor extractor = new SparkVariantSampleExtractor(Arrays.asList("v", "w"), STRUCT_TYPE);
+    GenericRecord avroData = new GenericData.Record(SCHEMA.toAvroSchema());
+    avroData.put("id", 1L);
+    VariantSample[] samples = extractor.extract(new HoodieAvroIndexedRecord(KEY, avroData), SCHEMA, PROPS);
+    assertEquals(2, samples.length);
+    assertNull(samples[0]);
+    assertNull(samples[1]);
+  }
+
+  @Test
+  public void testSharedSizeIsTheStructType() {
+    // Every Spark record of the file references the (cached) StructType; the decorator subtracts
+    // it from each record's size estimate so the byte cap is not consumed by the schema.
+    SparkVariantSampleExtractor extractor = new SparkVariantSampleExtractor(singletonList("v"), STRUCT_TYPE);
+    assertEquals(ObjectSizeCalculator.getObjectSize(STRUCT_TYPE), extractor.sharedSizeEstimate(SCHEMA));
+  }
+
+  @Test
+  public void testPrepareDetachesTheBufferedRecord() {
+    // copy() deep-copies the row but hands back the caller's own wrapper, which the merge handle
+    // deflates as soon as the write call returns; the buffer must hold a wrapper of its own.
+    SparkVariantSampleExtractor extractor = new SparkVariantSampleExtractor(singletonList("v"), STRUCT_TYPE);
+    GenericInternalRow row = new GenericInternalRow(new Object[] {1L, null});
+    HoodieSparkRecord record = new HoodieSparkRecord(KEY, row, STRUCT_TYPE, false);
+
+    HoodieRecord prepared = extractor.prepare(record, SCHEMA, PROPS);
+    assertNotSame(record, prepared);
+    // The row itself is not re-copied: the decorator already copied it before calling prepare().
+    assertSame(row, prepared.getData());
+    assertEquals(KEY, prepared.getKey());
+
+    record.deflate();
+    assertEquals(1L, ((InternalRow) prepared.getData()).getLong(0));
+  }
+
+  @Test
+  public void testPrepareLeavesNonRowRecordsAlone() {
+    // A delete payload has no row to detach from the caller.
+    SparkVariantSampleExtractor extractor = new SparkVariantSampleExtractor(singletonList("v"), STRUCT_TYPE);
+    GenericRecord avroData = new GenericData.Record(SCHEMA.toAvroSchema());
+    avroData.put("id", 1L);
+    HoodieAvroIndexedRecord record = new HoodieAvroIndexedRecord(KEY, avroData);
+    assertSame(record, extractor.prepare(record, SCHEMA, PROPS));
+  }
+}
diff --git a/hudi-client/hudi-spark-client/src/test/java/org/apache/hudi/io/storage/row/TestVariantShreddingInferenceInternalRowFileWriter.java b/hudi-client/hudi-spark-client/src/test/java/org/apache/hudi/io/storage/row/TestVariantShreddingInferenceInternalRowFileWriter.java
new file mode 100644
index 000000000000..d02ce6a21aaa
--- /dev/null
+++ b/hudi-client/hudi-spark-client/src/test/java/org/apache/hudi/io/storage/row/TestVariantShreddingInferenceInternalRowFileWriter.java
@@ -0,0 +1,481 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hudi.io.storage.row;
+
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer;
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer.VariantSample;
+import org.apache.hudi.common.schema.HoodieSchema;
+import org.apache.hudi.common.schema.HoodieSchemaType;
+import org.apache.hudi.common.util.DefaultSizeEstimator;
+import org.apache.hudi.core.io.storage.VariantShreddingInferenceFileWriter;
+
+import org.apache.spark.sql.catalyst.InternalRow;
+import org.apache.spark.sql.catalyst.expressions.GenericInternalRow;
+import org.apache.spark.sql.catalyst.expressions.UnsafeRow;
+import org.apache.spark.sql.types.DataTypes;
+import org.apache.spark.sql.types.StructType;
+import org.apache.spark.unsafe.types.UTF8String;
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static java.util.Collections.singletonList;
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * The row-writer sibling of {@code TestVariantShreddingInferenceFileWriter}. The decorator is
+ * driven with ordinals of -1 (the column absent from the row's StructType), which is the
+ * sampling branch that needs no Spark adapter on the classpath; sample extraction itself goes
+ * through {@code SparkAdapter.extractVariantBinary} and is covered by the functional tests.
+ */
+public class TestVariantShreddingInferenceInternalRowFileWriter {
+
+  private static final int[] ABSENT_COLUMN = {-1};
+
+  private static InternalRow row(long id) {
+    return new GenericInternalRow(new Object[] {id});
+  }
+
+  /** A row of about a kilobyte, so byte-cap arithmetic on the estimator is not dominated by rounding. */
+  private static InternalRow wideRow(long id) {
+    return new GenericInternalRow(new Object[] {id, UTF8String.fromString(new String(new char[1024]).replace('\0', 'x'))});
+  }
+
+  /** A row of a few megabytes, to dwarf {@link #row(long)} in the byte-cap re-estimation test. */
+  private static InternalRow bigRow(long id) {
+    return new GenericInternalRow(new Object[] {id, UTF8String.fromString(new String(new char[1 << 22]).replace('\0', 'x'))});
+  }
+
+  /** A 16-byte UnsafeRow (8-byte null bitset + one long), so byte-cap arithmetic is exact. */
+  private static UnsafeRow unsafeRow(long id) {
+    return unsafeRow(id, 16);
+  }
+
+  /** An UnsafeRow of exactly {@code sizeInBytes} bytes, holding one long. */
+  private static UnsafeRow unsafeRow(long id, int sizeInBytes) {
+    UnsafeRow row = new UnsafeRow(1);
+    byte[] buffer = new byte[sizeInBytes];
+    row.pointTo(buffer, sizeInBytes);
+    row.setLong(0, id);
+    return row;
+  }
+
+  /** Records every call so replay order and call kinds can be asserted. */
+  private static class RecordingRowWriter implements HoodieInternalRowFileWriter {
+    private final List<String> calls = new ArrayList<>();
+    private final List<InternalRow> rows = new ArrayList<>();
+    private int closeCount = 0;
+    /** An IOException or an Error; anything else is a misuse of the stub. */
+    private Throwable failWriteWith;
+    private IOException failCloseWith;
+
+    @Override
+    public boolean canWrite() {
+      return true;
+    }
+
+    @Override
+    public void writeRow(UTF8String key, InternalRow row) throws IOException {
+      failIfConfigured(failWriteWith);
+      calls.add("keyed:" + key);
+      rows.add(row);
+    }
+
+    @Override
+    public void writeRow(InternalRow row) throws IOException {
+      failIfConfigured(failWriteWith);
+      calls.add("plain:" + row.getLong(0));
+      rows.add(row);
+    }
+
+    @Override
+    public void close() throws IOException {
+      closeCount++;
+      failIfConfigured(failCloseWith);
+    }
+
+    private static void failIfConfigured(Throwable failure) throws IOException {
+      if (failure instanceof Error) {
+        throw (Error) failure;
+      } else if (failure != null) {
+        throw (IOException) failure;
+      }
+    }
+  }
+
+  private static VariantShreddingInferenceInternalRowFileWriter writer(
+      int[] ordinals,
+      VariantShreddingInferenceInternalRowFileWriter.InferredRowWriterFactory factory,
+      long maxFileSize) {
+    return writer(ordinals, (columns, samples) -> Collections.emptyMap(), factory, maxFileSize);
+  }
+
+  private static VariantShreddingInferenceInternalRowFileWriter writer(
+      int[] ordinals,
+      VariantShreddingSchemaInferrer inferrer,
+      VariantShreddingInferenceInternalRowFileWriter.InferredRowWriterFactory factory,
+      long maxFileSize) {
+    return new VariantShreddingInferenceInternalRowFileWriter(singletonList("v"), ordinals, inferrer, factory, maxFileSize);
+  }
+
+  @Test
+  public void testResolveOrdinals() {
+    StructType structType = new StructType()
+        .add("id", DataTypes.LongType)
+        .add("v", DataTypes.BinaryType)
+        .add("w", DataTypes.BinaryType);
+    // Present columns map to their ordinal; an absent one maps to -1 and is sampled as null.
+    assertArrayEquals(new int[] {2, 1, -1},
+        VariantShreddingInferenceInternalRowFileWriter.resolveOrdinals(structType, Arrays.asList("w", "v", "missing")));
+    assertArrayEquals(new int[0],
+        VariantShreddingInferenceInternalRowFileWriter.resolveOrdinals(structType, Collections.emptyList()));
+  }
+
+  @Test
+  public void testReplayPreservesOrderAndCallKinds() throws IOException {
+    Map<String, HoodieSchema> inferred = new HashMap<>();
+    inferred.put("v", HoodieSchema.create(HoodieSchemaType.LONG));
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    List<List<VariantSample[]>> seenSamples = new ArrayList<>();
+    RecordingRowWriter delegate = new RecordingRowWriter();
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN,
+        (columns, samples) -> {
+          seenSamples.add(new ArrayList<>(samples));
+          return inferred;
+        },
+        map -> {
+          factoryCalls.add(map);
+          return delegate;
+        }, Long.MAX_VALUE);
+
+    assertTrue(writer.canWrite());
+    writer.writeRow(UTF8String.fromString("k1"), row(1));
+    writer.writeRow(row(2));
+    writer.writeRow(UTF8String.fromString("k3"), row(3));
+    assertTrue(delegate.calls.isEmpty(), "rows are buffered until materialization");
+
+    writer.close();
+    assertEquals(1, factoryCalls.size());
+    assertSame(inferred, factoryCalls.get(0));
+    assertEquals(Arrays.asList("keyed:k1", "plain:2", "keyed:k3"), delegate.calls);
+    // One sample slot per row, null for the absent column.
+    assertEquals(3, seenSamples.get(0).size());
+    assertEquals(1, seenSamples.get(0).get(0).length);
+    assertNull(seenSamples.get(0).get(0)[0]);
+    assertEquals(1, delegate.closeCount);
+
+    // Idempotent close.
+    writer.close();
+    assertEquals(1, factoryCalls.size());
+    assertEquals(1, delegate.closeCount);
+  }
+
+  @Test
+  public void testBufferedRowsAreCopies() throws IOException {
+    // Spark iterators reuse row instances: the buffered row must be a copy taken at write time.
+    RecordingRowWriter delegate = new RecordingRowWriter();
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> delegate, Long.MAX_VALUE);
+    GenericInternalRow reused = new GenericInternalRow(new Object[] {1L});
+    writer.writeRow(reused);
+    reused.update(0, 2L);
+    writer.writeRow(reused);
+    writer.close();
+    assertEquals(Arrays.asList("plain:1", "plain:2"), delegate.calls);
+    assertFalse(delegate.rows.get(0) == reused);
+  }
+
+  @Test
+  public void testBufferedKeysAreCopies() throws IOException {
+    // Keys are reused by Spark iterators too: a key over a mutable buffer must be copied at write
+    // time, or the replay would carry whatever the buffer holds by then.
+    RecordingRowWriter delegate = new RecordingRowWriter();
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> delegate, Long.MAX_VALUE);
+    byte[] keyBytes = "k1".getBytes(StandardCharsets.UTF_8);
+    UTF8String reusedKey = UTF8String.fromBytes(keyBytes);
+    writer.writeRow(reusedKey, row(1));
+    keyBytes[1] = '2';
+    writer.writeRow(reusedKey, row(2));
+    writer.close();
+    assertEquals(Arrays.asList("keyed:k1", "keyed:k2"), delegate.calls);
+  }
+
+  @Test
+  public void testByteCapRechargesTheBufferWhenTheEstimateGrows() throws IOException {
+    // 99 small estimated rows, then a big 100th that lands on the periodic re-estimation. The
+    // moving average grows to about 0.9 * small + 0.1 * big, and the re-estimation recharges the
+    // 99 earlier rows at that too, so the buffer (about 90 small + 10 big) meets a cap of one big
+    // row right there. Without the recharge the 99 would stay charged at small, and about 100
+    // small plus a tenth of big would leave the cap untripped: the precondition keeps that gap.
+    DefaultSizeEstimator<InternalRow> estimator = new DefaultSizeEstimator<>();
+    long small = estimator.sizeEstimate(row(0));
+    long big = estimator.sizeEstimate(bigRow(99));
+    assertTrue(big > 200 * small, "expected the big row to dwarf the small ones: " + small + " vs " + big);
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> {
+      factoryCalls.add(map);
+      return new RecordingRowWriter();
+    }, big);
+
+    for (int i = 0; i < 99; i++) {
+      writer.writeRow(row(i));
+    }
+    assertTrue(factoryCalls.isEmpty(), "99 small rows stay under a one-big-row cap");
+    writer.writeRow(bigRow(99));
+    assertEquals(1, factoryCalls.size(), "the re-estimation on the 100th row recharges the buffer past the cap");
+    writer.close();
+  }
+
+  @Test
+  public void testUnsafeRowChargesSurviveReEstimation() throws IOException {
+    // UnsafeRows are charged exactly and other rows through the estimator, in one byte count. The
+    // re-estimation on the 100th estimated row recharges the estimated rows only; assigning the
+    // estimated total instead (what the record writer does, having no exact charges) would drop
+    // the UnsafeRow's bytes. So an UnsafeRow among 100 same-shaped estimated rows meets a cap of
+    // its size plus 100 rows' worth, less a slack that the estimated rows alone cannot cover.
+    long perRow = new DefaultSizeEstimator<InternalRow>().sizeEstimate(wideRow(0));
+    assertTrue(perRow > 1000, "expected a kilobyte-sized row, got " + perRow);
+    int unsafeRowSize = 4096;
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> {
+      factoryCalls.add(map);
+      return new RecordingRowWriter();
+    }, unsafeRowSize + 100 * perRow - 500);
+
+    for (int i = 0; i < 50; i++) {
+      writer.writeRow(wideRow(i));
+    }
+    writer.writeRow(unsafeRow(50, unsafeRowSize));
+    for (int i = 51; i < 100; i++) {
+      writer.writeRow(wideRow(i));
+    }
+    assertTrue(factoryCalls.isEmpty(), "the UnsafeRow plus 99 estimated rows stay under the cap");
+    writer.writeRow(wideRow(100));
+    assertEquals(1, factoryCalls.size(), "the 100th estimated row's re-estimation keeps the UnsafeRow's bytes and meets the cap");
+    writer.close();
+  }
+
+  @Test
+  public void testRecordCountThresholdTriggersMaterialization() throws IOException {
+    RecordingRowWriter delegate = new RecordingRowWriter();
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> {
+      factoryCalls.add(map);
+      return delegate;
+    }, Long.MAX_VALUE);
+
+    for (int i = 0; i < VariantShreddingInferenceFileWriter.MAX_BUFFERED_RECORDS; i++) {
+      writer.writeRow(row(i));
+    }
+    // Threshold reached: delegate created and buffer replayed before close.
+    assertEquals(1, factoryCalls.size());
+    assertEquals(VariantShreddingInferenceFileWriter.MAX_BUFFERED_RECORDS, delegate.calls.size());
+    // Subsequent rows stream straight through.
+    writer.writeRow(row(-1));
+    assertEquals(VariantShreddingInferenceFileWriter.MAX_BUFFERED_RECORDS + 1, delegate.calls.size());
+    writer.close();
+    assertEquals(1, factoryCalls.size());
+  }
+
+  @Test
+  public void testUnsafeRowByteCapTriggersMaterialization() throws IOException {
+    // UnsafeRow sizes are exact (no estimator): two 16-byte rows meet a 32-byte cap.
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> {
+      factoryCalls.add(map);
+      return new RecordingRowWriter();
+    }, 32L);
+
+    writer.writeRow(unsafeRow(1));
+    assertTrue(factoryCalls.isEmpty(), "16 of 32 bytes buffered");
+    writer.writeRow(unsafeRow(2));
+    assertEquals(1, factoryCalls.size(), "32 of 32 bytes buffered: materialize");
+    writer.close();
+  }
+
+  @Test
+  public void testByteCapIsBoundedByTheSharedMaximum() throws IOException {
+    // The cap is min(MAX_BUFFERED_BYTES, maxFileSize): a file size limit above 64MB must not lift
+    // the buffer above 64MB. One UnsafeRow reporting exactly the maximum meets it on its own. The
+    // row is really allocated: the decorator copies it, and copy() reads sizeInBytes bytes.
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> {
+      factoryCalls.add(map);
+      return new RecordingRowWriter();
+    }, Long.MAX_VALUE);
+
+    writer.writeRow(unsafeRow(1, (int) VariantShreddingInferenceFileWriter.MAX_BUFFERED_BYTES));
+    assertEquals(1, factoryCalls.size(), "a row at the shared maximum materializes whatever the file size limit");
+    writer.close();
+  }
+
+  @Test
+  public void testEstimatedByteCapTriggersEarlyMaterialization() throws IOException {
+    // Non-UnsafeRow rows go through the size estimator; a 1-byte cap is exceeded by any row.
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> {
+      factoryCalls.add(map);
+      return new RecordingRowWriter();
+    }, 1L);
+    writer.writeRow(row(1));
+    assertEquals(1, factoryCalls.size());
+    writer.close();
+  }
+
+  @Test
+  public void testInferrerFailureDeclinesAndWritesUnshredded() throws IOException {
+    RecordingRowWriter delegate = new RecordingRowWriter();
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN,
+        (columns, samples) -> {
+          throw new IllegalStateException("malformed variant");
+        },
+        map -> {
+          factoryCalls.add(map);
+          return delegate;
+        }, Long.MAX_VALUE);
+
+    writer.writeRow(row(1));
+    writer.close();
+    assertEquals(1, factoryCalls.size());
+    assertTrue(factoryCalls.get(0).isEmpty());
+    assertEquals(singletonList("plain:1"), delegate.calls);
+  }
+
+  @Test
+  public void testZeroRowCloseStillCreatesDelegate() throws IOException {
+    RecordingRowWriter delegate = new RecordingRowWriter();
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN,
+        (columns, samples) -> {
+          throw new AssertionError("inferrer must not be called with an empty buffer");
+        },
+        map -> {
+          factoryCalls.add(map);
+          return delegate;
+        }, Long.MAX_VALUE);
+
+    writer.close();
+    assertEquals(1, factoryCalls.size());
+    assertTrue(factoryCalls.get(0).isEmpty());
+    assertEquals(1, delegate.closeCount);
+  }
+
+  @Test
+  public void testWriterCreationFailureIsLatchedAndRethrown() throws IOException {
+    IOException boom = new IOException("create failed");
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> {
+      throw boom;
+    }, Long.MAX_VALUE);
+
+    writer.writeRow(row(1));
+    assertSame(boom, assertThrows(IOException.class, writer::close));
+    // Every subsequent call keeps failing: buffered rows were never written.
+    assertSame(boom, assertThrows(IOException.class, () -> writer.writeRow(row(2))));
+    assertSame(boom, assertThrows(IOException.class, () -> writer.writeRow(UTF8String.fromString("k"), row(2))));
+  }
+
+  @Test
+  public void testReplayFailureIsLatchedAndDelegateClosedOnce() throws IOException {
+    RecordingRowWriter delegate = new RecordingRowWriter();
+    IOException boom = new IOException("replay failed");
+    delegate.failWriteWith = boom;
+    IOException closeBoom = new IOException("close failed");
+    delegate.failCloseWith = closeBoom;
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> delegate, Long.MAX_VALUE);
+
+    writer.writeRow(row(1));
+    IOException fromClose = assertThrows(IOException.class, writer::close);
+    assertSame(boom, fromClose);
+    // Created but never closed by the try path, so the catch path closes it exactly once, and a
+    // failure of that close rides along as suppressed rather than replacing or hiding boom.
+    assertEquals(1, delegate.closeCount);
+    assertSame(closeBoom, fromClose.getSuppressed()[0]);
+    assertSame(boom, assertThrows(IOException.class, () -> writer.writeRow(row(2))));
+  }
+
+  @Test
+  public void testReplayErrorIsLatchedTooAndCloseDoesNotFinishTheFile() throws IOException {
+    // An Error mid-replay latches like an exception does: inference already treats a LinkageError
+    // as reachable (a writer linked against another Spark than the runtime's), and an unlatched
+    // one would let close() finish the file without the rows left in the buffer.
+    RecordingRowWriter delegate = new RecordingRowWriter();
+    NoClassDefFoundError boom = new NoClassDefFoundError("replay failed");
+    delegate.failWriteWith = boom;
+    // A 1-byte cap materializes on the first row, so the Error surfaces from writeRow(), not close().
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> delegate, 1L);
+
+    assertSame(boom, assertThrows(NoClassDefFoundError.class, () -> writer.writeRow(row(1))));
+    assertSame(boom, assertThrows(IOException.class, writer::close).getCause());
+    assertEquals(1, delegate.closeCount);
+  }
+
+  @Test
+  public void testMaterializeErrorInsideCloseStillClosesTheDelegate() throws IOException {
+    // With the caps never tripped, the first materialization happens inside close(): the Error
+    // must still close the delegate created just above, or the file handle leaks.
+    RecordingRowWriter delegate = new RecordingRowWriter();
+    NoClassDefFoundError boom = new NoClassDefFoundError("replay failed");
+    delegate.failWriteWith = boom;
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> delegate, Long.MAX_VALUE);
+
+    writer.writeRow(row(1));
+    assertSame(boom, assertThrows(NoClassDefFoundError.class, writer::close));
+    assertEquals(1, delegate.closeCount);
+  }
+
+  @Test
+  public void testThrowingDelegateCloseSurfacesAndIsNotRetried() throws IOException {
+    RecordingRowWriter delegate = new RecordingRowWriter();
+    IOException boom = new IOException("close failed");
+    delegate.failCloseWith = boom;
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> delegate, Long.MAX_VALUE);
+
+    writer.writeRow(row(1));
+    assertSame(boom, assertThrows(IOException.class, writer::close));
+    assertEquals(1, delegate.closeCount, "a throwing delegate.close() must surface, not be retried");
+  }
+
+  @Test
+  public void testCanWriteDelegatesAfterMaterialization() throws IOException {
+    VariantShreddingInferenceInternalRowFileWriter writer = writer(ABSENT_COLUMN, map -> new RecordingRowWriter() {
+      @Override
+      public boolean canWrite() {
+        return false;
+      }
+    }, 1L);
+
+    assertTrue(writer.canWrite());
+    writer.writeRow(row(1));
+    assertFalse(writer.canWrite());
+    writer.close();
+  }
+}
diff --git a/hudi-common/src/main/java/org/apache/hudi/common/avro/AvroVariantSampleExtractor.java b/hudi-common/src/main/java/org/apache/hudi/common/avro/AvroVariantSampleExtractor.java
new file mode 100644
index 000000000000..21de783a2d4d
--- /dev/null
+++ b/hudi-common/src/main/java/org/apache/hudi/common/avro/AvroVariantSampleExtractor.java
@@ -0,0 +1,131 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.hudi.common.avro;
+
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer.VariantSample;
+import org.apache.hudi.common.model.HoodieAvroIndexedRecord;
+import org.apache.hudi.common.model.HoodieRecord;
+import org.apache.hudi.common.schema.HoodieSchema;
+import org.apache.hudi.common.util.ObjectSizeCalculator;
+import org.apache.hudi.common.util.Option;
+import org.apache.hudi.core.io.storage.VariantShreddingInferenceFileWriter.VariantSampleExtractor;
+
+import org.apache.avro.Schema;
+import org.apache.avro.generic.GenericRecord;
+import org.apache.avro.generic.IndexedRecord;
+
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Properties;
+
+/**
+ * Extracts variant binaries from Avro-backed ({@code HoodieRecordType.AVRO}) records, where an
+ * unshredded variant column materializes as a {@code {metadata: bytes, value: bytes}} record.
+ */
+public class AvroVariantSampleExtractor implements VariantSampleExtractor {
+
+  private final List<String> columnNames;
+  // Memoized per schema instance: the per-call schema is the same object for every record of a file.
+  private HoodieSchema sizedSchema;
+  private long sizedSchemaBytes;
+
+  public AvroVariantSampleExtractor(List<String> columnNames) {
+    this.columnNames = columnNames;
+  }
+
+  /**
+   * The Avro {@code Schema} graph every materialized record references; measured once per schema
+   * instance, since a deep size walk would otherwise charge it to every buffered record (the
+   * {@link AvroRecordSizeEstimator} idiom).
+   */
+  @Override
+  public long sharedSizeEstimate(HoodieSchema schema) {
+    if (schema != sizedSchema) {
+      sizedSchema = schema;
+      sizedSchemaBytes = ObjectSizeCalculator.getObjectSize(schema.toAvroSchema());
+    }
+    return sizedSchemaBytes;
+  }
+
+  /**
+   * Materializes the record once up front: payload-backed records deserialize in
+   * {@code toIndexedRecord}, and the decorator replays what this returns, so the writer's own
+   * {@code toIndexedRecord} call at replay time is then a pass-through rather than a second
+   * deserialization (and a MERGE INTO expression payload evaluates once, not twice). Records
+   * without data (delete payloads) are buffered as they are.
+   */
+  @Override
+  public HoodieRecord prepare(HoodieRecord record, HoodieSchema schema, Properties props) throws IOException {
+    Option<HoodieAvroIndexedRecord> indexed = record.toIndexedRecord(schema, props);
+    return indexed.isPresent() ? indexed.get() : record;
+  }
+
+  @Override
+  public VariantSample[] extract(HoodieRecord record, HoodieSchema schema, Properties props) throws IOException {
+    VariantSample[] out = new VariantSample[columnNames.size()];
+    // A pass-through for the HoodieAvroIndexedRecord that prepare() buffered.
+    Option<HoodieAvroIndexedRecord> indexed = record.toIndexedRecord(schema, props);
+    if (!indexed.isPresent()) {
+      // Delete payload: no data to sample.
+      return out;
+    }
+    IndexedRecord data = indexed.get().getData();
+    Schema recordSchema = data.getSchema();
+    for (int i = 0; i < columnNames.size(); i++) {
+      // Lookup by name on the record's own schema: per-call schemas can differ from the
+      // writer schema (e.g. merge handles passing the table schema variant).
+      Schema.Field field = recordSchema.getField(columnNames.get(i));
+      if (field == null) {
+        continue;
+      }
+      Object value = data.get(field.pos());
+      if (value instanceof GenericRecord) {
+        GenericRecord variant = (GenericRecord) value;
+        byte[] valueBytes = copyBytes(variant, HoodieSchema.Variant.VARIANT_VALUE_FIELD);
+        byte[] metadataBytes = copyBytes(variant, HoodieSchema.Variant.VARIANT_METADATA_FIELD);
+        if (valueBytes != null && metadataBytes != null) {
+          out[i] = new VariantSample(valueBytes, metadataBytes);
+        }
+      }
+    }
+    return out;
+  }
+
+  private static byte[] copyBytes(GenericRecord variant, String fieldName) {
+    Schema.Field field = variant.getSchema().getField(fieldName);
+    if (field == null) {
+      return null;
+    }
+    Object value = variant.get(field.pos());
+    if (value instanceof ByteBuffer) {
+      ByteBuffer buffer = ((ByteBuffer) value).duplicate();
+      byte[] bytes = new byte[buffer.remaining()];
+      buffer.get(bytes);
+      return bytes;
+    }
+    if (value instanceof byte[]) {
+      byte[] bytes = (byte[]) value;
+      return Arrays.copyOf(bytes, bytes.length);
+    }
+    return null;
+  }
+}
diff --git a/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantSchemaUtils.java b/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantSchemaUtils.java
index a656fc5de875..8d6e40e4cf90 100644
--- a/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantSchemaUtils.java
+++ b/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantSchemaUtils.java
@@ -19,13 +19,20 @@
 
 package org.apache.hudi.common.avro;
 
+import org.apache.hudi.common.config.HoodieConfig;
+import org.apache.hudi.common.config.HoodieStorageConfig;
+import org.apache.hudi.common.config.TypedProperties;
 import org.apache.hudi.common.schema.HoodieSchema;
 import org.apache.hudi.common.schema.HoodieSchemaField;
 import org.apache.hudi.common.schema.HoodieSchemaType;
+import org.apache.hudi.common.schema.HoodieSchemaUtils;
 import org.apache.hudi.common.util.Option;
+import org.apache.hudi.common.util.StringUtils;
 
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
+import java.util.Map;
 
 /**
  * Shared helpers for converting between shredded and unshredded variant schemas.
@@ -34,6 +41,19 @@ import java.util.List;
  */
 public class VariantSchemaUtils {
 
+  // Defined in hudi-client's HoodieWriteConfig; referenced literally because hudi-common cannot
+  // depend on it (same precedent as "hoodie.index.type" in HoodieFileWriterFactory).
+  private static final String INTERNAL_SCHEMA_KEY = "hoodie.internal.schema";
+  private static final String WRITE_SCHEMA_OVERRIDE_KEY = "hoodie.write.schema";
+  private static final String AVRO_SCHEMA_KEY = "hoodie.avro.schema";
+
+  /**
+   * Namespace of the shredded record types {@link #applyInferredShredding} generates. Hudi-owned
+   * so the generated names ({@code <column>_variant}) cannot collide with a user-declared record
+   * type of the same simple name in the table schema.
+   */
+  private static final String INFERRED_VARIANT_NAMESPACE = "hoodie.variant.inferred";
+
   private VariantSchemaUtils() {
   }
 
@@ -123,6 +143,235 @@ public class VariantSchemaUtils {
     return wasNullable ? HoodieSchema.createNullable(replacement) : replacement;
   }
 
+  /**
+   * Strips {@code typed_value} from top-level fields that have the variant SHAPE but lost the
+   * variant logical type, i.e. plain records of {@code {metadata: bytes, value: [nullable]
+   * bytes, typed_value}} (see {@link #isShreddedVariantShape}). Parquet-footer-derived schemas
+   * come back this way (the converter does not attach the variant logical type), so
+   * {@link #stripVariantShredding} alone cannot see them. Used by the table-schema footer
+   * fallback only; returns {@code schema} as-is when nothing matches.
+   *
+   * <p>Unlike {@link #isShreddedVariantTarget}, the match here has NO requested-side anchor:
+   * the footer fallback runs precisely when no table schema is available to anchor on, so a
+   * plain user struct that happens to have exactly this shape is stripped too (a documented,
+   * accepted false positive: {@code metadata} plus {@code typed_value} is the variant spec's
+   * vocabulary). Top-level fields only, matching the scope of
+   * {@link #getInferableVariantColumns}: inference never shreds a nested variant, and
+   * {@code HoodieAvroWriteSupport.applyForcedShreddingSchema} walks top-level fields only. The row
+   * writer shreds at any depth its write schema asks it to, forced DDL or not (see
+   * {@link #swapShreddedVariantFields}); those nested layouts are not covered by this fallback.
+   *
+   * <p>The shape check also admits the spec's two-field {@code {metadata, typed_value}} form (a
+   * writer may omit {@code value} when every row is typed). Stripping that would leave a
+   * one-field record, so {@code value} is restored as nullable bytes: the result is always the
+   * unshredded {@code {metadata, value}} shape.
+   */
+  public static HoodieSchema stripVariantShreddingByShape(HoodieSchema schema) {
+    if (schema.getType() != HoodieSchemaType.RECORD) {
+      return schema;
+    }
+
+    List<HoodieSchemaField> newFields = new ArrayList<>();
+    boolean changed = false;
+
+    for (HoodieSchemaField field : schema.getFields()) {
+      HoodieSchema fieldSchema = field.schema();
+      boolean wasNullable = fieldSchema.isNullable();
+      HoodieSchema unwrapped = wasNullable ? fieldSchema.getNonNullType() : fieldSchema;
+
+      if (isShreddedVariantShape(unwrapped)) {
+        List<HoodieSchemaField> strippedFields = new ArrayList<>();
+        for (HoodieSchemaField member : unwrapped.getFields()) {
+          if (!HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD.equals(member.name())) {
+            strippedFields.add(HoodieSchemaUtils.createNewSchemaField(member));
+          }
+        }
+        if (!unwrapped.getField(HoodieSchema.Variant.VARIANT_VALUE_FIELD).isPresent()) {
+          // Null default, like every other optional field on this path (the footer converter
+          // attaches one, and kept members carry theirs over): HoodieSchemaField#equals compares
+          // defaults, so omitting it would make the stripped schema differ from the one a
+          // three-field file yields for the same column.
+          strippedFields.add(HoodieSchemaField.of(
+              HoodieSchema.Variant.VARIANT_VALUE_FIELD, HoodieSchema.createNullable(HoodieSchemaType.BYTES),
+              null, HoodieSchema.NULL_VALUE));
+        }
+        HoodieSchema stripped = HoodieSchema.createRecord(
+            unwrapped.getAvroSchema().getName(),
+            unwrapped.getAvroSchema().getNamespace(),
+            unwrapped.getAvroSchema().getDoc(),
+            strippedFields);
+        HoodieSchema replacement = wasNullable ? HoodieSchema.createNullable(stripped) : stripped;
+        newFields.add(HoodieSchemaUtils.createNewSchemaField(field.withSchema(replacement)));
+        changed = true;
+      } else {
+        newFields.add(HoodieSchemaUtils.createNewSchemaField(field));
+      }
+    }
+
+    if (!changed) {
+      return schema;
+    }
+
+    return HoodieSchema.createRecord(
+        schema.getAvroSchema().getName(),
+        schema.getAvroSchema().getNamespace(),
+        schema.getAvroSchema().getDoc(),
+        newFields);
+  }
+
+  /**
+   * The top-level variant columns of {@code schema} that are candidates for shredding-schema
+   * inference under {@code config}, or an empty list when inference does not apply.
+   *
+   * <p>Inference applies only when it is enabled, write shredding is enabled, no forced test
+   * DDL is set (force wins), and no internal schema is set (the Spark write support prefers the
+   * internal schema and would silently ignore an inferred one). Candidate columns are top-level
+   * unshredded variants; columns with an explicit typed_value keep their schema-driven shredding.</p>
+   */
+  public static List<String> getInferableVariantColumns(HoodieConfig config, HoodieSchema schema) {
+    return isShreddingInferenceEnabled(config) ? unshreddedTopLevelVariantColumns(schema) : Collections.emptyList();
+  }
+
+  /** The top-level unshredded variant columns of {@code schema}; empty when it is not a record. */
+  private static List<String> unshreddedTopLevelVariantColumns(HoodieSchema schema) {
+    if (schema.getType() != HoodieSchemaType.RECORD) {
+      return Collections.emptyList();
+    }
+    List<String> columns = new ArrayList<>();
+    for (HoodieSchemaField field : schema.getFields()) {
+      HoodieSchema unwrapped = field.schema().isNullable() ? field.schema().getNonNullType() : field.schema();
+      if (unwrapped.getType() == HoodieSchemaType.VARIANT && !((HoodieSchema.Variant) unwrapped).isShredded()) {
+        columns.add(field.name());
+      }
+    }
+    return columns;
+  }
+
+  /**
+   * {@link #getInferableVariantColumns} over the schema the config carries (see
+   * {@link #getConfigWriteSchema}), for write supports that resolve their schema from the config
+   * rather than a schema argument: detecting on that same schema guarantees the detection and the
+   * {@link #applyInferredShreddingToConfig} splice agree. Empty when inference does not apply or
+   * no schema is set; the schema is only parsed once the cheap config gates pass.
+   */
+  public static List<String> getInferableVariantColumnsFromConfig(HoodieConfig config) {
+    if (!isShreddingInferenceEnabled(config)) {
+      return Collections.emptyList();
+    }
+    return getConfigWriteSchema(config)
+        .map(VariantSchemaUtils::unshreddedTopLevelVariantColumns)
+        .orElse(Collections.emptyList());
+  }
+
+  /**
+   * The write schema carried by the config, {@code hoodie.write.schema} else
+   * {@code hoodie.avro.schema}, in that precedence (the one the Spark row write support resolves
+   * and the one {@link #applyInferredShreddingToConfig} splices into); empty when neither is set.
+   */
+  public static Option<HoodieSchema> getConfigWriteSchema(HoodieConfig config) {
+    String schemaString = config.getString(WRITE_SCHEMA_OVERRIDE_KEY);
+    if (StringUtils.isNullOrEmpty(schemaString)) {
+      schemaString = config.getString(AVRO_SCHEMA_KEY);
+    }
+    return StringUtils.isNullOrEmpty(schemaString) ? Option.empty() : Option.of(HoodieSchema.parse(schemaString));
+  }
+
+  /**
+   * Whether shredding-schema inference applies under {@code config}: enabled, write shredding
+   * enabled, no forced test DDL (force wins), and no internal schema (the Spark write support
+   * prefers the internal schema and would silently ignore an inferred one).
+   */
+  private static boolean isShreddingInferenceEnabled(HoodieConfig config) {
+    return config.getBooleanOrDefault(HoodieStorageConfig.PARQUET_VARIANT_SHREDDING_SCHEMA_INFERENCE_ENABLED)
+        && config.getBooleanOrDefault(HoodieStorageConfig.PARQUET_VARIANT_WRITE_SHREDDING_ENABLED)
+        && StringUtils.isNullOrEmpty(config.getString(HoodieStorageConfig.PARQUET_VARIANT_FORCE_SHREDDING_SCHEMA_FOR_TEST))
+        && StringUtils.isNullOrEmpty(config.getString(INTERNAL_SCHEMA_KEY));
+  }
+
+  /**
+   * Returns a copy of {@code config} with the inferred typed_value schemas spliced into its
+   * schema-carrying keys ({@code hoodie.write.schema}, {@code hoodie.avro.schema}), or
+   * {@code config} itself when there is nothing to splice. Used for write supports that resolve
+   * their schema from the config rather than a schema argument (the Spark row write support);
+   * the original config is never mutated.
+   */
+  public static HoodieConfig applyInferredShreddingToConfig(HoodieConfig config, Map<String, HoodieSchema> typedValueByField) {
+    if (typedValueByField.isEmpty()) {
+      return config;
+    }
+    HoodieConfig copy = new HoodieConfig(TypedProperties.copy(config.getProps()));
+    for (String key : new String[] {WRITE_SCHEMA_OVERRIDE_KEY, AVRO_SCHEMA_KEY}) {
+      String schemaString = copy.getString(key);
+      if (!StringUtils.isNullOrEmpty(schemaString)) {
+        HoodieSchema spliced = applyInferredShredding(HoodieSchema.parse(schemaString), typedValueByField);
+        copy.setValue(key, spliced.getAvroSchema().toString());
+      }
+    }
+    return copy;
+  }
+
+  /**
+   * Splices inferred typed_value schemas into the matching top-level variant fields of
+   * {@code schema}; the inverse direction of {@link #stripVariantShredding}. Only unshredded
+   * variant fields with an entry in {@code typedValueByField} are replaced; everything else
+   * passes through unchanged, and {@code schema} is returned as-is when nothing matches.
+   *
+   * @param schema            the writer schema
+   * @param typedValueByField column name to typed_value schema in the nested shredding-spec
+   *                          form, as produced by a {@link VariantShreddingSchemaInferrer}
+   */
+  public static HoodieSchema applyInferredShredding(HoodieSchema schema, Map<String, HoodieSchema> typedValueByField) {
+    if (schema.getType() != HoodieSchemaType.RECORD || typedValueByField.isEmpty()) {
+      return schema;
+    }
+
+    List<HoodieSchemaField> newFields = new ArrayList<>();
+    boolean changed = false;
+
+    for (HoodieSchemaField field : schema.getFields()) {
+      HoodieSchema fieldSchema = field.schema();
+      boolean wasNullable = fieldSchema.isNullable();
+      HoodieSchema unwrapped = wasNullable ? fieldSchema.getNonNullType() : fieldSchema;
+      HoodieSchema typedValue = typedValueByField.get(field.name());
+
+      if (typedValue != null
+          && unwrapped.getType() == HoodieSchemaType.VARIANT
+          && !((HoodieSchema.Variant) unwrapped).isShredded()) {
+        // typed_value must be nullable: rows whose variant value does not match the inferred
+        // schema are written with a null typed_value and the full binary in the value column.
+        HoodieSchema nullableTypedValue = typedValue.isNullable() ? typedValue : HoodieSchema.createNullable(typedValue);
+        // The shredded record needs a name unique to this column: variant columns commonly share
+        // one record type (named "variant"), which Avro serializes as name references after the
+        // first occurrence. Reusing the shared name would alias every other variant column to
+        // this column's shredded definition once the schema is serialized (the config-splice
+        // path), and two inferred columns could not coexist in one schema. The Hudi-owned
+        // namespace keeps the generated name clear of any user-declared type as well.
+        HoodieSchema.Variant shredded = HoodieSchema.createVariantShredded(
+            field.name() + "_variant",
+            INFERRED_VARIANT_NAMESPACE,
+            unwrapped.getAvroSchema().getDoc(),
+            nullableTypedValue);
+        HoodieSchema replacement = wasNullable ? HoodieSchema.createNullable(shredded) : shredded;
+        // createNewSchemaField: the existing avro fields are attached to the source schema and
+        // cannot be reused in a new record ("Field already used").
+        newFields.add(HoodieSchemaUtils.createNewSchemaField(field.withSchema(replacement)));
+        changed = true;
+      } else {
+        newFields.add(HoodieSchemaUtils.createNewSchemaField(field));
+      }
+    }
+
+    if (!changed) {
+      return schema;
+    }
+
+    return HoodieSchema.createRecord(
+        schema.getAvroSchema().getName(),
+        schema.getAvroSchema().getNamespace(),
+        schema.getAvroSchema().getDoc(),
+        newFields);
+  }
+
   /**
    * Whether this column sits shredded on disk and must be read in that shape and reconstructed to
    * serve the requested schema. A file schema that kept its variant logical type answers via
diff --git a/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantShreddingProvider.java b/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantShreddingProvider.java
index fafd3e8ab87b..c77c62ed92e0 100644
--- a/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantShreddingProvider.java
+++ b/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantShreddingProvider.java
@@ -37,29 +37,6 @@ import org.apache.avro.generic.GenericRecord;
  */
 public interface VariantShreddingProvider {
 
-  /**
-   * Provider implementations to auto-detect on the classpath, in priority order, when the variant
-   * shredding provider class is not set explicitly via config. Sole provider today: variant
-   * shredding currently requires Spark 4.0+.
-   */
-  String[] CLASSPATH_CANDIDATES = {"org.apache.hudi.variant.Spark4VariantShreddingProvider"};
-
-  /**
-   * Returns the fully-qualified class name of the first {@link VariantShreddingProvider}
-   * implementation available on the classpath, or {@code null} if none is present.
-   */
-  static String detectProviderClassOnClasspath() {
-    for (String candidate : CLASSPATH_CANDIDATES) {
-      try {
-        Class.forName(candidate);
-        return candidate;
-      } catch (ClassNotFoundException | NoClassDefFoundError e) {
-        // Provider not on classpath; try the next candidate.
-      }
-    }
-    return null;
-  }
-
   /**
    * Transform an unshredded variant GenericRecord into a shredded one.
    * <p>
diff --git a/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantShreddingRuntime.java b/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantShreddingRuntime.java
new file mode 100644
index 000000000000..b07154a4c069
--- /dev/null
+++ b/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantShreddingRuntime.java
@@ -0,0 +1,119 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.hudi.common.avro;
+
+import org.apache.hudi.common.util.Option;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Classpath detection of engine-specific variant shredding components.
+ *
+ * <p>Engine modules (currently the Spark 4.x bundles) ship implementations of
+ * {@link VariantShreddingProvider} and {@link VariantShreddingSchemaInferrer}; hudi-common
+ * discovers them by probing well-known class names so that it stays free of engine
+ * dependencies. Probes are memoized: classpath content does not change within a JVM.</p>
+ */
+@Slf4j
+public final class VariantShreddingRuntime {
+
+  /** Provider candidates, most specific first. Mirrors what each Spark bundle ships. */
+  private static final String[] PROVIDER_CANDIDATES = {
+      "org.apache.hudi.variant.Spark4VariantShreddingProvider"
+  };
+
+  /**
+   * Inferrer candidates, one per Spark version module that ships one (inference exists only in
+   * Spark 4.1+, SPARK-53659), most recent first. Each spark4.x profile builds only its own
+   * version module, so every version that should infer needs its own entry here: a runtime whose
+   * module is missing from this list silently writes unshredded.
+   */
+  private static final String[] INFERRER_CANDIDATES = {
+      "org.apache.hudi.variant.Spark42VariantShreddingSchemaInferrer",
+      "org.apache.hudi.variant.Spark41VariantShreddingSchemaInferrer"
+  };
+
+  private static final Option<String> PROVIDER_CLASS = probe(PROVIDER_CANDIDATES);
+  private static final Option<VariantShreddingSchemaInferrer> INFERRER = loadInferrer();
+
+  private VariantShreddingRuntime() {
+  }
+
+  /**
+   * The fully-qualified name of the first {@link VariantShreddingProvider} implementation
+   * found on the classpath, if any.
+   */
+  public static Option<String> getProviderClass() {
+    return PROVIDER_CLASS;
+  }
+
+  /**
+   * A shared {@link VariantShreddingSchemaInferrer} instance from the classpath, if any.
+   * Implementations are stateless and thread-safe by contract, so one instance is shared.
+   * Tests also use this as the capability probe to filter inference tests to classpaths
+   * that ship an inferrer.
+   */
+  public static Option<VariantShreddingSchemaInferrer> lookupInferrer() {
+    return INFERRER;
+  }
+
+  /**
+   * Both probes run from this class's static initializer, so nothing here may let an error
+   * escape: an escaping {@link LinkageError} would fail {@code <clinit>} and every later use
+   * (including {@link #getProviderClass()} on the main Avro write path) would see a bare
+   * "Could not initialize class" with the original cause lost. This probe therefore loads its
+   * candidates WITHOUT initialization (no static initializer of theirs runs here), and every
+   * {@link LinkageError} degrades to "absent". {@link #loadInferrer()} does initialize the
+   * candidate it picks, since it instantiates it, but every failure there - including the
+   * {@link ExceptionInInitializerError} a candidate's static initializer can raise, itself a
+   * {@link LinkageError} - is caught and latched to absent the same way.
+   */
+  private static Option<String> probe(String[] candidates) {
+    for (String candidate : candidates) {
+      try {
+        Class.forName(candidate, false, VariantShreddingRuntime.class.getClassLoader());
+        return Option.of(candidate);
+      } catch (ClassNotFoundException | NoClassDefFoundError e) {
+        // Not on the classpath (or its engine dependencies are absent); try the next candidate.
+      } catch (LinkageError e) {
+        // Present but unloadable (e.g. class version mismatch): treat as absent rather than fail.
+        log.warn("Variant shredding provider {} found on the classpath but failed to load; "
+            + "treating it as absent.", candidate, e);
+      }
+    }
+    return Option.empty();
+  }
+
+  private static Option<VariantShreddingSchemaInferrer> loadInferrer() {
+    for (String candidate : INFERRER_CANDIDATES) {
+      try {
+        Class<?> clazz = Class.forName(candidate, false, VariantShreddingRuntime.class.getClassLoader());
+        return Option.of((VariantShreddingSchemaInferrer) clazz.getDeclaredConstructor().newInstance());
+      } catch (ClassNotFoundException | NoClassDefFoundError e) {
+        // Not on the classpath (or its engine dependencies are absent); try the next candidate.
+      } catch (Exception | LinkageError e) {
+        // Present but unusable (e.g. linkage failure against an older Spark): degrade to absent.
+        log.warn("Variant shredding schema inferrer {} found on the classpath but failed to load; "
+            + "shredding schema inference is disabled.", candidate, e);
+      }
+    }
+    return Option.empty();
+  }
+}
diff --git a/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantShreddingSchemaInferrer.java b/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantShreddingSchemaInferrer.java
new file mode 100644
index 000000000000..915e57968d71
--- /dev/null
+++ b/hudi-common/src/main/java/org/apache/hudi/common/avro/VariantShreddingSchemaInferrer.java
@@ -0,0 +1,78 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.hudi.common.avro;
+
+import org.apache.hudi.common.schema.HoodieSchema;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Infers per-file variant shredding schemas (typed_value) from sampled variant binaries.
+ *
+ * <p>Implementations wrap an engine's inference machinery (e.g. Spark 4.1's
+ * {@code InferVariantShreddingSchema}) and are loaded via classpath detection, keeping
+ * hudi-common free of engine-specific dependencies. Implementations must be stateless,
+ * thread-safe and expose a public no-arg constructor.</p>
+ *
+ * <p>See https://github.com/apache/hudi/issues/18937.</p>
+ */
+public interface VariantShreddingSchemaInferrer {
+
+  /**
+   * Infers a typed_value schema for each variant column from row-aligned binary samples.
+   *
+   * <p>All variant columns of a file must be passed in ONE call: inference heuristics may
+   * apply a global budget (e.g. Spark caps the total shredded field count per file) and
+   * per-column calls would skew it.</p>
+   *
+   * @param columnNames top-level variant column names, in a fixed order
+   * @param rowSamples  one entry per sampled record; {@code rowSamples.get(i)[j]} holds the
+   *                    binaries of column {@code columnNames.get(j)} in record {@code i}, or
+   *                    null when that variant value is null
+   * @return column name to typed_value HoodieSchema in the nested shredding-spec form
+   *         (object fields wrapped as {@code {value, typed_value}}); a column absent from the
+   *         map declined inference and stays unshredded. May throw on malformed variant
+   *         binaries; callers must treat any throw as "decline all".
+   */
+  Map<String, HoodieSchema> inferTypedValueSchemas(List<String> columnNames, List<VariantSample[]> rowSamples);
+
+  /**
+   * The raw binary pair of a single variant value. Both arrays are always non-null; a null
+   * variant is represented by a null {@code VariantSample} slot instead.
+   */
+  final class VariantSample {
+    private final byte[] value;
+    private final byte[] metadata;
+
+    public VariantSample(byte[] value, byte[] metadata) {
+      this.value = value;
+      this.metadata = metadata;
+    }
+
+    public byte[] getValue() {
+      return value;
+    }
+
+    public byte[] getMetadata() {
+      return metadata;
+    }
+  }
+}
diff --git a/hudi-common/src/main/java/org/apache/hudi/common/config/HoodieStorageConfig.java b/hudi-common/src/main/java/org/apache/hudi/common/config/HoodieStorageConfig.java
index 60e062da2c4d..871cccd86d03 100644
--- a/hudi-common/src/main/java/org/apache/hudi/common/config/HoodieStorageConfig.java
+++ b/hudi-common/src/main/java/org/apache/hudi/common/config/HoodieStorageConfig.java
@@ -298,6 +298,25 @@ public class HoodieStorageConfig extends HoodieConfig {
           + "The provider parses variant binary data and populates typed_value columns. "
           + "When not set, the provider is auto-detected from the classpath.");
 
+  public static final ConfigProperty<Boolean> PARQUET_VARIANT_SHREDDING_SCHEMA_INFERENCE_ENABLED = ConfigProperty
+      .key("hoodie.parquet.variant.shredding.schema.inference.enabled")
+      .defaultValue(false)
+      .sinceVersion("1.3.0")
+      .withDocumentation("When enabled, the shredding schema for variant columns without an explicit "
+          + "typed_value in the write schema is inferred automatically per parquet file from a sample of "
+          + "the records written to that file, mirroring Spark 4.1's "
+          + "spark.sql.variant.inferShreddingSchema. Requires Spark 4.1+ on the writer classpath; "
+          + "writes stay unshredded otherwise (Spark 4.0, Flink, Java engines). Applies to every "
+          + "parquet file the writer produces: base files and, on table version 10+, the native "
+          + "parquet log files of MOR tables (each infers its own schema). Data blocks inside "
+          + "Avro-format log files, whether Avro or parquet (hoodie.logfile.data.block.format), stay "
+          + "unshredded and shred at compaction. Up to 4096 records or 64MB are buffered per "
+          + "open file writer before the writer is created, on top of parquet's own row-group "
+          + "buffer, so size executor memory for concurrently open handles accordingly. Ignored when "
+          + "hoodie.parquet.variant.force.shredding.schema.for.test is set, when write shredding "
+          + "is disabled, or when the table has a schema-on-read internal schema "
+          + "(hoodie.internal.schema).");
+
   public static final ConfigProperty<Boolean> WRITE_UTC_TIMEZONE = ConfigProperty
       .key("hoodie.parquet.write.utc-timezone.enabled")
       .defaultValue(true)
@@ -649,6 +668,11 @@ public class HoodieStorageConfig extends HoodieConfig {
       return this;
     }
 
+    public Builder parquetVariantShreddingSchemaInferenceEnabled(boolean enabled) {
+      storageConfig.setValue(PARQUET_VARIANT_SHREDDING_SCHEMA_INFERENCE_ENABLED, String.valueOf(enabled));
+      return this;
+    }
+
     public Builder hfileCompressionAlgorithm(String hfileCompressionAlgorithm) {
       storageConfig.setValue(HFILE_COMPRESSION_ALGORITHM_NAME, hfileCompressionAlgorithm);
       return this;
diff --git a/hudi-common/src/main/java/org/apache/hudi/common/schema/HoodieSchema.java b/hudi-common/src/main/java/org/apache/hudi/common/schema/HoodieSchema.java
index d8cd84e85f8a..c2ddd17d4221 100644
--- a/hudi-common/src/main/java/org/apache/hudi/common/schema/HoodieSchema.java
+++ b/hudi-common/src/main/java/org/apache/hudi/common/schema/HoodieSchema.java
@@ -2491,6 +2491,8 @@ public class HoodieSchema implements Serializable {
   public static class Variant extends HoodieSchema {
 
     private static final String VARIANT_DEFAULT_NAME = "variant";
+    /** Root namespace of the record types {@link #plainTypedValueOf} generates; Hudi-owned. */
+    private static final String PLAIN_TYPED_VALUE_NAMESPACE = "hoodie.variant.plain";
     public static final String VARIANT_METADATA_FIELD = "metadata";
     public static final String VARIANT_VALUE_FIELD = "value";
     public static final String VARIANT_TYPED_VALUE_FIELD = "typed_value";
@@ -2641,8 +2643,11 @@ public class HoodieSchema implements Serializable {
     /**
      * Returns the typed_value schema with plain (unwrapped) types suitable for Spark shredding utilities, i.e. essentially removing the `value` field
      *
-     * <p>If the typed_value follows the variant shredding spec (each field is a struct with
-     * {@code {value: bytes, typed_value: <type>}}), this extracts only the inner typed_value types and returns a record schema containing just those plain types.</p>
+     * <p>If the typed_value follows the variant shredding spec (each object field is a struct
+     * with {@code {value: bytes, typed_value: <type>}}), this extracts only the inner
+     * typed_value types, recursively unwrapping nested objects and arrays. A value-only wrapper
+     * ({@code {value}} with no typed_value, the spec form of a field that stays untyped) maps to
+     * an unshredded VARIANT member.</p>
      *
      * <p>If the typed_value is already in plain form (created with {@code createVariantShredded}),
      * returns the schema as-is.</p>
@@ -2653,47 +2658,108 @@ public class HoodieSchema implements Serializable {
       if (!typedValueSchema.isPresent()) {
         return Option.empty();
       }
-      HoodieSchema tvSchema = typedValueSchema.get();
-      if (tvSchema.getType() != HoodieSchemaType.RECORD) {
-        return typedValueSchema;
-      }
+      return Option.of(plainTypedValueOf(typedValueSchema.get(), PLAIN_TYPED_VALUE_NAMESPACE, VARIANT_TYPED_VALUE_FIELD));
+    }
 
-      List<HoodieSchemaField> fields = tvSchema.getFields();
-      // Check if all fields follow the nested shredding pattern: each field is a record with {value, typed_value}
-      boolean isNestedForm = !fields.isEmpty() && fields.stream().allMatch(field -> {
-        HoodieSchema fieldSchema = field.schema();
-        if (fieldSchema.isNullable()) {
-          fieldSchema = fieldSchema.getNonNullType();
+    /**
+     * Recursively converts a typed_value schema from the nested shredding-spec form to the
+     * plain form; schemas not in the spec form pass through unchanged (already plain).
+     *
+     * <p>Generated record names encode the field path: every nesting level of a spec-form
+     * schema is named {@code typed_value}, so reusing the source names (with a null namespace)
+     * would make a nested plain record an Avro self-reference of its ancestor, which Spark's
+     * schema converter rejects as recursion. The path goes into the NAMESPACE, one segment per
+     * level ({@code hoodie.variant.plain.typed_value.a.b_plain} for {@code typed_value.a.b}),
+     * so that paths which would concatenate to the same string ({@code a} under {@code b_c}
+     * versus {@code a_b} under {@code c}) still get distinct full names: '.' separates
+     * namespace segments and cannot occur inside an Avro name.</p>
+     *
+     * @param schema    the schema at this level
+     * @param namespace the namespace of the records generated at this level
+     * @param name      the name of this level (the field name, or {@code typed_value} at the root)
+     */
+    private static HoodieSchema plainTypedValueOf(HoodieSchema schema, String namespace, String name) {
+      HoodieSchema unwrapped = schema.isNullable() ? schema.getNonNullType() : schema;
+
+      if (unwrapped.getType() == HoodieSchemaType.RECORD) {
+        List<HoodieSchemaField> fields = unwrapped.getFields();
+        boolean isNestedForm = !fields.isEmpty() && fields.stream().allMatch(field -> {
+          HoodieSchema fieldSchema = field.schema();
+          if (fieldSchema.isNullable()) {
+            fieldSchema = fieldSchema.getNonNullType();
+          }
+          return isShreddedFieldWrapper(fieldSchema);
+        });
+        if (!isNestedForm) {
+          return schema;
         }
-        if (fieldSchema.getType() != HoodieSchemaType.RECORD) {
-          return false;
+
+        List<HoodieSchemaField> plainFields = new ArrayList<>();
+        for (HoodieSchemaField field : fields) {
+          HoodieSchema fieldSchema = field.schema();
+          if (fieldSchema.isNullable()) {
+            fieldSchema = fieldSchema.getNonNullType();
+          }
+          plainFields.add(HoodieSchemaField.of(field.name(),
+              unwrapFieldWrapper(fieldSchema, namespace + "." + name, field.name())));
         }
-        Option<HoodieSchemaField> valueSubField = fieldSchema.getField(VARIANT_VALUE_FIELD);
-        Option<HoodieSchemaField> typedValueSubField = fieldSchema.getField(VARIANT_TYPED_VALUE_FIELD);
-        return valueSubField.isPresent()
-            && valueSubField.get().schema().isNullable()
-            && valueSubField.get().schema().getNonNullType().getType() == HoodieSchemaType.BYTES
-            && typedValueSubField.isPresent()
-            && typedValueSubField.get().schema().isNullable()
-            && fieldSchema.getFields().size() == 2;
-      });
-
-      if (!isNestedForm) {
-        return typedValueSchema;
-      }
-
-      // Extract the plain types from the nested form
-      List<HoodieSchemaField> plainFields = new ArrayList<>();
-      for (HoodieSchemaField field : fields) {
-        HoodieSchema fieldSchema = field.schema();
-        if (fieldSchema.isNullable()) {
-          fieldSchema = fieldSchema.getNonNullType();
+        return HoodieSchema.createRecord(name + "_plain", namespace, null, plainFields);
+      }
+
+      if (unwrapped.getType() == HoodieSchemaType.ARRAY) {
+        HoodieSchema element = unwrapped.getElementType();
+        HoodieSchema elementUnwrapped = element.isNullable() ? element.getNonNullType() : element;
+        if (isShreddedFieldWrapper(elementUnwrapped)) {
+          return HoodieSchema.createArray(unwrapFieldWrapper(elementUnwrapped, namespace + "." + name, "element"));
         }
-        HoodieSchema innerTypedValue = fieldSchema.getField(VARIANT_TYPED_VALUE_FIELD).get().schema();
-        plainFields.add(HoodieSchemaField.of(field.name(), innerTypedValue));
+        return schema;
+      }
+
+      // Scalars and other types are already plain.
+      return schema;
+    }
+
+    /**
+     * Whether {@code schema} is a spec-form shredded-field wrapper: a record of exactly
+     * {@code {value: bytes}} or {@code {value: nullable bytes, typed_value: nullable type}}.
+     */
+    private static boolean isShreddedFieldWrapper(HoodieSchema schema) {
+      if (schema.getType() != HoodieSchemaType.RECORD) {
+        return false;
+      }
+      Option<HoodieSchemaField> valueSubField = schema.getField(VARIANT_VALUE_FIELD);
+      if (!valueSubField.isPresent()) {
+        return false;
+      }
+      HoodieSchema valueSchema = valueSubField.get().schema();
+      HoodieSchema valueType = valueSchema.isNullable() ? valueSchema.getNonNullType() : valueSchema;
+      if (valueType.getType() != HoodieSchemaType.BYTES) {
+        return false;
+      }
+      if (schema.getFields().size() == 1) {
+        // Value-only wrapper: the spec emits a required value for array elements and a
+        // nullable value for object fields.
+        return true;
+      }
+      Option<HoodieSchemaField> typedValueSubField = schema.getField(VARIANT_TYPED_VALUE_FIELD);
+      return schema.getFields().size() == 2
+          && valueSchema.isNullable()
+          && typedValueSubField.isPresent()
+          && typedValueSubField.get().schema().isNullable();
+    }
+
+    /**
+     * Extracts the plain type of a spec-form shredded-field wrapper: its inner typed_value,
+     * recursively unwrapped; or an unshredded VARIANT when the wrapper is value-only.
+     */
+    private static HoodieSchema unwrapFieldWrapper(HoodieSchema wrapper, String namespace, String name) {
+      Option<HoodieSchemaField> innerTypedValue = wrapper.getField(VARIANT_TYPED_VALUE_FIELD);
+      if (!innerTypedValue.isPresent()) {
+        // Value-only wrapper: the member stays untyped. Unique name per member to avoid
+        // same-name record clashes within one schema tree.
+        return HoodieSchema.createVariant(name + "_variant", namespace, null);
       }
-      return Option.of(HoodieSchema.createRecord(
-          tvSchema.getAvroSchema().getName() + "_plain", null, null, plainFields));
+      return plainTypedValueOf(innerTypedValue.get().schema(), namespace, name);
     }
 
     @Override
diff --git a/hudi-common/src/main/java/org/apache/hudi/common/table/TableSchemaResolver.java b/hudi-common/src/main/java/org/apache/hudi/common/table/TableSchemaResolver.java
index 08c45e2be4e8..eff6f6a7130e 100644
--- a/hudi-common/src/main/java/org/apache/hudi/common/table/TableSchemaResolver.java
+++ b/hudi-common/src/main/java/org/apache/hudi/common/table/TableSchemaResolver.java
@@ -18,6 +18,7 @@
 
 package org.apache.hudi.common.table;
 
+import org.apache.hudi.common.avro.VariantSchemaUtils;
 import org.apache.hudi.common.fs.FSUtils;
 import org.apache.hudi.common.fs.FileNameParser;
 import org.apache.hudi.common.model.HoodieCommitMetadata;
@@ -115,7 +116,13 @@ public class TableSchemaResolver {
   }
 
   private Option<HoodieSchema> getTableSchemaFromDataFileInternal() {
-    return getTableParquetSchemaFromDataFile();
+    // typed_value is a per-file physical layout (possibly inferred per file) and is stripped
+    // from the resolved table schema. Footer-derived schemas lose the variant logical type, so
+    // variant columns are also stripped by shape; that fallback walks top-level fields only, so
+    // a nested variant the row writer shredded at depth can still surface here.
+    return getTableParquetSchemaFromDataFile()
+        .map(VariantSchemaUtils::stripVariantShredding)
+        .map(VariantSchemaUtils::stripVariantShreddingByShape);
   }
 
   /**
diff --git a/hudi-common/src/main/java/org/apache/hudi/core/io/storage/VariantShreddingInferenceFileWriter.java b/hudi-common/src/main/java/org/apache/hudi/core/io/storage/VariantShreddingInferenceFileWriter.java
new file mode 100644
index 000000000000..bd236b839449
--- /dev/null
+++ b/hudi-common/src/main/java/org/apache/hudi/core/io/storage/VariantShreddingInferenceFileWriter.java
@@ -0,0 +1,332 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.hudi.core.io.storage;
+
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer;
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer.VariantSample;
+import org.apache.hudi.common.model.HoodieKey;
+import org.apache.hudi.common.model.HoodieRecord;
+import org.apache.hudi.common.schema.HoodieSchema;
+import org.apache.hudi.common.util.CloseableUtils;
+import org.apache.hudi.common.util.DefaultSizeEstimator;
+import org.apache.hudi.common.util.SizeEstimator;
+import org.apache.hudi.exception.HoodieIOException;
+
+import lombok.extern.slf4j.Slf4j;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Properties;
+
+/**
+ * A {@link HoodieFileWriter} decorator that infers a per-file variant shredding schema from the
+ * first records before opening the real parquet writer.
+ *
+ * <p>Records are buffered (and their variant binaries sampled) until a threshold is reached or
+ * the writer closes, the sampled binaries are fed to a {@link VariantShreddingSchemaInferrer},
+ * the real writer is created against the schema with the inferred typed_value spliced in, and
+ * the buffer is replayed in arrival order. Replay reproduces each call exactly (write vs
+ * writeWithMetadata), so commit seqnos, bloom filters and min/max record keys come out
+ * identical to a non-buffered write. Buffering thresholds mirror Spark's
+ * {@code ParquetOutputWriterWithVariantShredding} (4096 rows / 64MB).
+ *
+ * <p>Buffered records are {@link HoodieRecord#copy() copied} because Spark iterators reuse row
+ * instances, then handed to {@link VariantSampleExtractor#prepare}, which serves two purposes:
+ * an extractor that has to materialize the record to sample it (the Avro one deserializes
+ * payload-backed records) returns the materialized form for buffering so the replay does not
+ * repeat that work, and (since copy() returns the caller's own wrapper for every record type
+ * today) both shipped extractors return a wrapper the caller does not hold, so a handle that
+ * deflates its record right after the write call cannot blank a buffered one. Records with
+ * nothing to materialize (delete payloads) are buffered as they are, so replay still relies on
+ * writer-level records being freshly allocated per record, which holds today; variant samples
+ * are extracted eagerly into immutable byte arrays so inference itself never depends on it.
+ *
+ * <p>Inference failures never fail the write: the file falls back to unshredded variants. This
+ * deliberately diverges from Spark (which propagates inference failures) because a throwing
+ * inference would fail compaction. Writer-creation or replay failures, however, are latched and
+ * rethrown from every subsequent call including {@link #close()}, so a task cannot silently
+ * drop buffered records that the handle already counted as written.
+ *
+ * <p>{@link #writeRow} carries neither a {@link HoodieRecord} nor a schema to sample from, so the
+ * first such call materializes the real writer with whatever has been sampled so far (unshredded
+ * when nothing has) and passes the row straight through. Footer metadata added before
+ * materialization is queued and handed to the real writer once it exists; parquet only consumes
+ * it at close, so nothing is lost.
+ *
+ * <p>Single-threaded by contract, same as the writers it wraps.
+ *
+ * <p>See https://github.com/apache/hudi/issues/18937.</p>
+ *
+ * @param <T> the engine-native record type of the wrapped writer
+ */
+@Slf4j
+public class VariantShreddingInferenceFileWriter<T> implements HoodieFileWriter<T> {
+
+  /** Buffer caps mirroring Spark's ParquetOutputWriterWithVariantShredding. */
+  public static final int MAX_BUFFERED_RECORDS = 4096;
+  public static final long MAX_BUFFERED_BYTES = 64L * 1024 * 1024;
+  private static final int SIZE_ESTIMATE_INTERVAL = 100;
+
+  /**
+   * Extracts the variant binaries of the inferable columns from a record. Bound to the writer
+   * schema and column set by the creating factory; must defensively copy the bytes.
+   */
+  @FunctionalInterface
+  public interface VariantSampleExtractor {
+    VariantSample[] extract(HoodieRecord record, HoodieSchema schema, Properties props) throws IOException;
+
+    /**
+     * Returns the record to buffer for replay; {@link #extract} is then called with that record.
+     * An extractor that must materialize the record to sample it returns the materialized form,
+     * so the replay does not redo the work. Defaults to the record itself.
+     */
+    default HoodieRecord prepare(HoodieRecord record, HoodieSchema schema, Properties props) throws IOException {
+      return record;
+    }
+
+    /**
+     * Bytes of state that every buffered record references but that is shared across them, so a
+     * deep object-size walk of one record counts it in full: the Avro {@code Schema} graph of an
+     * Avro record, the {@code StructType} of a Spark row. Subtracted from each record's size
+     * estimate so the byte cap budgets record payload rather than the schema times the record
+     * count (the HUDI-9499 class of over-estimate, which would shrink the inference sample to a
+     * fraction of the intended 4096 rows). Defaults to 0.
+     */
+    default long sharedSizeEstimate(HoodieSchema schema) {
+      return 0;
+    }
+  }
+
+  /** Creates the real file writer once the inferred typed_value schemas are known. */
+  @FunctionalInterface
+  public interface InferredWriterFactory<T> {
+    HoodieFileWriter<T> create(Map<String, HoodieSchema> inferredTypedValues) throws IOException;
+  }
+
+  private final List<String> variantColumns;
+  private final VariantSampleExtractor extractor;
+  private final VariantShreddingSchemaInferrer inferrer;
+  private final InferredWriterFactory<T> writerFactory;
+  private final long maxBufferedBytes;
+  private final SizeEstimator<HoodieRecord> sizeEstimator = new DefaultSizeEstimator<>();
+
+  private final List<BufferedWrite> buffer = new ArrayList<>();
+  private final List<VariantSample[]> samples = new ArrayList<>();
+  private final Map<String, String> pendingFooterMetadata = new LinkedHashMap<>();
+  private long estimatedRecordSize = 0;
+  private long bufferedBytes = 0;
+  private HoodieFileWriter<T> delegate;
+  private IOException fatalFailure;
+  private boolean closed = false;
+
+  public VariantShreddingInferenceFileWriter(List<String> variantColumns,
+                                             VariantSampleExtractor extractor,
+                                             VariantShreddingSchemaInferrer inferrer,
+                                             InferredWriterFactory<T> writerFactory,
+                                             long maxFileSize) {
+    this.variantColumns = variantColumns;
+    this.extractor = extractor;
+    this.inferrer = inferrer;
+    this.writerFactory = writerFactory;
+    this.maxBufferedBytes = Math.min(MAX_BUFFERED_BYTES, Math.max(1, maxFileSize));
+  }
+
+  @Override
+  public boolean canWrite() {
+    // Nothing has been physically written while buffering, so size-based rollover cannot apply yet.
+    return delegate == null || delegate.canWrite();
+  }
+
+  @Override
+  public void writeWithMetadata(HoodieKey key, HoodieRecord record, HoodieSchema schema, Properties props) throws IOException {
+    rethrowIfFailed();
+    if (delegate != null) {
+      delegate.writeWithMetadata(key, record, schema, props);
+    } else {
+      buffer(true, key, null, record, schema, props);
+    }
+  }
+
+  @Override
+  public void write(String recordKey, HoodieRecord record, HoodieSchema schema, Properties props) throws IOException {
+    rethrowIfFailed();
+    if (delegate != null) {
+      delegate.write(recordKey, record, schema, props);
+    } else {
+      buffer(false, null, recordKey, record, schema, props);
+    }
+  }
+
+  @Override
+  public void writeRow(String recordKey, T record) throws IOException {
+    rethrowIfFailed();
+    // No HoodieRecord or schema to sample from: materialize with what has been sampled so far and
+    // pass the row through. No production caller reaches this today: the two factories that build
+    // this decorator (HoodieAvroFileWriterFactory and HoodieSparkFileWriterFactory) only wrap a
+    // writer whose schema has a top-level variant, and the writeRow callers that go through them
+    // (the native log-format delete writer and the CDC writer) pass schemas without one.
+    materialize();
+    delegate.writeRow(recordKey, record);
+  }
+
+  @Override
+  public void addFooterMetadata(Map<String, String> footerMetadata) {
+    if (delegate != null) {
+      delegate.addFooterMetadata(footerMetadata);
+    } else {
+      // Footer metadata is only consumed at close, so it can wait for the real writer.
+      pendingFooterMetadata.putAll(footerMetadata);
+    }
+  }
+
+  @Override
+  public void close() throws IOException {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    boolean delegateClosed = false;
+    try {
+      rethrowIfFailed();
+      // Materialize even with an empty buffer: handles expect the file to exist at close.
+      materialize();
+      // Mark before close() so a throwing delegate.close() surfaces, not retried in the catch.
+      delegateClosed = true;
+      delegate.close();
+    } catch (IOException | RuntimeException | Error e) {
+      // Error included: materialize() rethrows the Error it latches, and the delegate it
+      // created must still be closed.
+      if (delegate != null && !delegateClosed) {
+        CloseableUtils.closeSuppressing(delegate, e);
+      }
+      throw e;
+    }
+  }
+
+  @Override
+  public Object getFileFormatMetadata() {
+    try {
+      rethrowIfFailed();
+      materialize();
+    } catch (IOException e) {
+      throw new HoodieIOException("Failed to materialize the parquet writer for format metadata", e);
+    }
+    return delegate.getFileFormatMetadata();
+  }
+
+  private void buffer(boolean withMetadata, HoodieKey key, String recordKey, HoodieRecord record,
+                      HoodieSchema schema, Properties props) throws IOException {
+    rethrowIfFailed();
+    HoodieRecord buffered = extractor.prepare(record.copy(), schema, props);
+    // Eager extraction: immutable byte copies decouple inference from buffered-record identity,
+    // and per-record extraction failures (corrupt binaries) surface exactly like an eager write.
+    samples.add(extractor.extract(buffered, schema, props));
+    buffer.add(new BufferedWrite(withMetadata, key, recordKey, buffered, schema, props));
+    // Re-estimate periodically so a small first record cannot defeat the byte cap
+    // (same moving-average idiom as ExternalSpillableMap).
+    if (estimatedRecordSize == 0 || buffer.size() % SIZE_ESTIMATE_INTERVAL == 0) {
+      long sampled = Math.max(1, sizeEstimator.sizeEstimate(buffered) - extractor.sharedSizeEstimate(schema));
+      estimatedRecordSize = estimatedRecordSize == 0
+          ? sampled : (long) (estimatedRecordSize * 0.9 + sampled * 0.1);
+      // Rescale what is already buffered: leaving the earlier records charged at the old estimate
+      // would trip the cap late once the estimate grew (this record is charged just below).
+      bufferedBytes = (buffer.size() - 1) * estimatedRecordSize;
+    }
+    bufferedBytes += estimatedRecordSize;
+    if (buffer.size() >= MAX_BUFFERED_RECORDS || bufferedBytes >= maxBufferedBytes) {
+      materialize();
+    }
+  }
+
+  private void materialize() throws IOException {
+    if (delegate != null) {
+      return;
+    }
+    try {
+      delegate = writerFactory.create(inferTypedValues());
+      if (!pendingFooterMetadata.isEmpty()) {
+        delegate.addFooterMetadata(pendingFooterMetadata);
+        pendingFooterMetadata.clear();
+      }
+      for (BufferedWrite write : buffer) {
+        if (write.withMetadata) {
+          delegate.writeWithMetadata(write.key, write.record, write.schema, write.props);
+        } else {
+          delegate.write(write.recordKey, write.record, write.schema, write.props);
+        }
+      }
+      buffer.clear();
+      samples.clear();
+    } catch (IOException e) {
+      fatalFailure = e;
+      throw e;
+    } catch (RuntimeException | Error e) {
+      // Error latches too: inferTypedValues() already treats a LinkageError as reachable, and an
+      // unlatched failure would let close() finish the file without the un-replayed records.
+      fatalFailure = new IOException("Deferred parquet writer materialization failed", e);
+      throw e;
+    }
+  }
+
+  private Map<String, HoodieSchema> inferTypedValues() {
+    if (samples.isEmpty()) {
+      return Collections.emptyMap();
+    }
+    try {
+      Map<String, HoodieSchema> inferred = inferrer.inferTypedValueSchemas(variantColumns, samples);
+      return inferred == null ? Collections.emptyMap() : inferred;
+    } catch (Exception | LinkageError e) {
+      // LinkageError too: an inferrer linked against another Spark than the runtime's must
+      // degrade to unshredded like any other inference failure, not fail the write.
+      log.warn("Variant shredding schema inference failed for columns {}; writing unshredded variants.",
+          variantColumns, e);
+      return Collections.emptyMap();
+    }
+  }
+
+  private void rethrowIfFailed() throws IOException {
+    if (fatalFailure != null) {
+      throw fatalFailure;
+    }
+  }
+
+  private static final class BufferedWrite {
+    private final boolean withMetadata;
+    private final HoodieKey key;
+    private final String recordKey;
+    private final HoodieRecord record;
+    private final HoodieSchema schema;
+    private final Properties props;
+
+    BufferedWrite(boolean withMetadata, HoodieKey key, String recordKey, HoodieRecord record,
+                  HoodieSchema schema, Properties props) {
+      this.withMetadata = withMetadata;
+      this.key = key;
+      this.recordKey = recordKey;
+      this.record = record;
+      this.schema = schema;
+      this.props = props;
+    }
+  }
+}
diff --git a/hudi-common/src/test/java/org/apache/hudi/common/avro/TestAvroVariantSampleExtractor.java b/hudi-common/src/test/java/org/apache/hudi/common/avro/TestAvroVariantSampleExtractor.java
new file mode 100644
index 000000000000..ec3df9db3b16
--- /dev/null
+++ b/hudi-common/src/test/java/org/apache/hudi/common/avro/TestAvroVariantSampleExtractor.java
@@ -0,0 +1,172 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.hudi.common.avro;
+
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer.VariantSample;
+import org.apache.hudi.common.model.HoodieAvroIndexedRecord;
+import org.apache.hudi.common.model.HoodieAvroPayload;
+import org.apache.hudi.common.model.HoodieAvroRecord;
+import org.apache.hudi.common.model.HoodieKey;
+import org.apache.hudi.common.model.HoodieRecord;
+import org.apache.hudi.common.schema.HoodieSchema;
+import org.apache.hudi.common.schema.HoodieSchemaField;
+import org.apache.hudi.common.schema.HoodieSchemaType;
+import org.apache.hudi.common.util.ObjectSizeCalculator;
+import org.apache.hudi.common.util.Option;
+
+import org.apache.avro.generic.GenericData;
+import org.apache.avro.generic.GenericRecord;
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.nio.ByteBuffer;
+import java.util.Arrays;
+import java.util.Properties;
+
+import static java.util.Collections.singletonList;
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+public class TestAvroVariantSampleExtractor {
+
+  private static final HoodieSchema SCHEMA = HoodieSchema.createRecord("rec", "ns", null, Arrays.asList(
+      HoodieSchemaField.of("id", HoodieSchema.create(HoodieSchemaType.STRING)),
+      HoodieSchemaField.of("v", HoodieSchema.createNullable(HoodieSchema.createVariant()))));
+  private static final Properties PROPS = new Properties();
+  private static final HoodieKey KEY = new HoodieKey("r1", "p");
+
+  private static GenericRecord variant(Object value, Object metadata) {
+    HoodieSchema variantSchema = SCHEMA.getField("v").get().schema().getNonNullType();
+    GenericRecord record = new GenericData.Record(variantSchema.toAvroSchema());
+    record.put(HoodieSchema.Variant.VARIANT_VALUE_FIELD, value);
+    record.put(HoodieSchema.Variant.VARIANT_METADATA_FIELD, metadata);
+    return record;
+  }
+
+  private static GenericRecord row(GenericRecord variantValue) {
+    GenericRecord record = new GenericData.Record(SCHEMA.toAvroSchema());
+    record.put("id", "r1");
+    record.put("v", variantValue);
+    return record;
+  }
+
+  @Test
+  public void testExtractsDefensiveCopiesOfByteBufferAndByteArrayPayloads() throws IOException {
+    AvroVariantSampleExtractor extractor = new AvroVariantSampleExtractor(singletonList("v"));
+
+    // ByteBuffer payloads, the usual Avro representation of bytes.
+    byte[] valueBytes = {1, 2};
+    byte[] metadataBytes = {3};
+    VariantSample[] fromBuffers = extractor.extract(
+        new HoodieAvroIndexedRecord(KEY, row(variant(ByteBuffer.wrap(valueBytes), ByteBuffer.wrap(metadataBytes)))),
+        SCHEMA, PROPS);
+    assertEquals(1, fromBuffers.length);
+    assertArrayEquals(new byte[] {1, 2}, fromBuffers[0].getValue());
+    assertArrayEquals(new byte[] {3}, fromBuffers[0].getMetadata());
+    // Samples must not alias the record's backing arrays: they outlive the buffered record.
+    valueBytes[0] = 9;
+    metadataBytes[0] = 9;
+    assertArrayEquals(new byte[] {1, 2}, fromBuffers[0].getValue());
+    assertArrayEquals(new byte[] {3}, fromBuffers[0].getMetadata());
+
+    // Raw byte[] payloads are accepted too.
+    byte[] rawValue = {4};
+    byte[] rawMetadata = {5};
+    VariantSample[] fromArrays = extractor.extract(
+        new HoodieAvroIndexedRecord(KEY, row(variant(rawValue, rawMetadata))), SCHEMA, PROPS);
+    rawValue[0] = 9;
+    rawMetadata[0] = 9;
+    assertArrayEquals(new byte[] {4}, fromArrays[0].getValue());
+    assertArrayEquals(new byte[] {5}, fromArrays[0].getMetadata());
+  }
+
+  @Test
+  public void testAbsentColumnNullVariantAndMalformedVariantYieldNullSamples() throws IOException {
+    // "w" is not in the record's own schema (per-call schemas can differ from the writer schema);
+    // it is skipped rather than failing the write.
+    AvroVariantSampleExtractor extractor = new AvroVariantSampleExtractor(Arrays.asList("v", "w"));
+
+    VariantSample[] nullVariant = extractor.extract(new HoodieAvroIndexedRecord(KEY, row(null)), SCHEMA, PROPS);
+    assertEquals(2, nullVariant.length);
+    assertNull(nullVariant[0]);
+    assertNull(nullVariant[1]);
+
+    // A variant record with a null value payload contributes nothing either...
+    VariantSample[] nullValue = extractor.extract(
+        new HoodieAvroIndexedRecord(KEY, row(variant(null, ByteBuffer.wrap(new byte[] {1})))), SCHEMA, PROPS);
+    assertNull(nullValue[0]);
+
+    // ...nor does a variant-positioned record whose own schema lacks the value member, nor a
+    // non-record value in the variant position: malformed data declines sampling, never fails it.
+    GenericRecord metadataOnly = new GenericData.Record(HoodieSchema.createRecord("metadata_only", null, null,
+        singletonList(HoodieSchemaField.of("metadata", HoodieSchema.create(HoodieSchemaType.BYTES)))).toAvroSchema());
+    metadataOnly.put("metadata", ByteBuffer.wrap(new byte[] {1}));
+    assertNull(extractor.extract(new HoodieAvroIndexedRecord(KEY, row(metadataOnly)), SCHEMA, PROPS)[0]);
+    GenericRecord notARecord = new GenericData.Record(SCHEMA.toAvroSchema());
+    notARecord.put("id", "r1");
+    notARecord.put("v", "not a variant record");
+    assertNull(extractor.extract(new HoodieAvroIndexedRecord(KEY, notARecord), SCHEMA, PROPS)[0]);
+  }
+
+  @Test
+  public void testSharedSizeIsTheSchemaGraphMemoizedPerSchema() {
+    // The Avro Schema every materialized record references is charged once, not per record, and
+    // the memo is keyed on the schema instance: another schema measures its own graph, and the
+    // first schema measures as before once it is back.
+    AvroVariantSampleExtractor extractor = new AvroVariantSampleExtractor(singletonList("v"));
+    long shared = extractor.sharedSizeEstimate(SCHEMA);
+    assertEquals(ObjectSizeCalculator.getObjectSize(SCHEMA.toAvroSchema()), shared);
+    assertTrue(shared > 0);
+    HoodieSchema other = HoodieSchema.createRecord("other", null, null, Arrays.asList(
+        HoodieSchemaField.of("id", HoodieSchema.create(HoodieSchemaType.STRING)),
+        HoodieSchemaField.of("v", HoodieSchema.createVariant()),
+        HoodieSchemaField.of("extra", HoodieSchema.create(HoodieSchemaType.LONG))));
+    long otherShared = extractor.sharedSizeEstimate(other);
+    assertEquals(ObjectSizeCalculator.getObjectSize(other.toAvroSchema()), otherShared);
+    assertNotEquals(shared, otherShared);
+    assertEquals(shared, extractor.sharedSizeEstimate(SCHEMA));
+  }
+
+  @Test
+  public void testPrepareMaterializesPayloadOnceAndPassesIndexedRecordsThrough() throws IOException {
+    AvroVariantSampleExtractor extractor = new AvroVariantSampleExtractor(singletonList("v"));
+    GenericRecord data = row(variant(ByteBuffer.wrap(new byte[] {1}), ByteBuffer.wrap(new byte[] {2})));
+
+    // A payload-backed record is deserialized by prepare(); the result is what the decorator
+    // buffers and replays, so the writer's own toIndexedRecord at replay is a pass-through.
+    HoodieRecord payloadBacked = new HoodieAvroRecord<>(KEY, new HoodieAvroPayload(Option.of(data)));
+    HoodieRecord prepared = extractor.prepare(payloadBacked, SCHEMA, PROPS);
+    assertInstanceOf(HoodieAvroIndexedRecord.class, prepared);
+    assertSame(prepared, extractor.prepare(prepared, SCHEMA, PROPS), "already materialized: identity");
+    assertNotNull(extractor.extract(prepared, SCHEMA, PROPS)[0]);
+    assertArrayEquals(new byte[] {1}, extractor.extract(prepared, SCHEMA, PROPS)[0].getValue());
+
+    // A record without data (delete payload) has nothing to materialize: buffered as it is, no sample.
+    HoodieRecord delete = new HoodieAvroRecord<>(KEY, new HoodieAvroPayload(Option.empty()));
+    assertSame(delete, extractor.prepare(delete, SCHEMA, PROPS));
+    assertNull(extractor.extract(delete, SCHEMA, PROPS)[0]);
+  }
+}
diff --git a/hudi-common/src/test/java/org/apache/hudi/common/avro/TestVariantSchemaUtils.java b/hudi-common/src/test/java/org/apache/hudi/common/avro/TestVariantSchemaUtils.java
new file mode 100644
index 000000000000..8da150697ea3
--- /dev/null
+++ b/hudi-common/src/test/java/org/apache/hudi/common/avro/TestVariantSchemaUtils.java
@@ -0,0 +1,341 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.hudi.common.avro;
+
+import org.apache.hudi.common.config.HoodieConfig;
+import org.apache.hudi.common.config.HoodieStorageConfig;
+import org.apache.hudi.common.schema.HoodieSchema;
+import org.apache.hudi.common.schema.HoodieSchemaField;
+import org.apache.hudi.common.schema.HoodieSchemaTestUtils;
+import org.apache.hudi.common.schema.HoodieSchemaType;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+public class TestVariantSchemaUtils {
+
+  private static HoodieSchema schemaWithVariants() {
+    return HoodieSchema.createRecord("rec", "ns", null, Arrays.asList(
+        HoodieSchemaField.of("id", HoodieSchema.create(HoodieSchemaType.STRING)),
+        HoodieSchemaField.of("v1", HoodieSchema.createNullable(HoodieSchema.createVariant())),
+        HoodieSchemaField.of("v2", HoodieSchema.createVariant("v2_variant", null, null)),
+        HoodieSchemaField.of("shredded", HoodieSchema.createVariantShredded(
+            "pre_shredded", null, null, HoodieSchema.create(HoodieSchemaType.LONG)))));
+  }
+
+  private static HoodieConfig inferenceEnabledConfig() {
+    HoodieConfig config = new HoodieConfig();
+    config.setValue(HoodieStorageConfig.PARQUET_VARIANT_SHREDDING_SCHEMA_INFERENCE_ENABLED, "true");
+    return config;
+  }
+
+  @Test
+  public void testGetInferableVariantColumns() {
+    HoodieSchema schema = schemaWithVariants();
+    // Unshredded variants only; explicitly shredded columns keep schema-driven shredding.
+    assertEquals(Arrays.asList("v1", "v2"),
+        VariantSchemaUtils.getInferableVariantColumns(inferenceEnabledConfig(), schema));
+  }
+
+  @Test
+  public void testGetInferableVariantColumnsGating() {
+    HoodieSchema schema = schemaWithVariants();
+
+    // Inference disabled (default)
+    assertTrue(VariantSchemaUtils.getInferableVariantColumns(new HoodieConfig(), schema).isEmpty());
+
+    // Write shredding disabled
+    HoodieConfig shreddingOff = inferenceEnabledConfig();
+    shreddingOff.setValue(HoodieStorageConfig.PARQUET_VARIANT_WRITE_SHREDDING_ENABLED, "false");
+    assertTrue(VariantSchemaUtils.getInferableVariantColumns(shreddingOff, schema).isEmpty());
+
+    // Forced test DDL wins over inference
+    HoodieConfig forced = inferenceEnabledConfig();
+    forced.setValue(HoodieStorageConfig.PARQUET_VARIANT_FORCE_SHREDDING_SCHEMA_FOR_TEST, "a int");
+    assertTrue(VariantSchemaUtils.getInferableVariantColumns(forced, schema).isEmpty());
+
+    // Internal schema present: the Spark write support would ignore the splice
+    HoodieConfig internal = inferenceEnabledConfig();
+    internal.setValue("hoodie.internal.schema", "{}");
+    assertTrue(VariantSchemaUtils.getInferableVariantColumns(internal, schema).isEmpty());
+
+    // No variant columns
+    HoodieSchema noVariants = HoodieSchema.createRecord("rec", null, null,
+        Collections.singletonList(HoodieSchemaField.of("id", HoodieSchema.create(HoodieSchemaType.STRING))));
+    assertTrue(VariantSchemaUtils.getInferableVariantColumns(inferenceEnabledConfig(), noVariants).isEmpty());
+  }
+
+  @Test
+  public void testGetInferableVariantColumnsIsTopLevelOnly() {
+    // Inference never shreds a nested variant (struct member, array element, map value): the
+    // footer-fallback strip and the write supports' hooks share that top-level scope, so a
+    // recursive walk here would shred what nothing else accounts for.
+    HoodieSchema schema = HoodieSchema.createRecord("rec", "ns", null, Arrays.asList(
+        HoodieSchemaField.of("top", HoodieSchema.createVariant()),
+        HoodieSchemaField.of("s", HoodieSchema.createRecord("s_rec", "ns", null,
+            Collections.singletonList(HoodieSchemaField.of("v", HoodieSchema.createVariant("s_variant", null, null))))),
+        HoodieSchemaField.of("a", HoodieSchema.createArray(HoodieSchema.createVariant("a_variant", null, null))),
+        HoodieSchemaField.of("m", HoodieSchema.createMap(HoodieSchema.createVariant("m_variant", null, null)))));
+
+    assertEquals(Collections.singletonList("top"),
+        VariantSchemaUtils.getInferableVariantColumns(inferenceEnabledConfig(), schema));
+  }
+
+  @Test
+  public void testGetInferableVariantColumnsFromConfig() {
+    HoodieSchema schema = schemaWithVariants();
+    String schemaString = schema.getAvroSchema().toString();
+    // Only the id column: distinguishes the write-schema key from the avro-schema key below.
+    String noVariantString = HoodieSchema.createRecord("rec", null, null,
+        Collections.singletonList(HoodieSchemaField.of("id", HoodieSchema.create(HoodieSchemaType.STRING))))
+        .getAvroSchema().toString();
+
+    // hoodie.write.schema takes precedence over hoodie.avro.schema, as in the row write support.
+    HoodieConfig writeOverridesAvro = inferenceEnabledConfig();
+    writeOverridesAvro.setValue("hoodie.avro.schema", schemaString);
+    writeOverridesAvro.setValue("hoodie.write.schema", noVariantString);
+    assertTrue(VariantSchemaUtils.getInferableVariantColumnsFromConfig(writeOverridesAvro).isEmpty());
+
+    HoodieConfig avroOnly = inferenceEnabledConfig();
+    avroOnly.setValue("hoodie.avro.schema", schemaString);
+    assertEquals(Arrays.asList("v1", "v2"), VariantSchemaUtils.getInferableVariantColumnsFromConfig(avroOnly));
+
+    HoodieConfig writeOnly = inferenceEnabledConfig();
+    writeOnly.setValue("hoodie.write.schema", schemaString);
+    assertEquals(Arrays.asList("v1", "v2"), VariantSchemaUtils.getInferableVariantColumnsFromConfig(writeOnly));
+
+    // No schema in the config, or inference disabled: nothing, and no schema parse attempted.
+    assertTrue(VariantSchemaUtils.getInferableVariantColumnsFromConfig(inferenceEnabledConfig()).isEmpty());
+    HoodieConfig disabled = new HoodieConfig();
+    disabled.setValue("hoodie.avro.schema", "not a schema");
+    assertTrue(VariantSchemaUtils.getInferableVariantColumnsFromConfig(disabled).isEmpty());
+  }
+
+  @Test
+  public void testApplyInferredShredding() {
+    HoodieSchema schema = schemaWithVariants();
+    Map<String, HoodieSchema> inferred = new LinkedHashMap<>();
+    // Spec-form object typed_value for v1; v2 intentionally absent (declined).
+    Map<String, HoodieSchema> typedFields = new LinkedHashMap<>();
+    typedFields.put("a", HoodieSchema.create(HoodieSchemaType.INT));
+    inferred.put("v1", HoodieSchema.createVariantShreddedObject(typedFields).getTypedValueField().get());
+
+    HoodieSchema spliced = VariantSchemaUtils.applyInferredShredding(schema, inferred);
+    assertNotEquals(schema, spliced);
+
+    // v1: shredded, nullability preserved, typed_value nullable
+    HoodieSchema v1 = spliced.getField("v1").get().schema();
+    assertTrue(v1.isNullable());
+    HoodieSchema.Variant v1Variant = (HoodieSchema.Variant) v1.getNonNullType();
+    assertTrue(v1Variant.isShredded());
+    assertTrue(v1Variant.getTypedValueField().isPresent());
+    assertTrue(v1Variant.getTypedValueField().get().isNullable());
+
+    // v2: untouched (declined)
+    HoodieSchema v2 = spliced.getField("v2").get().schema();
+    assertFalse(((HoodieSchema.Variant) v2).isShredded());
+
+    // Splicing the non-nullable v2 keeps it non-nullable: a bare shredded variant, no union.
+    HoodieSchema v2Spliced = VariantSchemaUtils.applyInferredShredding(schema,
+        Collections.singletonMap("v2", HoodieSchema.create(HoodieSchemaType.STRING))).getField("v2").get().schema();
+    assertFalse(v2Spliced.isNullable());
+    assertTrue(((HoodieSchema.Variant) v2Spliced).isShredded());
+
+    // Pre-shredded column untouched
+    HoodieSchema.Variant preShredded = (HoodieSchema.Variant) spliced.getField("shredded").get().schema();
+    assertEquals(HoodieSchemaType.LONG,
+        preShredded.getTypedValueField().get().getType());
+
+    // Non-variant column untouched
+    assertEquals(HoodieSchemaType.STRING, spliced.getField("id").get().schema().getType());
+
+    // Strip is the inverse: stripping the spliced schema yields unshredded v1 again
+    HoodieSchema stripped = VariantSchemaUtils.stripVariantShredding(spliced);
+    assertFalse(((HoodieSchema.Variant) stripped.getField("v1").get().schema().getNonNullType()).isShredded());
+  }
+
+  @Test
+  public void testApplyInferredShreddingIdentityWhenNothingMatches() {
+    HoodieSchema schema = schemaWithVariants();
+    assertSame(schema, VariantSchemaUtils.applyInferredShredding(schema, Collections.emptyMap()));
+    // Map entry for a non-variant column does not match anything
+    assertSame(schema, VariantSchemaUtils.applyInferredShredding(schema,
+        Collections.singletonMap("id", HoodieSchema.create(HoodieSchemaType.LONG))));
+  }
+
+  @Test
+  public void testStripVariantShreddingByShape() {
+    // Footer-derived schemas lose the variant logical type: a shredded variant comes back as a
+    // plain record {metadata: bytes, value: nullable bytes, typed_value}.
+    HoodieSchema footerVariant = HoodieSchemaTestUtils.createPlainShreddedVariantRecord("v",
+        HoodieSchema.createRecord("tv", null, null,
+            Collections.singletonList(HoodieSchemaField.of("a", HoodieSchema.create(HoodieSchemaType.LONG)))));
+    HoodieSchema schema = HoodieSchema.createRecord("rec", null, null, Arrays.asList(
+        HoodieSchemaField.of("id", HoodieSchema.create(HoodieSchemaType.STRING)),
+        HoodieSchemaField.of("v", HoodieSchema.createNullable(footerVariant))));
+
+    HoodieSchema stripped = VariantSchemaUtils.stripVariantShreddingByShape(schema);
+    HoodieSchema v = stripped.getField("v").get().schema().getNonNullType();
+    assertEquals(2, v.getFields().size());
+    assertFalse(v.getField("typed_value").isPresent());
+    assertTrue(v.getField("metadata").isPresent());
+    assertTrue(v.getField("value").isPresent());
+    // Non-variant-shaped records pass through; identity when nothing matches.
+    assertEquals(HoodieSchemaType.STRING, stripped.getField("id").get().schema().getType());
+    assertSame(stripped, VariantSchemaUtils.stripVariantShreddingByShape(stripped));
+
+    // Documented limitation: the footer fallback has no table schema to anchor on, so unlike the
+    // read path's isShreddedVariantTarget / alignShreddedVariants (which keep a same-shaped user
+    // struct intact, see TestHoodieSchemaCompatibility) this strip cannot tell a shredded variant
+    // from a plain user struct of the same shape and strips both. Pinned so that adding an anchor
+    // later is a deliberate change.
+    HoodieSchema userStruct = HoodieSchemaTestUtils.createPlainShreddedVariantRecord("user_struct",
+        HoodieSchema.create(HoodieSchemaType.LONG));
+    HoodieSchema userStructStripped = VariantSchemaUtils.stripVariantShreddingByShape(HoodieSchema.createRecord(
+        "rec", null, null, Collections.singletonList(HoodieSchemaField.of("s", userStruct)))).getField("s").get().schema();
+    assertEquals(Arrays.asList("metadata", "value"),
+        userStructStripped.getFields().stream().map(HoodieSchemaField::name).collect(Collectors.toList()));
+  }
+
+  @Test
+  public void testStripVariantShreddingByShapeRestoresOmittedValue() {
+    // The spec lets a writer omit `value` when every row is typed; the stripped column must still
+    // come out in the unshredded {metadata, value} shape rather than as a one-field record.
+    HoodieSchema twoFieldVariant = HoodieSchema.createRecord("v", null, null, Arrays.asList(
+        HoodieSchemaField.of("metadata", HoodieSchema.create(HoodieSchemaType.BYTES)),
+        HoodieSchemaField.of("typed_value", HoodieSchema.createNullable(HoodieSchemaType.LONG))));
+    HoodieSchema schema = HoodieSchema.createRecord("rec", null, null,
+        Collections.singletonList(HoodieSchemaField.of("v", twoFieldVariant)));
+
+    HoodieSchema v = VariantSchemaUtils.stripVariantShreddingByShape(schema).getField("v").get().schema();
+    assertEquals(Arrays.asList("metadata", "value"),
+        v.getFields().stream().map(HoodieSchemaField::name).collect(Collectors.toList()));
+    assertTrue(v.getField("value").get().schema().isNullable());
+    assertEquals(HoodieSchemaType.BYTES, v.getField("value").get().schema().getNonNullType().getType());
+    // The synthesized field must carry a null default like every other footer-derived optional field.
+    assertEquals(HoodieSchema.NULL_VALUE, v.getField("value").get().defaultVal().get());
+  }
+
+  @Test
+  public void testApplyInferredShreddingToConfig() {
+    HoodieSchema schema = schemaWithVariants();
+    HoodieConfig config = new HoodieConfig();
+    config.setValue("hoodie.avro.schema", schema.getAvroSchema().toString());
+    String originalString = config.getString("hoodie.avro.schema");
+
+    Map<String, HoodieSchema> inferred = Collections.singletonMap("v2",
+        HoodieSchema.create(HoodieSchemaType.STRING));
+    HoodieConfig spliced = VariantSchemaUtils.applyInferredShreddingToConfig(config, inferred);
+
+    // The original config is never mutated.
+    assertEquals(originalString, config.getString("hoodie.avro.schema"));
+    HoodieSchema splicedSchema = HoodieSchema.parse(spliced.getString("hoodie.avro.schema"));
+    HoodieSchema.Variant v2 = (HoodieSchema.Variant) splicedSchema.getField("v2").get().schema();
+    assertTrue(v2.isShredded());
+
+    // Identity when there is nothing to splice.
+    assertSame(config, VariantSchemaUtils.applyInferredShreddingToConfig(config, Collections.emptyMap()));
+  }
+
+  @Test
+  public void testApplyInferredShreddingToConfigKeepsSameNamedVariantColumnsApart() {
+    // Variant columns commonly share one record type (the default name "variant"), which Avro
+    // serializes as a name reference after the first occurrence. Splicing one column's record
+    // under that shared name used to alias every other variant column to the shredded definition
+    // once the schema was re-parsed from the config (and two inferred columns could not coexist).
+    HoodieSchema schema = HoodieSchema.createRecord("rec", "ns", null, Arrays.asList(
+        HoodieSchemaField.of("id", HoodieSchema.create(HoodieSchemaType.STRING)),
+        HoodieSchemaField.of("a", HoodieSchema.createVariant()),
+        HoodieSchemaField.of("b", HoodieSchema.createVariant())));
+    HoodieConfig config = new HoodieConfig();
+    config.setValue("hoodie.avro.schema", schema.getAvroSchema().toString());
+
+    // One column inferred, the sibling declined: the sibling must come back unshredded.
+    HoodieSchema oneSpliced = HoodieSchema.parse(VariantSchemaUtils.applyInferredShreddingToConfig(config,
+        Collections.singletonMap("a", HoodieSchema.create(HoodieSchemaType.LONG))).getString("hoodie.avro.schema"));
+    assertTrue(((HoodieSchema.Variant) oneSpliced.getField("a").get().schema()).isShredded());
+    assertFalse(((HoodieSchema.Variant) oneSpliced.getField("b").get().schema()).isShredded());
+
+    // Both inferred with different typed_values: each column keeps its own.
+    Map<String, HoodieSchema> both = new LinkedHashMap<>();
+    both.put("a", HoodieSchema.create(HoodieSchemaType.LONG));
+    both.put("b", HoodieSchema.create(HoodieSchemaType.STRING));
+    HoodieSchema bothSpliced = HoodieSchema.parse(
+        VariantSchemaUtils.applyInferredShreddingToConfig(config, both).getString("hoodie.avro.schema"));
+    HoodieSchema.Variant a = (HoodieSchema.Variant) bothSpliced.getField("a").get().schema();
+    HoodieSchema.Variant b = (HoodieSchema.Variant) bothSpliced.getField("b").get().schema();
+    assertEquals(HoodieSchemaType.LONG, a.getTypedValueField().get().getNonNullType().getType());
+    assertEquals(HoodieSchemaType.STRING, b.getTypedValueField().get().getNonNullType().getType());
+    assertNotEquals(a.getFullName(), b.getFullName());
+  }
+
+  @Test
+  public void testApplyInferredShreddingToConfigSplicesEverySchemaKey() {
+    // The row write support resolves hoodie.write.schema first and falls back to
+    // hoodie.avro.schema, so whichever of the two is set (or both) must carry the splice.
+    HoodieSchema schema = schemaWithVariants();
+    Map<String, HoodieSchema> inferred = Collections.singletonMap("v2", HoodieSchema.create(HoodieSchemaType.STRING));
+
+    HoodieConfig bothKeys = new HoodieConfig();
+    bothKeys.setValue("hoodie.write.schema", schema.getAvroSchema().toString());
+    bothKeys.setValue("hoodie.avro.schema", schema.getAvroSchema().toString());
+    HoodieConfig bothSpliced = VariantSchemaUtils.applyInferredShreddingToConfig(bothKeys, inferred);
+    for (String key : Arrays.asList("hoodie.write.schema", "hoodie.avro.schema")) {
+      HoodieSchema.Variant v2 = (HoodieSchema.Variant) HoodieSchema.parse(bothSpliced.getString(key)).getField("v2").get().schema();
+      assertTrue(v2.isShredded(), key + " should carry the splice");
+    }
+
+    HoodieConfig writeOnly = new HoodieConfig();
+    writeOnly.setValue("hoodie.write.schema", schema.getAvroSchema().toString());
+    HoodieConfig writeSpliced = VariantSchemaUtils.applyInferredShreddingToConfig(writeOnly, inferred);
+    assertTrue(((HoodieSchema.Variant) HoodieSchema.parse(writeSpliced.getString("hoodie.write.schema"))
+        .getField("v2").get().schema()).isShredded());
+    // An absent key stays absent: the splice never invents a schema.
+    assertNull(writeSpliced.getString("hoodie.avro.schema"));
+
+    // Detection reads hoodie.write.schema first while the splice writes every key that is set:
+    // when the two keys carry different schemas, each key is spliced on its own columns, so a key
+    // without the inferred column is left exactly as it was.
+    HoodieSchema noV2 = HoodieSchema.createRecord("rec", "ns", null, Arrays.asList(
+        HoodieSchemaField.of("id", HoodieSchema.create(HoodieSchemaType.STRING)),
+        HoodieSchemaField.of("v1", HoodieSchema.createNullable(HoodieSchema.createVariant()))));
+    HoodieConfig differentKeys = new HoodieConfig();
+    differentKeys.setValue("hoodie.write.schema", schema.getAvroSchema().toString());
+    differentKeys.setValue("hoodie.avro.schema", noV2.getAvroSchema().toString());
+    HoodieConfig differentSpliced = VariantSchemaUtils.applyInferredShreddingToConfig(differentKeys, inferred);
+    assertTrue(((HoodieSchema.Variant) HoodieSchema.parse(differentSpliced.getString("hoodie.write.schema"))
+        .getField("v2").get().schema()).isShredded());
+    HoodieSchema avroSide = HoodieSchema.parse(differentSpliced.getString("hoodie.avro.schema"));
+    assertFalse(avroSide.getField("v2").isPresent());
+    assertFalse(((HoodieSchema.Variant) avroSide.getField("v1").get().schema().getNonNullType()).isShredded());
+  }
+}
diff --git a/hudi-common/src/test/java/org/apache/hudi/common/schema/HoodieSchemaTestUtils.java b/hudi-common/src/test/java/org/apache/hudi/common/schema/HoodieSchemaTestUtils.java
index 6052639d209e..f5fa382a70b8 100644
--- a/hudi-common/src/test/java/org/apache/hudi/common/schema/HoodieSchemaTestUtils.java
+++ b/hudi-common/src/test/java/org/apache/hudi/common/schema/HoodieSchemaTestUtils.java
@@ -96,4 +96,16 @@ public class HoodieSchemaTestUtils {
         HoodieSchemaField.of("metadata", HoodieSchema.create(HoodieSchemaType.BYTES), null, null),
         HoodieSchemaField.of("value", HoodieSchema.create(HoodieSchemaType.BYTES), null, null)));
   }
+
+  /**
+   * The shredded twin of {@link #createPlainVariantRecord}: the on-disk shredded variant layout
+   * {@code {metadata: bytes, value: nullable bytes, typed_value}} as a plain record without the
+   * variant logicalType, i.e. what converting a parquet footer of a shredded file gives back.
+   */
+  public static HoodieSchema createPlainShreddedVariantRecord(String recordName, HoodieSchema typedValue) {
+    return HoodieSchema.createRecord(recordName, null, null, false, Arrays.asList(
+        HoodieSchemaField.of("metadata", HoodieSchema.create(HoodieSchemaType.BYTES), null, null),
+        HoodieSchemaField.of("value", HoodieSchema.createNullable(HoodieSchemaType.BYTES), null, null),
+        HoodieSchemaField.of("typed_value", typedValue, null, null)));
+  }
 }
diff --git a/hudi-common/src/test/java/org/apache/hudi/common/schema/TestHoodieSchema.java b/hudi-common/src/test/java/org/apache/hudi/common/schema/TestHoodieSchema.java
index b622b67fc65d..90fdd609cc41 100644
--- a/hudi-common/src/test/java/org/apache/hudi/common/schema/TestHoodieSchema.java
+++ b/hudi-common/src/test/java/org/apache/hudi/common/schema/TestHoodieSchema.java
@@ -3087,4 +3087,127 @@ public class TestHoodieSchema {
     HoodieSchema.Variant unshreddedVariant = HoodieSchema.createVariant();
     assertFalse(unshreddedVariant.getPlainTypedValueSchema().isPresent());
   }
+
+  @Test
+  public void testGetPlainTypedValueSchemaNestedObjectRecursion() {
+    // Depth-2 spec form: typed_value { a: wrapper{value, typed_value: { b: wrapper{value, typed_value: long} }} }.
+    // Both record levels are named "typed_value", as the schema converters produce them.
+    HoodieSchema innerObject = HoodieSchema.createRecord("typed_value", "inner.ns", null,
+        Collections.singletonList(HoodieSchemaField.of("b",
+            HoodieSchema.createNullable(HoodieSchema.createShreddedFieldStruct("b_wrapper", HoodieSchema.create(HoodieSchemaType.LONG))))));
+    HoodieSchema topTypedValue = HoodieSchema.createRecord("typed_value", "outer.ns", null,
+        Collections.singletonList(HoodieSchemaField.of("a",
+            HoodieSchema.createNullable(HoodieSchema.createShreddedFieldStruct("a_wrapper", innerObject)))));
+    // Nullable typed_value, as produced by the inferred-shredding splice.
+    HoodieSchema.Variant variant = HoodieSchema.createVariantShredded(HoodieSchema.createNullable(topTypedValue));
+
+    Option<HoodieSchema> plainOpt = variant.getPlainTypedValueSchema();
+    assertTrue(plainOpt.isPresent());
+    HoodieSchema plain = plainOpt.get();
+    assertEquals(HoodieSchemaType.RECORD, plain.getType());
+    assertEquals(1, plain.getFields().size());
+
+    HoodieSchema aPlain = plain.getFields().get(0).schema();
+    aPlain = aPlain.isNullable() ? aPlain.getNonNullType() : aPlain;
+    assertEquals(HoodieSchemaType.RECORD, aPlain.getType());
+    assertEquals(1, aPlain.getFields().size());
+
+    HoodieSchema bPlain = aPlain.getFields().get(0).schema();
+    bPlain = bPlain.isNullable() ? bPlain.getNonNullType() : bPlain;
+    assertEquals(HoodieSchemaType.LONG, bPlain.getType());
+
+    // Generated plain record names must be unique per nesting level: a nested record carrying
+    // its ancestor's fullname is an Avro self-reference, which Spark rejects as recursion.
+    assertNotEquals(plain.getFullName(), aPlain.getFullName());
+  }
+
+  @Test
+  public void testGetPlainTypedValueSchemaNamesDistinguishConcatenatingPaths() {
+    // Two object paths whose segments concatenate to the same string ("x_y" > "z" and "x" > "y_z")
+    // must still yield distinct plain record names for the objects at their leaves; the path goes
+    // into the namespace, where the '.' separator keeps them apart (a flat "<path>_plain" name
+    // gave both leaves "typed_value_x_y_z_plain").
+    HoodieSchema leafObject = HoodieSchema.createRecord("typed_value", "leaf.ns", null,
+        Collections.singletonList(HoodieSchemaField.of("c",
+            HoodieSchema.createNullable(HoodieSchema.createShreddedFieldStruct("c_wrapper", HoodieSchema.create(HoodieSchemaType.LONG))))));
+    HoodieSchema underXy = HoodieSchema.createRecord("typed_value", "a.ns", null,
+        Collections.singletonList(HoodieSchemaField.of("z",
+            HoodieSchema.createNullable(HoodieSchema.createShreddedFieldStruct("z_wrapper", leafObject)))));
+    HoodieSchema underX = HoodieSchema.createRecord("typed_value", "b.ns", null,
+        Collections.singletonList(HoodieSchemaField.of("y_z",
+            HoodieSchema.createNullable(HoodieSchema.createShreddedFieldStruct("y_z_wrapper", leafObject)))));
+    HoodieSchema topTypedValue = HoodieSchema.createRecord("typed_value", "outer.ns", null, Arrays.asList(
+        HoodieSchemaField.of("x_y", HoodieSchema.createNullable(HoodieSchema.createShreddedFieldStruct("x_y_wrapper", underXy))),
+        HoodieSchemaField.of("x", HoodieSchema.createNullable(HoodieSchema.createShreddedFieldStruct("x_wrapper", underX)))));
+
+    HoodieSchema plain = HoodieSchema.createVariantShredded(topTypedValue).getPlainTypedValueSchema().get();
+    HoodieSchema zLeaf = nestedRecord(plain, "x_y", "z");
+    HoodieSchema yzLeaf = nestedRecord(plain, "x", "y_z");
+    assertEquals(HoodieSchemaType.RECORD, zLeaf.getType());
+    assertEquals(HoodieSchemaType.RECORD, yzLeaf.getType());
+    assertNotEquals(zLeaf.getFullName(), yzLeaf.getFullName());
+    // Serializing the whole tree (as the config-splice path does) must not alias the two leaves.
+    // Avro writes a repeated fullname as a reference to its first definition rather than
+    // throwing, so the check has to be on the re-parsed serialized form.
+    HoodieSchema reparsed = HoodieSchema.parse(plain.toString());
+    assertNotEquals(nestedRecord(reparsed, "x_y", "z").getFullName(), nestedRecord(reparsed, "x", "y_z").getFullName());
+  }
+
+  /** The non-null schema of {@code record.<outer>.<inner>}, both fields nullable. */
+  private static HoodieSchema nestedRecord(HoodieSchema record, String outer, String inner) {
+    return record.getField(outer).get().schema().getNonNullType()
+        .getField(inner).get().schema().getNonNullType();
+  }
+
+  @Test
+  public void testGetPlainTypedValueSchemaValueOnlyWrapper() {
+    // A field whose wrapper has no typed_value stays untyped: plain form is VARIANT.
+    HoodieSchema valueOnlyWrapper = HoodieSchema.createRecord("untyped_wrapper", null, null,
+        Collections.singletonList(
+            HoodieSchemaField.of("value", HoodieSchema.createNullable(HoodieSchemaType.BYTES))));
+    HoodieSchema topTypedValue = HoodieSchema.createRecord("typed_value", null, null, Arrays.asList(
+        HoodieSchemaField.of("a", HoodieSchema.createNullable(HoodieSchema.createShreddedFieldStruct("a_wrapper", HoodieSchema.create(HoodieSchemaType.INT)))),
+        HoodieSchemaField.of("u", HoodieSchema.createNullable(valueOnlyWrapper))));
+    HoodieSchema.Variant variant = HoodieSchema.createVariantShredded(topTypedValue);
+
+    HoodieSchema plain = variant.getPlainTypedValueSchema().get();
+    assertEquals(HoodieSchemaType.RECORD, plain.getType());
+    HoodieSchema aPlain = plain.getFields().get(0).schema();
+    aPlain = aPlain.isNullable() ? aPlain.getNonNullType() : aPlain;
+    assertEquals(HoodieSchemaType.INT, aPlain.getType());
+    HoodieSchema uPlain = plain.getFields().get(1).schema();
+    uPlain = uPlain.isNullable() ? uPlain.getNonNullType() : uPlain;
+    assertEquals(HoodieSchemaType.VARIANT, uPlain.getType());
+  }
+
+  @Test
+  public void testGetPlainTypedValueSchemaArrayTypedValue() {
+    // Spec form for arrays: typed_value = array<wrapper{value, typed_value: string}>
+    HoodieSchema arrayTypedValue = HoodieSchema.createArray(
+        HoodieSchema.createShreddedFieldStruct("element_wrapper", HoodieSchema.create(HoodieSchemaType.STRING)));
+    HoodieSchema.Variant variant = HoodieSchema.createVariantShredded(arrayTypedValue);
+
+    HoodieSchema plain = variant.getPlainTypedValueSchema().get();
+    assertEquals(HoodieSchemaType.ARRAY, plain.getType());
+    HoodieSchema element = plain.getElementType();
+    element = element.isNullable() ? element.getNonNullType() : element;
+    assertEquals(HoodieSchemaType.STRING, element.getType());
+  }
+
+  @Test
+  public void testGetPlainTypedValueSchemaArrayWithValueOnlyElements() {
+    // Spark emits a REQUIRED value for array-element value-only wrappers (mixed-type elements
+    // decline typing); the plain form of such an array is array<variant>.
+    HoodieSchema valueOnlyElement = HoodieSchema.createRecord("element_wrapper", null, null,
+        Collections.singletonList(
+            HoodieSchemaField.of("value", HoodieSchema.create(HoodieSchemaType.BYTES))));
+    HoodieSchema.Variant variant = HoodieSchema.createVariantShredded(
+        HoodieSchema.createArray(valueOnlyElement));
+
+    HoodieSchema plain = variant.getPlainTypedValueSchema().get();
+    assertEquals(HoodieSchemaType.ARRAY, plain.getType());
+    HoodieSchema element = plain.getElementType();
+    element = element.isNullable() ? element.getNonNullType() : element;
+    assertEquals(HoodieSchemaType.VARIANT, element.getType());
+  }
 }
diff --git a/hudi-common/src/test/java/org/apache/hudi/core/io/storage/TestVariantShreddingInferenceFileWriter.java b/hudi-common/src/test/java/org/apache/hudi/core/io/storage/TestVariantShreddingInferenceFileWriter.java
new file mode 100644
index 000000000000..cf84f3c74670
--- /dev/null
+++ b/hudi-common/src/test/java/org/apache/hudi/core/io/storage/TestVariantShreddingInferenceFileWriter.java
@@ -0,0 +1,573 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.hudi.core.io.storage;
+
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer;
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer.VariantSample;
+import org.apache.hudi.common.model.HoodieAvroIndexedRecord;
+import org.apache.hudi.common.model.HoodieKey;
+import org.apache.hudi.common.model.HoodieRecord;
+import org.apache.hudi.common.schema.HoodieSchema;
+import org.apache.hudi.common.schema.HoodieSchemaField;
+import org.apache.hudi.common.schema.HoodieSchemaType;
+import org.apache.hudi.common.util.DefaultSizeEstimator;
+import org.apache.hudi.exception.HoodieIOException;
+
+import org.apache.avro.generic.GenericData;
+import org.apache.avro.generic.GenericRecord;
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Properties;
+
+import static java.util.Collections.singletonList;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+public class TestVariantShreddingInferenceFileWriter {
+
+  private static final HoodieSchema RECORD_SCHEMA = HoodieSchema.createRecord("rec", null, null,
+      singletonList(HoodieSchemaField.of("id", HoodieSchema.create(HoodieSchemaType.STRING))));
+  private static final Properties PROPS = new Properties();
+
+  private final VariantShreddingInferenceFileWriter.VariantSampleExtractor noopExtractor =
+      (record, schema, props) -> new VariantSample[1];
+
+  /** A decorator over {@link #noopExtractor} for the column {@code v}. */
+  private VariantShreddingInferenceFileWriter<Object> writer(
+      VariantShreddingSchemaInferrer inferrer,
+      VariantShreddingInferenceFileWriter.InferredWriterFactory<Object> factory,
+      long maxFileSize) {
+    return new VariantShreddingInferenceFileWriter<>(singletonList("v"), noopExtractor, inferrer, factory, maxFileSize);
+  }
+
+  private static HoodieRecord newRecord(String id) {
+    GenericRecord data = new GenericData.Record(RECORD_SCHEMA.toAvroSchema());
+    data.put("id", id);
+    return new HoodieAvroIndexedRecord(new HoodieKey(id, "p"), data);
+  }
+
+  /** Records every call so replay order and call kinds can be asserted. */
+  private static class RecordingWriter implements HoodieFileWriter<Object> {
+    private final List<String> calls = new ArrayList<>();
+    private final List<HoodieRecord> writtenRecords = new ArrayList<>();
+    private final Map<String, String> footerMetadata = new LinkedHashMap<>();
+    private final Object fileFormatMetadata = new Object();
+    private int closeCount = 0;
+    /** An IOException or an Error; anything else is a misuse of the stub. */
+    private Throwable failWriteWith;
+    private IOException failCloseWith;
+
+    @Override
+    public boolean canWrite() {
+      return true;
+    }
+
+    @Override
+    public void writeWithMetadata(HoodieKey key, HoodieRecord record, HoodieSchema schema, Properties props) throws IOException {
+      failIfConfigured(failWriteWith);
+      calls.add("meta:" + key.getRecordKey());
+      writtenRecords.add(record);
+    }
+
+    @Override
+    public void write(String recordKey, HoodieRecord record, HoodieSchema schema, Properties props) throws IOException {
+      failIfConfigured(failWriteWith);
+      calls.add("plain:" + recordKey);
+      writtenRecords.add(record);
+    }
+
+    @Override
+    public void writeRow(String recordKey, Object record) {
+      calls.add("row:" + recordKey);
+    }
+
+    @Override
+    public void addFooterMetadata(Map<String, String> footerMetadata) {
+      this.footerMetadata.putAll(footerMetadata);
+    }
+
+    @Override
+    public Object getFileFormatMetadata() {
+      return fileFormatMetadata;
+    }
+
+    @Override
+    public void close() throws IOException {
+      closeCount++;
+      failIfConfigured(failCloseWith);
+    }
+
+    private static void failIfConfigured(Throwable failure) throws IOException {
+      if (failure instanceof Error) {
+        throw (Error) failure;
+      } else if (failure != null) {
+        throw (IOException) failure;
+      }
+    }
+  }
+
+  @Test
+  public void testReplayPreservesOrderAndCallKinds() throws IOException {
+    Map<String, HoodieSchema> inferred = new HashMap<>();
+    inferred.put("v", HoodieSchema.create(HoodieSchemaType.LONG));
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    RecordingWriter delegate = new RecordingWriter();
+
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> inferred,
+        map -> {
+          factoryCalls.add(map);
+          return delegate;
+        }, Long.MAX_VALUE);
+
+    assertTrue(writer.canWrite());
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    writer.writeWithMetadata(new HoodieKey("r2", "p"), newRecord("r2"), RECORD_SCHEMA, PROPS);
+    writer.write("r3", newRecord("r3"), RECORD_SCHEMA, PROPS);
+    assertTrue(delegate.calls.isEmpty());
+
+    writer.close();
+    assertEquals(1, factoryCalls.size());
+    assertSame(inferred, factoryCalls.get(0));
+    assertEquals(Arrays.asList("plain:r1", "meta:r2", "plain:r3"), delegate.calls);
+    assertEquals(1, delegate.closeCount, "the delegate must be closed exactly once");
+
+    // Idempotent close
+    writer.close();
+    assertEquals(1, factoryCalls.size());
+    assertEquals(1, delegate.closeCount);
+  }
+
+  @Test
+  public void testRecordCountThresholdTriggersMaterialization() throws IOException {
+    RecordingWriter delegate = new RecordingWriter();
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceFileWriter<Object> writer = writer(
+        (columns, samples) -> {
+          assertEquals(VariantShreddingInferenceFileWriter.MAX_BUFFERED_RECORDS, samples.size());
+          return Collections.emptyMap();
+        },
+        map -> {
+          factoryCalls.add(map);
+          return delegate;
+        }, Long.MAX_VALUE);
+
+    for (int i = 0; i < VariantShreddingInferenceFileWriter.MAX_BUFFERED_RECORDS; i++) {
+      writer.write("r" + i, newRecord("r" + i), RECORD_SCHEMA, PROPS);
+    }
+    // Threshold reached: delegate created and buffer replayed before close.
+    assertEquals(1, factoryCalls.size());
+    assertEquals(VariantShreddingInferenceFileWriter.MAX_BUFFERED_RECORDS, delegate.calls.size());
+
+    // Subsequent writes stream straight through.
+    writer.write("tail", newRecord("tail"), RECORD_SCHEMA, PROPS);
+    assertEquals(VariantShreddingInferenceFileWriter.MAX_BUFFERED_RECORDS + 1, delegate.calls.size());
+    writer.close();
+    assertEquals(1, factoryCalls.size());
+  }
+
+  @Test
+  public void testByteCapTriggersEarlyMaterialization() throws IOException {
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> Collections.emptyMap(),
+        map -> {
+          factoryCalls.add(map);
+          return new RecordingWriter();
+        }, 1L);
+
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    // A 1-byte cap is exceeded by any record.
+    assertEquals(1, factoryCalls.size());
+    writer.close();
+  }
+
+  @Test
+  public void testByteCapIsBoundedByTheSharedMaximum() throws IOException {
+    // The cap is min(MAX_BUFFERED_BYTES, maxFileSize): a file size limit above 64MB must not lift
+    // the buffer above 64MB. One record estimating at least the maximum meets it on its own.
+    byte[] payload = new byte[(int) VariantShreddingInferenceFileWriter.MAX_BUFFERED_BYTES];
+    Arrays.fill(payload, (byte) 'x');
+    HoodieRecord record = newRecord(new String(payload, StandardCharsets.ISO_8859_1));
+    assertTrue(new DefaultSizeEstimator<HoodieRecord>().sizeEstimate(record) >= VariantShreddingInferenceFileWriter.MAX_BUFFERED_BYTES);
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> Collections.emptyMap(),
+        map -> {
+          factoryCalls.add(map);
+          return new RecordingWriter();
+        }, Long.MAX_VALUE);
+
+    writer.write("r1", record, RECORD_SCHEMA, PROPS);
+    assertEquals(1, factoryCalls.size(), "a record at the shared maximum materializes whatever the file size limit");
+    writer.close();
+  }
+
+  @Test
+  public void testInferrerFailureDeclinesAndWritesUnshredded() throws IOException {
+    RecordingWriter delegate = new RecordingWriter();
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceFileWriter<Object> writer = writer(
+        (columns, samples) -> {
+          throw new IllegalStateException("malformed variant");
+        },
+        map -> {
+          factoryCalls.add(map);
+          return delegate;
+        }, Long.MAX_VALUE);
+
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    writer.close();
+
+    assertEquals(1, factoryCalls.size());
+    assertTrue(factoryCalls.get(0).isEmpty());
+    assertEquals(singletonList("plain:r1"), delegate.calls);
+    assertEquals(1, delegate.closeCount);
+  }
+
+  @Test
+  public void testZeroRecordCloseStillCreatesDelegate() throws IOException {
+    RecordingWriter delegate = new RecordingWriter();
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceFileWriter<Object> writer = writer(
+        (columns, samples) -> {
+          throw new AssertionError("inferrer must not be called with an empty buffer");
+        },
+        map -> {
+          factoryCalls.add(map);
+          return delegate;
+        }, Long.MAX_VALUE);
+
+    writer.close();
+    assertEquals(1, factoryCalls.size());
+    assertTrue(factoryCalls.get(0).isEmpty());
+    assertEquals(1, delegate.closeCount);
+  }
+
+  @Test
+  public void testWriterCreationFailureIsLatchedAndRethrown() throws IOException {
+    IOException boom = new IOException("create failed");
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> Collections.emptyMap(),
+        map -> {
+          throw boom;
+        }, Long.MAX_VALUE);
+
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    IOException fromClose = assertThrows(IOException.class, writer::close);
+    assertSame(boom, fromClose);
+    // Every subsequent call keeps failing: buffered records were never written.
+    IOException fromWrite = assertThrows(IOException.class,
+        () -> writer.write("r2", newRecord("r2"), RECORD_SCHEMA, PROPS));
+    assertSame(boom, fromWrite);
+  }
+
+  @Test
+  public void testSamplesAlignWithBufferedRecords() throws IOException {
+    // Snapshot: the decorator's internal list is cleared after replay.
+    List<List<VariantSample[]>> seenSamples = new ArrayList<>();
+    VariantShreddingInferenceFileWriter.VariantSampleExtractor extractor = (record, schema, props) -> {
+      VariantSample[] samples = new VariantSample[1];
+      samples[0] = new VariantSample(new byte[] {1}, new byte[] {2});
+      return samples;
+    };
+    VariantShreddingInferenceFileWriter<Object> writer = new VariantShreddingInferenceFileWriter<>(
+        singletonList("v"), extractor, (columns, samples) -> {
+          seenSamples.add(new ArrayList<>(samples));
+          assertEquals(singletonList("v"), columns);
+          return Collections.emptyMap();
+        },
+        map -> new RecordingWriter(), Long.MAX_VALUE);
+
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    writer.write("r2", newRecord("r2"), RECORD_SCHEMA, PROPS);
+    writer.close();
+
+    assertEquals(1, seenSamples.size());
+    assertEquals(2, seenSamples.get(0).size());
+    assertNotNull(seenSamples.get(0).get(0)[0]);
+    assertEquals(1, seenSamples.get(0).get(0)[0].getValue()[0]);
+  }
+
+  @Test
+  public void testCanWriteDelegatesAfterMaterialization() throws IOException {
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> Collections.emptyMap(),
+        map -> new RecordingWriter() {
+          @Override
+          public boolean canWrite() {
+            return false;
+          }
+        }, 1L);
+
+    assertTrue(writer.canWrite());
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    assertFalse(writer.canWrite());
+    writer.close();
+  }
+
+  @Test
+  public void testNullInferredMapTreatedAsDecline() throws IOException {
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> null,
+        map -> {
+          factoryCalls.add(map);
+          return new RecordingWriter();
+        }, Long.MAX_VALUE);
+
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    writer.close();
+    assertEquals(1, factoryCalls.size());
+    assertNotNull(factoryCalls.get(0));
+    assertTrue(factoryCalls.get(0).isEmpty());
+  }
+
+  @Test
+  public void testWriteRowMaterializesAndPassesThrough() throws IOException {
+    RecordingWriter delegate = new RecordingWriter();
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> Collections.emptyMap(),
+        map -> {
+          factoryCalls.add(map);
+          return delegate;
+        }, Long.MAX_VALUE);
+
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    assertTrue(factoryCalls.isEmpty());
+    // A raw row has nothing to sample from: the buffered records are replayed first, then the
+    // row goes straight through, preserving arrival order.
+    writer.writeRow("r2", new Object());
+    assertEquals(1, factoryCalls.size());
+    assertEquals(Arrays.asList("plain:r1", "row:r2"), delegate.calls);
+    writer.close();
+    assertEquals(1, factoryCalls.size());
+  }
+
+  @Test
+  public void testFooterMetadataQueuedUntilMaterialization() throws IOException {
+    RecordingWriter delegate = new RecordingWriter();
+    // A 1-byte cap materializes on the first write, so the forwarded leg below runs on an open writer.
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> Collections.emptyMap(),
+        map -> delegate, 1L);
+
+    writer.addFooterMetadata(Collections.singletonMap("k1", "v1"));
+    assertTrue(delegate.footerMetadata.isEmpty(), "queued until the real writer exists");
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    assertEquals("v1", delegate.footerMetadata.get("k1"), "handed over at materialization");
+
+    // After materialization the call is forwarded directly.
+    writer.addFooterMetadata(Collections.singletonMap("k2", "v2"));
+    assertEquals("v2", delegate.footerMetadata.get("k2"));
+    writer.close();
+  }
+
+  @Test
+  public void testGetFileFormatMetadataMaterializesAndDelegates() throws IOException {
+    RecordingWriter delegate = new RecordingWriter();
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> Collections.emptyMap(),
+        map -> {
+          factoryCalls.add(map);
+          return delegate;
+        }, Long.MAX_VALUE);
+
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    assertTrue(factoryCalls.isEmpty());
+    // Footer metadata lives in the real writer, so asking for it creates that writer first.
+    assertSame(delegate.fileFormatMetadata, writer.getFileFormatMetadata());
+    assertEquals(1, factoryCalls.size());
+    assertEquals(singletonList("plain:r1"), delegate.calls);
+
+    // The native log-format writer asks after close() (column stats): still the delegate's answer.
+    writer.close();
+    assertSame(delegate.fileFormatMetadata, writer.getFileFormatMetadata());
+    assertEquals(1, factoryCalls.size());
+  }
+
+  @Test
+  public void testReplayFailureIsLatchedAndRethrown() throws IOException {
+    RecordingWriter delegate = new RecordingWriter();
+    IOException boom = new IOException("replay failed");
+    delegate.failWriteWith = boom;
+    IOException closeBoom = new IOException("close failed");
+    delegate.failCloseWith = closeBoom;
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> Collections.emptyMap(),
+        map -> delegate, Long.MAX_VALUE);
+
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    IOException fromClose = assertThrows(IOException.class, writer::close);
+    assertSame(boom, fromClose);
+    // The delegate was created but never closed by the try path, so the catch path closes it once,
+    // and a failure of that close rides along as suppressed rather than replacing or hiding boom.
+    assertEquals(1, delegate.closeCount);
+    assertSame(closeBoom, fromClose.getSuppressed()[0]);
+    // Latched: the buffered record was never written, so every later call keeps failing.
+    assertSame(boom, assertThrows(IOException.class, () -> writer.write("r2", newRecord("r2"), RECORD_SCHEMA, PROPS)));
+    assertSame(boom, assertThrows(HoodieIOException.class, writer::getFileFormatMetadata).getCause());
+  }
+
+  @Test
+  public void testReplayErrorIsLatchedTooAndCloseDoesNotFinishTheFile() throws IOException {
+    // An Error mid-replay latches like an exception does: inference already treats a LinkageError
+    // as reachable (a writer linked against another Spark than the runtime's), and an unlatched
+    // one would let close() finish the file without the records left in the buffer.
+    RecordingWriter delegate = new RecordingWriter();
+    NoClassDefFoundError boom = new NoClassDefFoundError("replay failed");
+    delegate.failWriteWith = boom;
+    // A 1-byte cap materializes on the first write, so the Error surfaces from write(), not close().
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> Collections.emptyMap(),
+        map -> delegate, 1L);
+
+    assertSame(boom, assertThrows(NoClassDefFoundError.class,
+        () -> writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS)));
+    assertSame(boom, assertThrows(IOException.class, writer::close).getCause());
+    assertEquals(1, delegate.closeCount);
+  }
+
+  @Test
+  public void testMaterializeErrorInsideCloseStillClosesTheDelegate() throws IOException {
+    // With the caps never tripped, the first materialization happens inside close(): the Error
+    // must still close the delegate created just above, or the file handle leaks.
+    RecordingWriter delegate = new RecordingWriter();
+    NoClassDefFoundError boom = new NoClassDefFoundError("replay failed");
+    delegate.failWriteWith = boom;
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> Collections.emptyMap(),
+        map -> delegate, Long.MAX_VALUE);
+
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    assertSame(boom, assertThrows(NoClassDefFoundError.class, writer::close));
+    assertEquals(1, delegate.closeCount);
+  }
+
+  @Test
+  public void testThrowingDelegateCloseSurfacesAndIsNotRetried() throws IOException {
+    RecordingWriter delegate = new RecordingWriter();
+    IOException boom = new IOException("close failed");
+    delegate.failCloseWith = boom;
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> Collections.emptyMap(),
+        map -> delegate, Long.MAX_VALUE);
+
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    assertSame(boom, assertThrows(IOException.class, writer::close));
+    assertEquals(1, delegate.closeCount, "a throwing delegate.close() must surface, not be retried");
+  }
+
+  @Test
+  public void testPreparedRecordIsSampledAndReplayed() throws IOException {
+    // An extractor that materializes the record (the Avro one) hands the materialized form back
+    // via prepare(); the decorator samples that form and replays it, so the writer never redoes
+    // the materialization.
+    HoodieRecord prepared = newRecord("prepared");
+    List<HoodieRecord> sampled = new ArrayList<>();
+    VariantShreddingInferenceFileWriter.VariantSampleExtractor extractor =
+        new VariantShreddingInferenceFileWriter.VariantSampleExtractor() {
+          @Override
+          public VariantSample[] extract(HoodieRecord record, HoodieSchema schema, Properties props) {
+            sampled.add(record);
+            return new VariantSample[1];
+          }
+
+          @Override
+          public HoodieRecord prepare(HoodieRecord record, HoodieSchema schema, Properties props) {
+            return prepared;
+          }
+        };
+    RecordingWriter delegate = new RecordingWriter();
+    VariantShreddingInferenceFileWriter<Object> writer = new VariantShreddingInferenceFileWriter<>(
+        singletonList("v"), extractor, (columns, samples) -> Collections.emptyMap(),
+        map -> delegate, Long.MAX_VALUE);
+
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    writer.close();
+
+    assertEquals(singletonList(prepared), sampled);
+    assertEquals(singletonList(prepared), delegate.writtenRecords);
+  }
+
+  @Test
+  public void testByteCapRechargesTheBufferWhenTheEstimateGrows() throws IOException {
+    // 99 small records, then a big 100th that lands on the periodic re-estimation. The moving
+    // average grows to about 0.9 * small + 0.1 * big, and the re-estimation charges the 99 earlier
+    // records at that too, so the buffer (about 90 small + 10 big) meets a cap of one big record
+    // right there. Without the rescale the 99 would stay charged at small, and about 100 small
+    // plus a tenth of big would leave the cap untripped: the precondition below keeps that gap.
+    String padding = new String(new char[1 << 22]).replace('\0', 'x');
+    DefaultSizeEstimator<HoodieRecord> estimator = new DefaultSizeEstimator<>();
+    long small = estimator.sizeEstimate(newRecord("r000"));
+    long big = estimator.sizeEstimate(newRecord("r099" + padding));
+    assertTrue(big > 200 * small, "expected the big record to dwarf the small ones: " + small + " vs " + big);
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceFileWriter<Object> writer = writer((columns, samples) -> Collections.emptyMap(),
+        map -> {
+          factoryCalls.add(map);
+          return new RecordingWriter();
+        }, big);
+
+    for (int i = 0; i < 99; i++) {
+      writer.write("r" + i, newRecord(String.format("r%03d", i)), RECORD_SCHEMA, PROPS);
+    }
+    assertTrue(factoryCalls.isEmpty(), "99 small records stay under a one-big-record cap");
+    writer.write("r99", newRecord("r099" + padding), RECORD_SCHEMA, PROPS);
+    assertEquals(1, factoryCalls.size(), "the re-estimation on the 100th record recharges the buffer past the cap");
+    writer.close();
+  }
+
+  @Test
+  public void testSharedSizeIsNotChargedPerRecord() throws IOException {
+    // An extractor reporting shared state (the schema graph every record references) has that
+    // much subtracted from each record's estimate: here all but 10 bytes, so a 25-byte cap holds
+    // two records and trips on the third instead of the first.
+    long perRecord = new DefaultSizeEstimator<HoodieRecord>().sizeEstimate(newRecord("r0"));
+    VariantShreddingInferenceFileWriter.VariantSampleExtractor sharing =
+        new VariantShreddingInferenceFileWriter.VariantSampleExtractor() {
+          @Override
+          public VariantSample[] extract(HoodieRecord record, HoodieSchema schema, Properties props) {
+            return new VariantSample[1];
+          }
+
+          @Override
+          public long sharedSizeEstimate(HoodieSchema schema) {
+            return perRecord - 10;
+          }
+        };
+    List<Map<String, HoodieSchema>> factoryCalls = new ArrayList<>();
+    VariantShreddingInferenceFileWriter<Object> writer = new VariantShreddingInferenceFileWriter<>(
+        singletonList("v"), sharing, (columns, samples) -> Collections.emptyMap(),
+        map -> {
+          factoryCalls.add(map);
+          return new RecordingWriter();
+        }, 25L);
+
+    writer.write("r0", newRecord("r0"), RECORD_SCHEMA, PROPS);
+    writer.write("r1", newRecord("r1"), RECORD_SCHEMA, PROPS);
+    assertTrue(factoryCalls.isEmpty(), "20 of 25 bytes: two records buffered");
+    writer.write("r2", newRecord("r2"), RECORD_SCHEMA, PROPS);
+    assertEquals(1, factoryCalls.size(), "30 of 25 bytes: materialize on the third");
+    writer.close();
+  }
+}
diff --git a/hudi-hadoop-common/src/main/java/org/apache/hudi/io/storage/hadoop/HoodieAvroFileWriterFactory.java b/hudi-hadoop-common/src/main/java/org/apache/hudi/io/storage/hadoop/HoodieAvroFileWriterFactory.java
index 1920619600f3..9c91068a38e5 100644
--- a/hudi-hadoop-common/src/main/java/org/apache/hudi/io/storage/hadoop/HoodieAvroFileWriterFactory.java
+++ b/hudi-hadoop-common/src/main/java/org/apache/hudi/io/storage/hadoop/HoodieAvroFileWriterFactory.java
@@ -20,7 +20,10 @@
 package org.apache.hudi.io.storage.hadoop;
 
 import org.apache.hudi.avro.HoodieAvroWriteSupport;
-import org.apache.hudi.common.avro.VariantShreddingProvider;
+import org.apache.hudi.common.avro.AvroVariantSampleExtractor;
+import org.apache.hudi.common.avro.VariantSchemaUtils;
+import org.apache.hudi.common.avro.VariantShreddingRuntime;
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer;
 import org.apache.hudi.common.bloom.BloomFilter;
 import org.apache.hudi.common.config.HoodieConfig;
 import org.apache.hudi.common.config.HoodieParquetConfig;
@@ -40,6 +43,7 @@ import org.apache.hudi.core.io.storage.HoodieFileWriter;
 import org.apache.hudi.core.io.storage.HoodieFileWriterFactory;
 import org.apache.hudi.core.io.storage.HoodieHFileConfig;
 import org.apache.hudi.core.io.storage.HoodieOrcConfig;
+import org.apache.hudi.core.io.storage.VariantShreddingInferenceFileWriter;
 import org.apache.hudi.exception.HoodieException;
 import org.apache.hudi.io.compress.CompressionCodec;
 import org.apache.hudi.storage.HoodieStorage;
@@ -54,6 +58,7 @@ import org.apache.parquet.schema.MessageType;
 
 import java.io.IOException;
 import java.io.OutputStream;
+import java.util.List;
 import java.util.Properties;
 
 import static org.apache.hudi.common.config.HoodieStorageConfig.HFILE_WRITER_TO_ALLOW_DUPLICATES;
@@ -70,6 +75,40 @@ public class HoodieAvroFileWriterFactory extends HoodieFileWriterFactory {
   protected HoodieFileWriter newParquetFileWriter(
       String instantTime, StoragePath path, HoodieConfig config, HoodieSchema schema,
       TaskContextSupplier taskContextSupplier) throws IOException {
+    List<String> inferableColumns = VariantSchemaUtils.getInferableVariantColumns(config, schema);
+    if (!inferableColumns.isEmpty() && isShreddingProviderAvailable(config)) {
+      Option<VariantShreddingSchemaInferrer> inferrer = VariantShreddingRuntime.lookupInferrer();
+      if (inferrer.isPresent()) {
+        // The Avro write support derives its shredding from the schema argument, so the deferred
+        // creation below splices the inferred typed_value into it; the config stays untouched.
+        return new VariantShreddingInferenceFileWriter<>(
+            inferableColumns,
+            new AvroVariantSampleExtractor(inferableColumns),
+            inferrer.get(),
+            inferred -> createParquetFileWriter(instantTime, path, config,
+                VariantSchemaUtils.applyInferredShredding(schema, inferred), taskContextSupplier),
+            config.getLongOrDefault(HoodieStorageConfig.PARQUET_MAX_FILE_SIZE));
+      }
+    }
+    return createParquetFileWriter(instantTime, path, config, schema, taskContextSupplier);
+  }
+
+  /**
+   * Whether a {@link org.apache.hudi.common.avro.VariantShreddingProvider} will be available to the
+   * write support; the Avro path cannot shred without one, so inference must decline up front
+   * instead of failing at writer materialization (e.g. when the provider class is explicitly
+   * configured empty, which also disables auto-detection).
+   */
+  private static boolean isShreddingProviderAvailable(HoodieConfig config) {
+    if (config.contains(PARQUET_VARIANT_SHREDDING_PROVIDER_CLASS.key())) {
+      return !StringUtils.isNullOrEmpty(config.getString(PARQUET_VARIANT_SHREDDING_PROVIDER_CLASS));
+    }
+    return VariantShreddingRuntime.getProviderClass().isPresent();
+  }
+
+  private HoodieFileWriter createParquetFileWriter(
+      String instantTime, StoragePath path, HoodieConfig config, HoodieSchema schema,
+      TaskContextSupplier taskContextSupplier) throws IOException {
     MetaFieldsMode metaFieldsMode = MetaFieldsMode.resolve(config);
 
     Pair<StorageConfiguration, HoodieConfig> injectedConfigs = HoodieParquetConfigInjector.applyConfigInjector(path, storage.getConf(), config);
@@ -149,10 +188,8 @@ public class HoodieAvroFileWriterFactory extends HoodieFileWriterFactory {
     Properties props = TypedProperties.copy(config.getProps());
     // Auto-detect variant shredding provider from classpath if not explicitly configured
     if (!props.containsKey(PARQUET_VARIANT_SHREDDING_PROVIDER_CLASS.key())) {
-      String detectedClass = VariantShreddingProvider.detectProviderClassOnClasspath();
-      if (detectedClass != null) {
-        props.setProperty(PARQUET_VARIANT_SHREDDING_PROVIDER_CLASS.key(), detectedClass);
-      }
+      VariantShreddingRuntime.getProviderClass().ifPresent(detected ->
+          props.setProperty(PARQUET_VARIANT_SHREDDING_PROVIDER_CLASS.key(), detected));
     }
     return (HoodieAvroWriteSupport) ReflectionUtils.loadClass(
         config.getStringOrDefault(HoodieStorageConfig.HOODIE_AVRO_WRITE_SUPPORT_CLASS),
@@ -163,5 +200,4 @@ public class HoodieAvroFileWriterFactory extends HoodieFileWriterFactory {
         // typed_value, failing the write with "Null-value for required field: value".
         getAvroSchemaConverter((Configuration) storageConf.unwrapAs(Configuration.class)).convert(effectiveSchema), schema, filter, props);
   }
-
 }
diff --git a/hudi-hadoop-common/src/main/java/org/apache/hudi/io/storage/hadoop/HoodieVariantReconstruction.java b/hudi-hadoop-common/src/main/java/org/apache/hudi/io/storage/hadoop/HoodieVariantReconstruction.java
index cfc0d680d626..09fa1648580c 100644
--- a/hudi-hadoop-common/src/main/java/org/apache/hudi/io/storage/hadoop/HoodieVariantReconstruction.java
+++ b/hudi-hadoop-common/src/main/java/org/apache/hudi/io/storage/hadoop/HoodieVariantReconstruction.java
@@ -21,6 +21,7 @@ package org.apache.hudi.io.storage.hadoop;
 
 import org.apache.hudi.common.avro.VariantSchemaUtils;
 import org.apache.hudi.common.avro.VariantShreddingProvider;
+import org.apache.hudi.common.avro.VariantShreddingRuntime;
 import org.apache.hudi.common.config.HoodieStorageConfig;
 import org.apache.hudi.common.schema.HoodieSchema;
 import org.apache.hudi.common.schema.HoodieSchemaField;
@@ -268,7 +269,7 @@ final class HoodieVariantReconstruction {
     String providerClass = storage.getConf()
         .getString(HoodieStorageConfig.PARQUET_VARIANT_SHREDDING_PROVIDER_CLASS.key()).orElse(null);
     if (providerClass == null || providerClass.isEmpty()) {
-      providerClass = VariantShreddingProvider.detectProviderClassOnClasspath();
+      providerClass = VariantShreddingRuntime.getProviderClass().orElse(null);
     }
     return providerClass == null ? null : (VariantShreddingProvider) ReflectionUtils.loadClass(providerClass);
   }
diff --git a/hudi-hadoop-common/src/main/java/org/apache/parquet/avro/AvroSchemaConverterWithTimestampNTZ.java b/hudi-hadoop-common/src/main/java/org/apache/parquet/avro/AvroSchemaConverterWithTimestampNTZ.java
index c28a9a83c278..af7238b17de9 100644
--- a/hudi-hadoop-common/src/main/java/org/apache/parquet/avro/AvroSchemaConverterWithTimestampNTZ.java
+++ b/hudi-hadoop-common/src/main/java/org/apache/parquet/avro/AvroSchemaConverterWithTimestampNTZ.java
@@ -128,6 +128,20 @@ public class AvroSchemaConverterWithTimestampNTZ extends HoodieAvroParquetSchema
     return new MessageType(schema.getFullName(), convertFields(schema.getFields(), ""));
   }
 
+  /**
+   * Returns the parquet VARIANT logical type annotation, or null when the running parquet version
+   * predates it (1.16 / Spark 4.1). Resolved reflectively because this engine-agnostic module also
+   * compiles and runs against parquet 1.15.2 on Spark 4.0, where {@code variantType} does not exist.
+   */
+  private static LogicalTypeAnnotation variantLogicalType() {
+    try {
+      return (LogicalTypeAnnotation) LogicalTypeAnnotation.class
+          .getMethod("variantType", byte.class).invoke(null, (byte) 1);
+    } catch (ReflectiveOperationException e) {
+      return null;
+    }
+  }
+
   private List<Type> convertFields(List<HoodieSchemaField> fields, String schemaPath) {
     List<Type> types = new ArrayList<Type>(fields.size());
     for (HoodieSchemaField field : fields) {
@@ -266,9 +280,21 @@ public class AvroSchemaConverterWithTimestampNTZ extends HoodieAvroParquetSchema
       case UNION:
         return convertUnion(fieldName, schema, repetition, schemaPath);
       case VARIANT:
-        // Variant is represented as a record with value and metadata binary fields
-        // Convert the variant schema's fields to Parquet types
-        return new GroupType(repetition, fieldName, convertFields(schema.getFields(), schemaPath));
+        // Variant is a group of value/metadata (plus typed_value when shredded). Tag it with the
+        // VARIANT logical type so external readers recognize the column as a Variant, matching
+        // Spark's native parquet schema and the row-writer path. The annotation only exists in
+        // parquet 1.16+ (Spark 4.1+); on older parquet (Spark 4.0/3.x) variantLogicalType() returns
+        // null and the group stays unannotated. Built via the Types builder because the
+        // annotation-bearing GroupType constructor is not public outside org.apache.parquet.schema.
+        Types.GroupBuilder<GroupType> variantBuilder = Types.buildGroup(repetition);
+        LogicalTypeAnnotation variantAnnotation = variantLogicalType();
+        if (variantAnnotation != null) {
+          variantBuilder.as(variantAnnotation);
+        }
+        for (Type variantFieldType : convertFields(schema.getFields(), schemaPath)) {
+          variantBuilder.addField(variantFieldType);
+        }
+        return variantBuilder.named(fieldName);
       default:
         throw new UnsupportedOperationException("Cannot convert Avro type " + type);
     }
diff --git a/hudi-hadoop-common/src/test/java/org/apache/hudi/avro/TestHoodieAvroWriteSupportShredding.java b/hudi-hadoop-common/src/test/java/org/apache/hudi/avro/TestHoodieAvroWriteSupportShredding.java
index 9ec32c9da3fd..653e9cbf9a7b 100644
--- a/hudi-hadoop-common/src/test/java/org/apache/hudi/avro/TestHoodieAvroWriteSupportShredding.java
+++ b/hudi-hadoop-common/src/test/java/org/apache/hudi/avro/TestHoodieAvroWriteSupportShredding.java
@@ -24,6 +24,10 @@ import org.apache.hudi.common.schema.HoodieSchema;
 import org.apache.hudi.common.schema.HoodieSchemaField;
 import org.apache.hudi.common.schema.HoodieSchemaType;
 
+import org.apache.parquet.avro.AvroSchemaConverterWithTimestampNTZ;
+import org.apache.parquet.schema.GroupType;
+import org.apache.parquet.schema.LogicalTypeAnnotation;
+import org.apache.parquet.schema.MessageType;
 import org.junit.jupiter.api.Test;
 
 import java.util.Arrays;
@@ -36,6 +40,9 @@ import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 class TestHoodieAvroWriteSupportShredding {
 
@@ -47,16 +54,8 @@ class TestHoodieAvroWriteSupportShredding {
    */
   @Test
   void forcedShreddingDdlTreatsDecimalParensAsOneField() {
-    HoodieSchema record = HoodieSchema.createRecord(
-        "test_record", "org.apache.hudi.test", null,
-        Collections.singletonList(HoodieSchemaField.of("v", HoodieSchema.createVariant())));
-
-    Properties props = new Properties();
-    props.setProperty(HoodieStorageConfig.PARQUET_VARIANT_WRITE_SHREDDING_ENABLED.key(), "true");
-    props.setProperty(HoodieStorageConfig.PARQUET_VARIANT_FORCE_SHREDDING_SCHEMA_FOR_TEST.key(),
-        "a int, b string, c decimal(15, 1)");
-
-    HoodieSchema effective = HoodieAvroWriteSupport.generateEffectiveSchema(record, props);
+    HoodieSchema effective = HoodieAvroWriteSupport.generateEffectiveSchema(
+        singleVariantRecord(), forcedShreddingProps("a int, b string, c decimal(15, 1)"));
 
     HoodieSchema variantField = effective.getFields().get(0).schema();
     HoodieSchema variant = variantField.isNullable() ? variantField.getNonNullType() : variantField;
@@ -115,4 +114,56 @@ class TestHoodieAvroWriteSupportShredding {
     assertInstanceOf(HoodieSchema.Variant.class, unwrapped, label + " should still be a variant");
     assertFalse(((HoodieSchema.Variant) unwrapped).isShredded(), label + " should no longer be shredded");
   }
+
+  /**
+   * A shredded variant written via the Avro path must carry the parquet VARIANT logical type on the
+   * variant group so external readers recognize it (mirroring the row-writer path and native Spark).
+   * The annotation type only exists in parquet 1.16+ (Spark 4.1+); on older parquet it stays absent.
+   */
+  @Test
+  void shreddedVariantParquetGroupCarriesVariantLogicalType() {
+    HoodieSchema effective = HoodieAvroWriteSupport.generateEffectiveSchema(
+        singleVariantRecord(), forcedShreddingProps("a int, b string"));
+    MessageType parquet = new AvroSchemaConverterWithTimestampNTZ().convert(effective);
+    GroupType variantGroup = parquet.getType("v").asGroupType();
+    // The converter tags unshredded groups too, so pin that the group under test is the shredded
+    // one; on parquet < 1.16 (every CI lane today) this is the assertion that keeps the test honest.
+    assertTrue(variantGroup.containsField("typed_value"),
+        "expected a shredded typed_value group: " + variantGroup);
+
+    LogicalTypeAnnotation annotation = variantGroup.getLogicalTypeAnnotation();
+    if (variantLogicalTypeSupported()) {
+      assertNotNull(annotation,
+          "shredded variant group should carry the VARIANT logical type: " + variantGroup);
+      assertTrue(annotation.toString().contains("VARIANT"),
+          "expected the VARIANT logical type, got: " + annotation);
+    } else {
+      assertNull(annotation, "parquet < 1.16 has no VARIANT logical type: " + variantGroup);
+    }
+  }
+
+  /** A record with one unshredded variant column {@code v}. */
+  private static HoodieSchema singleVariantRecord() {
+    return HoodieSchema.createRecord(
+        "test_record", "org.apache.hudi.test", null,
+        Collections.singletonList(HoodieSchemaField.of("v", HoodieSchema.createVariant())));
+  }
+
+  /** Write-support properties that shred every variant column with the given forced test DDL. */
+  private static Properties forcedShreddingProps(String forcedShreddingDdl) {
+    Properties props = new Properties();
+    props.setProperty(HoodieStorageConfig.PARQUET_VARIANT_WRITE_SHREDDING_ENABLED.key(), "true");
+    props.setProperty(HoodieStorageConfig.PARQUET_VARIANT_FORCE_SHREDDING_SCHEMA_FOR_TEST.key(), forcedShreddingDdl);
+    return props;
+  }
+
+  private static boolean variantLogicalTypeSupported() {
+    // Probes parquet directly, not the converter's own probe: the expectation must be an independent oracle.
+    try {
+      LogicalTypeAnnotation.class.getMethod("variantType", byte.class);
+      return true;
+    } catch (NoSuchMethodException e) {
+      return false;
+    }
+  }
 }
diff --git a/hudi-hadoop-common/src/test/java/org/apache/hudi/io/storage/hadoop/TestHoodieAvroFileWriterFactoryVariantInference.java b/hudi-hadoop-common/src/test/java/org/apache/hudi/io/storage/hadoop/TestHoodieAvroFileWriterFactoryVariantInference.java
new file mode 100644
index 000000000000..380868c118df
--- /dev/null
+++ b/hudi-hadoop-common/src/test/java/org/apache/hudi/io/storage/hadoop/TestHoodieAvroFileWriterFactoryVariantInference.java
@@ -0,0 +1,112 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.hudi.io.storage.hadoop;
+
+import org.apache.hudi.common.avro.VariantSchemaUtils;
+import org.apache.hudi.common.avro.VariantShreddingRuntime;
+import org.apache.hudi.common.config.HoodieConfig;
+import org.apache.hudi.common.config.HoodieStorageConfig;
+import org.apache.hudi.common.engine.LocalTaskContextSupplier;
+import org.apache.hudi.common.schema.HoodieSchema;
+import org.apache.hudi.common.schema.HoodieSchemaField;
+import org.apache.hudi.common.schema.HoodieSchemaType;
+import org.apache.hudi.common.testutils.HoodieTestUtils;
+import org.apache.hudi.core.io.storage.HoodieFileWriter;
+import org.apache.hudi.storage.HoodieStorage;
+import org.apache.hudi.storage.StoragePath;
+
+import org.apache.avro.generic.GenericData;
+import org.apache.avro.generic.GenericRecord;
+import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.fs.Path;
+import org.apache.parquet.hadoop.ParquetFileReader;
+import org.apache.parquet.schema.GroupType;
+import org.apache.parquet.schema.MessageType;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.ByteBuffer;
+import java.util.Arrays;
+
+import static java.util.Collections.singletonList;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assumptions.assumeFalse;
+
+/**
+ * Pins the no-inferrer degradation of shredding-schema inference in
+ * {@link HoodieAvroFileWriterFactory}: this module's classpath carries no Spark version module,
+ * so {@link VariantShreddingRuntime#lookupInferrer()} is empty here, which is what engines without
+ * Spark 4.1+ (Flink, Java, Spark 4.0) see in production.
+ */
+public class TestHoodieAvroFileWriterFactoryVariantInference {
+
+  @TempDir
+  java.nio.file.Path tmpDir;
+
+  @Test
+  public void testInferenceFlagWithoutInferrerWritesPlainUnshreddedFile() throws Exception {
+    assumeFalse(VariantShreddingRuntime.lookupInferrer().isPresent(),
+        "this test pins the fallback for classpaths without a shredding-schema inferrer");
+
+    HoodieSchema schema = HoodieSchema.createRecord("rec", "ns", null, Arrays.asList(
+        HoodieSchemaField.of("id", HoodieSchema.create(HoodieSchemaType.STRING)),
+        HoodieSchemaField.of("v", HoodieSchema.createNullable(HoodieSchema.createVariant()))));
+    HoodieConfig config = new HoodieConfig();
+    config.setValue(HoodieStorageConfig.PARQUET_VARIANT_SHREDDING_SCHEMA_INFERENCE_ENABLED, "true");
+    // Name a provider explicitly: the factory also declines when no shredding provider is available,
+    // and this module ships none, so without this the inferrer gate (the one under test) would never
+    // be reached. The class is never loaded: the write support only resolves it for shredded schemas.
+    config.setValue(HoodieStorageConfig.PARQUET_VARIANT_SHREDDING_PROVIDER_CLASS,
+        "org.apache.hudi.variant.Spark4VariantShreddingProvider");
+    // Inference applies as far as the config is concerned...
+    assertEquals(singletonList("v"), VariantSchemaUtils.getInferableVariantColumns(config, schema));
+
+    HoodieStorage storage = HoodieTestUtils.getStorage(tmpDir.toString());
+    StoragePath path = new StoragePath(tmpDir.resolve("f1_1-0-1_000.parquet").toAbsolutePath().toString());
+    HoodieFileWriter writer = new HoodieAvroFileWriterFactory(storage)
+        .newParquetFileWriter("000", path, config, schema, new LocalTaskContextSupplier());
+    // ...but with no inferrer on the classpath the factory must hand out the plain writer, not the
+    // inference decorator, and the write must go through unshredded rather than fail.
+    assertInstanceOf(HoodieAvroParquetWriter.class, writer);
+
+    HoodieSchema variantSchema = schema.getField("v").get().schema().getNonNullType();
+    GenericRecord variant = new GenericData.Record(variantSchema.toAvroSchema());
+    variant.put(HoodieSchema.Variant.VARIANT_METADATA_FIELD, ByteBuffer.wrap(new byte[] {1, 0, 0}));
+    variant.put(HoodieSchema.Variant.VARIANT_VALUE_FIELD, ByteBuffer.wrap(new byte[] {0}));
+    GenericRecord record = new GenericData.Record(schema.toAvroSchema());
+    record.put("id", "r1");
+    record.put("v", variant);
+    ((HoodieAvroParquetWriter) writer).writeAvro("r1", record);
+    writer.close();
+    assertTrue(storage.exists(path));
+
+    MessageType footer;
+    try (ParquetFileReader reader = ParquetFileReader.open(new Configuration(), new Path(path.toUri()))) {
+      footer = reader.getFooter().getFileMetaData().getSchema();
+    }
+    GroupType variantGroup = footer.getType("v").asGroupType();
+    assertFalse(variantGroup.containsField("typed_value"),
+        "no inferrer: the variant must be written unshredded, got " + variantGroup);
+    assertTrue(variantGroup.containsField("metadata") && variantGroup.containsField("value"));
+  }
+}
diff --git a/hudi-hadoop-common/src/test/java/org/apache/parquet/avro/TestAvroSchemaConverter.java b/hudi-hadoop-common/src/test/java/org/apache/parquet/avro/TestAvroSchemaConverter.java
index 4e9792aa2ed6..198763c53973 100644
--- a/hudi-hadoop-common/src/test/java/org/apache/parquet/avro/TestAvroSchemaConverter.java
+++ b/hudi-hadoop-common/src/test/java/org/apache/parquet/avro/TestAvroSchemaConverter.java
@@ -119,6 +119,28 @@ public class TestAvroSchemaConverter {
     assertEquals(expectedMT.toString(), messageType.toString());
   }
 
+  /**
+   * The VARIANT logical type annotation the converter stamps on variant groups on parquet 1.16+
+   * (Spark 4.1+ profiles), as {@code GroupType.toString()} renders it; empty on older parquet,
+   * where the annotation type does not exist and groups stay plain. {@code MessageTypeParser}
+   * cannot parse the annotation, so variant expectations are compared against the converter's
+   * {@code toString()} directly rather than through {@link #testAvroToParquetConversion}.
+   */
+  private static String variantAnnotation() {
+    // Probes parquet directly, not the converter's own probe: the expectation must be an independent oracle.
+    try {
+      LogicalTypeAnnotation.class.getMethod("variantType", byte.class);
+      return " (VARIANT(1))";
+    } catch (NoSuchMethodException e) {
+      return "";
+    }
+  }
+
+  private void testVariantAvroToParquetConversion(HoodieSchema schema, String expectedMessageType) {
+    MessageType messageType = getAvroSchemaConverter(new Configuration(false)).convert(schema);
+    assertEquals(expectedMessageType, messageType.toString());
+  }
+
   private void testParquetToAvroConversion(HoodieSchema schema, String schemaString) throws Exception {
     testParquetToAvroConversion(new Configuration(false), schema, schemaString);
   }
@@ -865,10 +887,10 @@ public class TestAvroSchemaConverter {
     HoodieSchema variant = HoodieSchema.createVariant();
     HoodieSchema schema = HoodieSchema.createRecord("myrecord", null, null, false,
         Collections.singletonList(HoodieSchemaField.of("myvariant", variant, null, null)));
-    testAvroToParquetConversion(
+    testVariantAvroToParquetConversion(
         schema,
         "message myrecord {\n"
-            + "  required group myvariant {\n"
+            + "  required group myvariant" + variantAnnotation() + " {\n"
             + "    required binary metadata;\n"
             + "    required binary value;\n"
             + "  }\n"
@@ -880,10 +902,10 @@ public class TestAvroSchemaConverter {
     HoodieSchema variant = HoodieSchema.createVariantShredded(HoodieSchema.create(HoodieSchemaType.INT));
     HoodieSchema schema = HoodieSchema.createRecord("myrecord", null, null, false,
         Collections.singletonList(HoodieSchemaField.of("myvariant", variant, null, null)));
-    testAvroToParquetConversion(
+    testVariantAvroToParquetConversion(
         schema,
         "message myrecord {\n"
-            + "  required group myvariant {\n"
+            + "  required group myvariant" + variantAnnotation() + " {\n"
             + "    required binary metadata;\n"
             + "    optional binary value;\n"
             + "    required int32 typed_value;\n"
@@ -897,10 +919,10 @@ public class TestAvroSchemaConverter {
     HoodieSchema schema = HoodieSchema.createRecord("myrecord", null, null, false,
         Collections.singletonList(
             HoodieSchemaField.of("myvariant", HoodieSchema.createNullable(variant), null, HoodieSchema.NULL_VALUE)));
-    testAvroToParquetConversion(
+    testVariantAvroToParquetConversion(
         schema,
         "message myrecord {\n"
-            + "  optional group myvariant {\n"
+            + "  optional group myvariant" + variantAnnotation() + " {\n"
             + "    required binary metadata;\n"
             + "    required binary value;\n"
             + "  }\n"
@@ -971,23 +993,6 @@ public class TestAvroSchemaConverter {
     }
   }
 
-  @Test
-  public void testVariantToParquetConversion() throws Exception {
-    // Create a record with a variant field
-    HoodieSchema variantSchema = HoodieSchema.createRecord("variantRecord", null, null, false,
-        Collections.singletonList(
-            HoodieSchemaField.of("v", HoodieSchema.createVariant(), null, null)));
-
-    String expectedParquet = "message variantRecord {\n"
-        + "  required group v {\n"
-        + "    required binary metadata;\n"
-        + "    required binary value;\n"
-        + "  }\n"
-        + "}\n";
-
-    testAvroToParquetConversion(variantSchema, expectedParquet);
-  }
-
   public static Configuration conf(String name, boolean value) {
     Configuration conf = new Configuration(false);
     conf.setBoolean(name, value);
diff --git a/hudi-spark-datasource/hudi-spark/src/test/scala/org/apache/spark/sql/hudi/dml/schema/TestVariantDataType.scala b/hudi-spark-datasource/hudi-spark/src/test/scala/org/apache/spark/sql/hudi/dml/schema/TestVariantDataType.scala
index 9c88590cb72e..b98ecccae923 100644
--- a/hudi-spark-datasource/hudi-spark/src/test/scala/org/apache/spark/sql/hudi/dml/schema/TestVariantDataType.scala
+++ b/hudi-spark-datasource/hudi-spark/src/test/scala/org/apache/spark/sql/hudi/dml/schema/TestVariantDataType.scala
@@ -20,8 +20,10 @@
 package org.apache.spark.sql.hudi.dml.schema
 
 import org.apache.hudi.{DataSourceReadOptions, HoodieSparkUtils}
+import org.apache.hudi.common.avro.VariantShreddingRuntime
 import org.apache.hudi.common.fs.FSUtils
 import org.apache.hudi.common.model.HoodieRecord.HoodieRecordType
+import org.apache.hudi.common.model.WriteOperationType
 import org.apache.hudi.common.schema.HoodieSchema
 import org.apache.hudi.common.schema.internal.HoodieSchemaException
 import org.apache.hudi.common.table.TableSchemaResolver
@@ -39,8 +41,10 @@ import org.apache.spark.sql.catalyst.TableIdentifier
 import org.apache.spark.sql.catalyst.catalog.{CatalogStorageFormat, CatalogTable, CatalogTableType}
 import org.apache.spark.sql.hudi.command.CreateHoodieTableCommand
 import org.apache.spark.sql.hudi.common.HoodieSparkSqlTestBase
+import org.apache.spark.sql.hudi.common.HoodieSparkSqlTestBase.getLastCommitMetadata
 import org.apache.spark.sql.types.{ArrayType, BinaryType, DataType, LongType, MapType, MetadataBuilder, StringType, StructField, StructType}
 
+import scala.collection.JavaConverters._
 
 class TestVariantDataType extends HoodieSparkSqlTestBase {
 
@@ -1183,39 +1187,40 @@ class TestVariantDataType extends HoodieSparkSqlTestBase {
            | )
         """.stripMargin)
 
-      spark.sql("set hoodie.parquet.variant.write.shredding.enabled = true")
-      spark.sql("set hoodie.parquet.variant.allow.reading.shredded = true")
-      spark.sql("set hoodie.parquet.variant.force.shredding.schema.for.test = a int, b string")
-
-      spark.sql(
-        s"""
-           |insert into $tableName values
-           |  (1, 'row1', parse_json('{"a": 1, "b": "hello"}'), 1000)
-        """.stripMargin)
-      // Reading shredded variants back via Spark SQL needs Spark 4.1+ (spark.sql.variant.allowReadingShredded,
-      // SPARK-54410); Spark 4.0's native reader rejects the 3-field shredded layout. The shredded write is
-      // still validated below.
-      if (HoodieSparkUtils.gteqSpark4_1) {
-        checkAnswer(s"select id, name, cast(v as string), ts from $tableName order by id")(
-          Seq(1, "row1", "{\"a\":1,\"b\":\"hello\"}", 1000)
-        )
-      }
+      withSQLConf(
+        "hoodie.parquet.variant.write.shredding.enabled" -> "true",
+        "hoodie.parquet.variant.allow.reading.shredded" -> "true",
+        "hoodie.parquet.variant.force.shredding.schema.for.test" -> "a int, b string") {
+        spark.sql(
+          s"""
+             |insert into $tableName values
+             |  (1, 'row1', parse_json('{"a": 1, "b": "hello"}'), 1000)
+          """.stripMargin)
+        // Reading shredded variants back via Spark SQL needs Spark 4.1+ (spark.sql.variant.allowReadingShredded,
+        // SPARK-54410); Spark 4.0's native reader rejects the 3-field shredded layout. The shredded write is
+        // still validated below.
+        if (HoodieSparkUtils.gteqSpark4_1) {
+          checkAnswer(s"select id, name, cast(v as string), ts from $tableName order by id")(
+            Seq(1, "row1", "{\"a\":1,\"b\":\"hello\"}", 1000)
+          )
+        }
 
-      // Verify parquet schema has shredded structure with typed_value
-      val parquetFiles = listDataParquetFiles(tmp.getCanonicalPath)
-      assert(parquetFiles.nonEmpty, "Should have at least one data parquet file")
+        // Verify parquet schema has shredded structure with typed_value
+        val parquetFiles = listDataParquetFiles(tmp.getCanonicalPath)
+        assert(parquetFiles.nonEmpty, "Should have at least one data parquet file")
 
-      parquetFiles.foreach { filePath =>
-        val schema = readParquetSchema(filePath)
-        val variantGroup = getFieldAsGroup(schema, "v")
-        assert(variantGroup.containsField("typed_value"),
-          s"Shredded variant should have typed_value field. Schema:\n$variantGroup")
-        val valueField = variantGroup.getType(variantGroup.getFieldIndex("value"))
-        assert(valueField.getRepetition == Type.Repetition.OPTIONAL,
-          "Shredded variant value field should be OPTIONAL")
-        val metadataField = variantGroup.getType(variantGroup.getFieldIndex("metadata"))
-        assert(metadataField.getRepetition == Type.Repetition.REQUIRED,
-          "Shredded variant metadata field should be REQUIRED")
+        parquetFiles.foreach { filePath =>
+          val schema = readParquetSchema(filePath)
+          val variantGroup = getFieldAsGroup(schema, "v")
+          assert(variantGroup.containsField("typed_value"),
+            s"Shredded variant should have typed_value field. Schema:\n$variantGroup")
+          val valueField = variantGroup.getType(variantGroup.getFieldIndex("value"))
+          assert(valueField.getRepetition == Type.Repetition.OPTIONAL,
+            "Shredded variant value field should be OPTIONAL")
+          val metadataField = variantGroup.getType(variantGroup.getFieldIndex("metadata"))
+          assert(metadataField.getRepetition == Type.Repetition.REQUIRED,
+            "Shredded variant metadata field should be REQUIRED")
+        }
       }
     })
   }
@@ -1241,49 +1246,230 @@ class TestVariantDataType extends HoodieSparkSqlTestBase {
            | )
               """.stripMargin)
 
-      spark.sql(s"set hoodie.parquet.variant.write.shredding.enabled = false")
+      withSQLConf(
+        "hoodie.parquet.variant.write.shredding.enabled" -> "false") {
+        spark.sql(
+          s"""
+             |insert into $tableName values
+             |  (1, 'row1', parse_json('{"a": 1, "b": "hello"}'), 1000)
+                """.stripMargin)
+
+        checkAnswer(s"select id, name, cast(v as string), ts from $tableName order by id")(
+          Seq(1, "row1", "{\"a\":1,\"b\":\"hello\"}", 1000)
+        )
+
+        // Verify parquet schema does NOT have typed_value
+        val parquetFiles = listDataParquetFiles(tmp.getCanonicalPath)
+        assert(parquetFiles.nonEmpty, "Should have at least one data parquet file")
 
+        parquetFiles.foreach { filePath =>
+          val schema = readParquetSchema(filePath)
+          val variantGroup = getFieldAsGroup(schema, "v")
+          assert(!variantGroup.containsField("typed_value"),
+            s"Non-shredded variant should NOT have typed_value field. Schema:\n$variantGroup")
+          val valueField = variantGroup.getType(variantGroup.getFieldIndex("value"))
+          assert(valueField.getRepetition == Type.Repetition.REQUIRED,
+            "Non-shredded variant value field should be REQUIRED")
+        }
+
+        // Verify data can still be read back for the non-shredded case
+        checkAnswer(s"select id, name, cast(v as string), ts from $tableName order by id")(
+          Seq(1, "row1", "{\"a\":1,\"b\":\"hello\"}", 1000)
+        )
+      }
+    })
+  }
+
+  test("Test Auto-Inferred Variant Shredding on COW") {
+    // Inference reuses Spark's InferVariantShreddingSchema (SPARK-53659, Spark 4.1+); without an
+    // inferrer on the classpath, writes silently stay unshredded. Gate on the capability rather
+    // than the Spark version: each spark4.x profile only builds its own version module, so a
+    // profile whose module ships no inferrer (4.0 and older) must skip here rather than fail.
+    assume(VariantShreddingRuntime.lookupInferrer.isPresent,
+      "Variant shredding schema inference requires a VariantShreddingSchemaInferrer on the classpath")
+
+    withRecordType()(withTempDir { tmp =>
+      val tableName = generateTableName
+      spark.sql(
+        s"""
+           |create table $tableName (
+           |  id int,
+           |  v1 variant,
+           |  v2 variant,
+           |  v3 variant,
+           |  ts long
+           |) using hudi
+           | location '${tmp.getCanonicalPath}'
+           | tblproperties (
+           |  primaryKey = 'id',
+           |  type = 'cow',
+           |  preCombineField = 'ts',
+           |  hoodie.parquet.variant.shredding.schema.inference.enabled = 'true'
+           | )
+        """.stripMargin)
+
+      // v1: consistent objects incl. a nested object and an avro-illegal key (dropped from
+      // typed_value, falls back to the residual value column). v2: empty objects (inference
+      // declines empty structs). v3: all null (inference declines). The declines must hold per
+      // ROW, not just across rows: inference is per file and a multi-row insert can fan out to
+      // one file per row, so a cross-row type conflict would not reach a single inference call.
       spark.sql(
         s"""
            |insert into $tableName values
-           |  (1, 'row1', parse_json('{"a": 1, "b": "hello"}'), 1000)
-              """.stripMargin)
+           |  (1, parse_json('{"a": 1, "b": "x", "bad-key": true, "nested": {"c": 5}}'), parse_json('{}'), null, 1000),
+           |  (2, parse_json('{"a": 2, "b": "y", "bad-key": false, "nested": {"c": 6}}'), parse_json('{}'), null, 1000)
+        """.stripMargin)
+      checkAnswer(s"select id, cast(v1 as string), cast(v2 as string), cast(v3 as string), ts from $tableName order by id")(
+        Seq(1, "{\"a\":1,\"b\":\"x\",\"bad-key\":true,\"nested\":{\"c\":5}}", "{}", null, 1000),
+        Seq(2, "{\"a\":2,\"b\":\"y\",\"bad-key\":false,\"nested\":{\"c\":6}}", "{}", null, 1000)
+      )
 
-      checkAnswer(s"select id, name, cast(v as string), ts from $tableName order by id")(
-        Seq(1, "row1", "{\"a\":1,\"b\":\"hello\"}", 1000)
+      def assertInferredFooters(): Unit = {
+        // v1: inferred, with the avro-illegal key dropped from typed_value (it falls back to value).
+        assertInferredTypedValue(tmp.getCanonicalPath, "v1", "cow v1",
+          present = Seq("a", "b", "nested"), absent = Seq("bad-key"))
+        // v2 holds empty objects and v3 is all null: inference declines both, per file.
+        assertVariantLayout(tmp.getCanonicalPath, shredded = false, "cow v2 (declined)", column = "v2")
+        assertVariantLayout(tmp.getCanonicalPath, shredded = false, "cow v3 (declined)", column = "v3")
+      }
+      assertInferredFooters()
+
+      // The update reads the shredded base (reconstruction on the AVRO path, native on SPARK),
+      // re-infers and writes a new shredded base file.
+      spark.sql(s"update $tableName set " +
+        "v1 = parse_json('{\"a\": 9, \"b\": \"z\", \"bad-key\": true, \"nested\": {\"c\": 7}}'), ts = 1001 " +
+        "where id = 1")
+      checkAnswer(s"select id, cast(v1 as string), cast(v2 as string), ts from $tableName order by id")(
+        Seq(1, "{\"a\":9,\"b\":\"z\",\"bad-key\":true,\"nested\":{\"c\":7}}", "{}", 1001),
+        Seq(2, "{\"a\":2,\"b\":\"y\",\"bad-key\":false,\"nested\":{\"c\":6}}", "{}", 1000)
       )
+      assertInferredFooters()
+    })
+  }
 
-      // Verify parquet schema does NOT have typed_value
-      val parquetFiles = listDataParquetFiles(tmp.getCanonicalPath)
-      assert(parquetFiles.nonEmpty, "Should have at least one data parquet file")
+  test("Test Auto-Inferred Variant Shredding via MOR Compaction") {
+    assume(VariantShreddingRuntime.lookupInferrer.isPresent,
+      "Variant shredding schema inference requires a VariantShreddingSchemaInferrer on the classpath")
 
-      parquetFiles.foreach { filePath =>
-        val schema = readParquetSchema(filePath)
-        val variantGroup = getFieldAsGroup(schema, "v")
-        assert(!variantGroup.containsField("typed_value"),
-          s"Non-shredded variant should NOT have typed_value field. Schema:\n$variantGroup")
-        val valueField = variantGroup.getType(variantGroup.getFieldIndex("value"))
-        assert(valueField.getRepetition == Type.Repetition.REQUIRED,
-          "Non-shredded variant value field should be REQUIRED")
-      }
+    withRecordType()(withTempDir { tmp =>
+      val tableName = generateTableName
+      val tablePath = tmp.getCanonicalPath
+      // Inference is per parquet file. On the default table version the log files of this MOR
+      // table are native parquet too (*.log.parquet, written through the same factory), so each
+      // log file infers its own layout; the compaction then writes the base file with its own.
+      spark.sql(
+        s"""
+           |create table $tableName (
+           |  id int,
+           |  v variant,
+           |  ts long
+           |) using hudi
+           | location '$tablePath'
+           | tblproperties (
+           |  primaryKey = 'id',
+           |  type = 'mor',
+           |  preCombineField = 'ts',
+           |  hoodie.parquet.variant.shredding.schema.inference.enabled = 'true',
+           |  hoodie.index.type = 'INMEMORY',
+           |  hoodie.compact.inline = 'true',
+           |  hoodie.compact.inline.max.delta.commits = '3'
+           | )
+       """.stripMargin)
 
-      // Verify data can still be read back for the non-shredded case
-      checkAnswer(s"select id, name, cast(v as string), ts from $tableName order by id")(
-        Seq(1, "row1", "{\"a\":1,\"b\":\"hello\"}", 1000)
+      spark.sql(s"insert into $tableName values " + "(1, parse_json('{\"key\":\"value1\"}'), 1000)")
+      spark.sql(s"insert into $tableName values " + "(2, parse_json('{\"key\":\"value2\"}'), 1000)")
+      assertResult(true)(DataSourceTestUtils.isLogFileOnly(tablePath))
+
+      // 3rd commit triggers inline compaction; the base file is written with inferred shredding.
+      spark.sql(s"insert into $tableName values " + "(3, parse_json('{\"key\":\"value3\"}'), 1000)")
+      assertResult(false)(DataSourceTestUtils.isLogFileOnly(tablePath))
+
+      checkAnswer(s"select id, cast(v as string), ts from $tableName order by id")(
+        Seq(1, "{\"key\":\"value1\"}", 1000),
+        Seq(2, "{\"key\":\"value2\"}", 1000),
+        Seq(3, "{\"key\":\"value3\"}", 1000)
       )
+
+      // Split by file kind so the base-file leg cannot pass on the shredded log files alone. Only
+      // native DATA logs (*.log.parquet) are checked on the log side: delete and CDC logs are
+      // parquet too but carry no variant column.
+      val parquetFiles = listDataParquetFiles(tablePath)
+      val baseFiles = parquetFiles.filter(f => FSUtils.isBaseFile(new HadoopPath(f).getName))
+      val nativeDataLogs = parquetFiles.filter(_.endsWith(".log.parquet"))
+      assert(baseFiles.nonEmpty, "Compaction should have produced a base parquet file")
+      assertInferredTypedValueIn(baseFiles, "v", "mor compacted base", present = Seq("key"))
+      // The default table version (10) writes native parquet log files, which are shredded per
+      // file by the same factory path. Asserted rather than guarded: a table version that wrote
+      // Avro log blocks here would silently turn this leg off.
+      assert(nativeDataLogs.nonEmpty, "table version 10 MOR tables write native parquet log files")
+      assertInferredTypedValueIn(nativeDataLogs, "v", "mor native log", present = Seq("key"))
     })
   }
 
+  test("A shredding-schema inferrer is registered for every Spark version that ships one") {
+    // Spark 4.1+ ships InferVariantShreddingSchema. A Spark version module without a registered
+    // inferrer silently writes unshredded with the flag on and turns every inference test above
+    // into a skip, which is how the spark4.2 module first shipped without one. Deliberately not
+    // gated on the inferrer itself: this is the leg that notices the gap.
+    assertResult(HoodieSparkUtils.gteqSpark4_1)(VariantShreddingRuntime.lookupInferrer.isPresent)
+  }
+
+  test("Test Auto-Inferred Variant Shredding with Bulk Insert Row Writer") {
+    assume(VariantShreddingRuntime.lookupInferrer.isPresent,
+      "Variant shredding schema inference requires a VariantShreddingSchemaInferrer on the classpath")
+
+    // The row-writer path (HoodieInternalRowFileWriterFactory) is record-type independent.
+    withTempDir { tmp =>
+      val tableName = generateTableName
+      withSQLConf("hoodie.spark.sql.insert.into.operation" -> "bulk_insert") {
+        spark.sql(
+          s"""
+             |create table $tableName (
+             |  id int,
+             |  v variant,
+             |  ts long
+             |) using hudi
+             | location '${tmp.getCanonicalPath}'
+             | tblproperties (
+             |  primaryKey = 'id',
+             |  type = 'cow',
+             |  preCombineField = 'ts',
+             |  hoodie.parquet.variant.shredding.schema.inference.enabled = 'true',
+             |  hoodie.datasource.write.row.writer.enable = 'true'
+             | )
+          """.stripMargin)
+
+        spark.sql(
+          s"""
+             |insert into $tableName values
+             |  (1, parse_json('{"a": 1, "b": "x"}'), 1000),
+             |  (2, parse_json('{"a": 2, "b": "y"}'), 1000)
+          """.stripMargin)
+      }
+
+      // Pin the path: the footer would look the same if the insert silently fell back to the
+      // record-based writers, which infer through a different decorator.
+      assertResult(WriteOperationType.BULK_INSERT)(getLastCommitMetadata(spark, tmp.getCanonicalPath).getOperationType)
+      checkAnswer(s"select id, cast(v as string), ts from $tableName order by id")(
+        Seq(1, "{\"a\":1,\"b\":\"x\"}", 1000),
+        Seq(2, "{\"a\":2,\"b\":\"y\"}", 1000)
+      )
+
+      assertInferredTypedValue(tmp.getCanonicalPath, "v", "row writer", present = Seq("a", "b"))
+    }
+  }
+
   /**
-   * Pins the on-disk layout of the `v` column across every base file. Without it a leg meant to
-   * exercise the shredded path can silently degenerate into the unshredded one, or the reverse,
-   * and the branch it was written for goes uncovered.
+   * Pins the on-disk layout of `column` (the single `v` column most tests declare, by default)
+   * across every data parquet file. Without it a leg meant to exercise the shredded path can
+   * silently degenerate into the unshredded one, or the reverse, and the branch it was written
+   * for goes uncovered.
    */
-  private def assertVariantLayout(tablePath: String, shredded: Boolean, leg: String): Unit = {
+  private def assertVariantLayout(tablePath: String, shredded: Boolean, leg: String, column: String = "v"): Unit = {
     val files = listDataParquetFiles(tablePath)
     assert(files.nonEmpty, s"[$leg] should have at least one data parquet file")
     files.foreach { filePath =>
-      val variantGroup = getFieldAsGroup(readParquetSchema(filePath), "v")
+      val variantGroup = getFieldAsGroup(readParquetSchema(filePath), column)
       if (shredded) {
         assert(variantGroup.containsField("typed_value"),
           s"[$leg] base file should carry typed_value. Schema:\n$variantGroup")
@@ -1294,6 +1480,43 @@ class TestVariantDataType extends HoodieSparkSqlTestBase {
     }
   }
 
+  /**
+   * Pins an INFERRED shredding layout of `column` across every data parquet file of the table:
+   * see [[assertInferredTypedValueIn]].
+   */
+  private def assertInferredTypedValue(tablePath: String, column: String, leg: String,
+                                       present: Seq[String], absent: Seq[String] = Seq.empty): Unit = {
+    assertInferredTypedValueIn(listDataParquetFiles(tablePath), column, leg, present, absent)
+  }
+
+  /**
+   * Pins an INFERRED shredding layout of `column` in the given parquet files: the variant group is
+   * shredded, carries the VARIANT logical type (the inferrer only exists on Spark 4.1+, whose
+   * parquet ships the annotation), its typed_value has every `present` member and none of
+   * the `absent` ones (e.g. an avro-illegal key the inferrer dropped), and typed_value holds
+   * non-null values per the block column statistics.
+   */
+  private def assertInferredTypedValueIn(files: Seq[String], column: String, leg: String,
+                                         present: Seq[String], absent: Seq[String] = Seq.empty): Unit = {
+    assert(files.nonEmpty, s"[$leg] should have at least one data parquet file")
+    files.foreach { filePath =>
+      val variantGroup = getFieldAsGroup(readParquetSchema(filePath), column)
+      assert(variantGroup.containsField("typed_value"),
+        s"[$leg] $column should be shredded with an inferred typed_value. File: $filePath Schema:\n$variantGroup")
+      assert(Option(variantGroup.getLogicalTypeAnnotation).exists(_.toString.contains("VARIANT")),
+        s"[$leg] inferred variant group must carry the VARIANT logical type. Schema:\n$variantGroup")
+      val typedValue = getFieldAsGroup(variantGroup, "typed_value")
+      present.foreach(member => assert(typedValue.containsField(member),
+        s"[$leg] inferred typed_value should contain $member. Schema:\n$typedValue"))
+      absent.foreach(member => assert(!typedValue.containsField(member),
+        s"[$leg] inferred typed_value must not contain $member. Schema:\n$typedValue"))
+      // The footer schema alone cannot tell real shredding from a file where every row fell
+      // back to the residual value with typed_value all-null.
+      assert(typedValueNonNullCount(filePath, column) > 0,
+        s"[$leg] inferred typed_value of $column should hold non-null values. File: $filePath")
+    }
+  }
+
   /** Pins that a write bin-packed into the existing file group rather than creating a new one. */
   private def assertSingleFileGroup(tablePath: String, leg: String): Unit = {
     val fileGroupIds = listDataParquetFiles(tablePath)
@@ -1334,6 +1557,34 @@ class TestVariantDataType extends HoodieSparkSqlTestBase {
     }
   }
 
+  /**
+   * Sums the non-null value counts of the typed leaf columns under `column`.typed_value across
+   * all blocks of the file, from the block column statistics. The residual `value` leaves of
+   * shredded object fields are left out: they hold the rows that fell back, so counting them
+   * would let a file with every field fallen back pass as shredded.
+   */
+  private def typedValueNonNullCount(filePath: String, column: String): Long = {
+    val conf = spark.sparkContext.hadoopConfiguration
+    val inputFile = HadoopInputFile.fromPath(new HadoopPath(filePath), conf)
+    val reader = ParquetFileReader.open(inputFile)
+    try {
+      val prefix = s"$column.typed_value"
+      reader.getFooter.getBlocks.asScala.flatMap(_.getColumns.asScala)
+        .filter { c =>
+          val dot = c.getPath.toDotString
+          (dot == prefix || dot.startsWith(prefix + ".")) && !dot.endsWith(".value")
+        }
+        .map { c =>
+          val stats = c.getStatistics
+          // A chunk without a written null count must not pass as holding non-null values
+          if (stats == null || stats.getNumNulls < 0) 0L else c.getValueCount - stats.getNumNulls
+        }
+        .sum
+    } finally {
+      reader.close()
+    }
+  }
+
   /**
    * Gets a named field from a GroupType (MessageType) and returns it as a GroupType.
    * Uses getFieldIndex(String) + getType(int) to avoid Scala overload resolution issues.
diff --git a/hudi-spark-datasource/hudi-spark4-common/src/main/java/org/apache/hudi/variant/Spark4VariantShreddingProvider.java b/hudi-spark-datasource/hudi-spark4-common/src/main/java/org/apache/hudi/variant/Spark4VariantShreddingProvider.java
index efb62c23e101..2c1e5f36df63 100644
--- a/hudi-spark-datasource/hudi-spark4-common/src/main/java/org/apache/hudi/variant/Spark4VariantShreddingProvider.java
+++ b/hudi-spark-datasource/hudi-spark4-common/src/main/java/org/apache/hudi/variant/Spark4VariantShreddingProvider.java
@@ -551,47 +551,52 @@ public class Spark4VariantShreddingProvider implements VariantShreddingProvider
       return toByteArray((ByteBuffer) record.get(fieldNameFor(ordinal)));
     }
 
-    // The scalar getters below read typed_value directly: Spark only invokes them for the scalar
-    // typed_value (ordinal == typedIdx), so resolving via fieldNameFor(ordinal) would be redundant.
-    // isNullAt/getBinary stay on fieldNameFor because they are also called for value/metadata.
+    // The scalar/struct/array getters below ignore `ordinal` and read typed_value directly via
+    // typedValue(): Spark's rebuild() only invokes them for the scalar typed_value (ordinal ==
+    // typedIdx), so dispatching via fieldNameFor(ordinal) would be redundant. isNullAt/getBinary
+    // stay on fieldNameFor because rebuild() also calls them for the value/metadata fields.
+    private Object typedValue() {
+      return record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD);
+    }
+
     @Override public boolean getBoolean(int ordinal) {
-      return (Boolean) record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD);
+      return (Boolean) typedValue();
     }
 
     @Override public byte getByte(int ordinal) {
-      return ((Number) record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD)).byteValue();
+      return ((Number) typedValue()).byteValue();
     }
 
     @Override public short getShort(int ordinal) {
-      return ((Number) record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD)).shortValue();
+      return ((Number) typedValue()).shortValue();
     }
 
     @Override public int getInt(int ordinal) {
-      return ((Number) record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD)).intValue();
+      return ((Number) typedValue()).intValue();
     }
 
     @Override public long getLong(int ordinal) {
-      return ((Number) record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD)).longValue();
+      return ((Number) typedValue()).longValue();
     }
 
     @Override public float getFloat(int ordinal) {
-      return ((Number) record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD)).floatValue();
+      return ((Number) typedValue()).floatValue();
     }
 
     @Override public double getDouble(int ordinal) {
-      return ((Number) record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD)).doubleValue();
+      return ((Number) typedValue()).doubleValue();
     }
 
     @Override public String getString(int ordinal) {
-      return record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD).toString();
+      return typedValue().toString();
     }
 
     @Override public UUID getUuid(int ordinal) {
-      return UUID.fromString(record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD).toString());
+      return UUID.fromString(typedValue().toString());
     }
 
     @Override public BigDecimal getDecimal(int ordinal, int precision, int scale) {
-      Object value = record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD);
+      Object value = typedValue();
       if (value instanceof BigDecimal) {
         return (BigDecimal) value;
       }
@@ -608,11 +613,11 @@ public class Spark4VariantShreddingProvider implements VariantShreddingProvider
 
     @Override public ShreddingUtils.ShreddedRow getStruct(int ordinal, int numFields) {
       // Object shredding: typed_value is a record whose fields are the shredded object fields.
-      return new AvroObjectRow((GenericRecord) record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD), schema);
+      return new AvroObjectRow((GenericRecord) typedValue(), schema);
     }
 
     @Override public ShreddingUtils.ShreddedRow getArray(int ordinal) {
-      return new AvroArrayRow((List<?>) record.get(HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD), schema.arraySchema);
+      return new AvroArrayRow((List<?>) typedValue(), schema.arraySchema);
     }
   }
 
diff --git a/hudi-spark-datasource/hudi-spark4-common/src/main/scala/org/apache/spark/sql/adapter/BaseSpark4Adapter.scala b/hudi-spark-datasource/hudi-spark4-common/src/main/scala/org/apache/spark/sql/adapter/BaseSpark4Adapter.scala
index 1be6bf440a74..fab2f0480dc7 100644
--- a/hudi-spark-datasource/hudi-spark4-common/src/main/scala/org/apache/spark/sql/adapter/BaseSpark4Adapter.scala
+++ b/hudi-spark-datasource/hudi-spark4-common/src/main/scala/org/apache/spark/sql/adapter/BaseSpark4Adapter.scala
@@ -18,6 +18,7 @@
 package org.apache.spark.sql.adapter
 
 import org.apache.hudi.{AvroConversionUtils, DefaultSource, HoodieFileScanRDD, HoodieSchemaConversionUtils}
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer
 import org.apache.hudi.common.schema.HoodieSchema
 import org.apache.hudi.common.table.HoodieTableMetaClient
 import org.apache.hudi.common.util.JsonUtils
@@ -284,8 +285,8 @@ abstract class BaseSpark4Adapter extends SparkAdapter with Logging {
     applyVariantLogicalType(builder).named(fieldName)
   }
 
-  // TODO(#18935) drop-spark4.0: when all remaining 4.x adapters are parquet 1.16+, apply variantType() in this base and delete the no-op default plus the Spark4_1Adapter override.
-  protected def applyVariantLogicalType(builder: Types.GroupBuilder[GroupType]): Types.GroupBuilder[GroupType] = builder
+  // TODO(#18935) drop-spark4.0: when all remaining 4.x adapters are parquet 1.16+, apply variantType() in this base and delete the no-op override plus the Spark4_1Adapter override.
+  override def applyVariantLogicalType(builder: Types.GroupBuilder[GroupType]): Types.GroupBuilder[GroupType] = builder
 
   override def isVariantShreddingStruct(structType: StructType): Boolean = {
     SparkShreddingUtils.isVariantShreddingStruct(structType)
@@ -332,4 +333,14 @@ abstract class BaseSpark4Adapter extends SparkAdapter with Logging {
       writeStruct.accept(shreddedValues)
     }
   }
+
+  override def extractVariantBinary(row: SpecializedGetters, ordinal: Int): VariantShreddingSchemaInferrer.VariantSample = {
+    if (row.isNullAt(ordinal)) {
+      null
+    } else {
+      val variantVal = row.getVariant(ordinal)
+      // Defensive copies: Spark iterators reuse row instances and VariantVal exposes its backing arrays.
+      new VariantShreddingSchemaInferrer.VariantSample(variantVal.getValue.clone(), variantVal.getMetadata.clone())
+    }
+  }
 }
diff --git a/hudi-spark-datasource/hudi-spark4.1.x/src/main/scala/org/apache/hudi/variant/Spark41VariantShreddingSchemaInferrer.scala b/hudi-spark-datasource/hudi-spark4.1.x/src/main/scala/org/apache/hudi/variant/Spark41VariantShreddingSchemaInferrer.scala
new file mode 100644
index 000000000000..d7dd1078631a
--- /dev/null
+++ b/hudi-spark-datasource/hudi-spark4.1.x/src/main/scala/org/apache/hudi/variant/Spark41VariantShreddingSchemaInferrer.scala
@@ -0,0 +1,148 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.hudi.variant
+
+import org.apache.hudi.HoodieSchemaConversionUtils
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer.VariantSample
+import org.apache.hudi.common.schema.HoodieSchema
+
+import org.apache.spark.SparkEnv
+import org.apache.spark.sql.catalyst.InternalRow
+import org.apache.spark.sql.catalyst.expressions.GenericInternalRow
+import org.apache.spark.sql.execution.datasources.parquet.InferVariantShreddingSchema
+import org.apache.spark.sql.internal.SQLConf
+import org.apache.spark.sql.types.{ArrayType, DataType, StructField, StructType, VariantType}
+import org.apache.spark.unsafe.types.VariantVal
+
+import java.{util => ju}
+
+import scala.jdk.CollectionConverters.ListHasAsScala
+
+/**
+ * Infers per-file variant shredding schemas by delegating to Spark 4.1's
+ * [[InferVariantShreddingSchema]] (SPARK-53659), so Hudi inherits Spark's merge and
+ * finalization heuristics verbatim (field-frequency dropping, type widening, width/depth caps).
+ *
+ * Loaded reflectively from hudi-common via classpath detection; lives in the spark4.1 module
+ * because the Spark class does not exist before 4.1.
+ */
+class Spark41VariantShreddingSchemaInferrer extends VariantShreddingSchemaInferrer {
+
+  private val typedValueField = HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD
+  // Avro identifier shape; the Hudi schema the result splices into is Avro-backed.
+  private val avroNamePattern = "[A-Za-z_][A-Za-z0-9_]*".r.pattern
+  // Addressed by key because the SQLConf entries behind them are spark-private.
+  private val shreddingCapKeys = Seq(
+    "spark.sql.variant.shredding.maxSchemaWidth", // SQLConf.VARIANT_SHREDDING_MAX_SCHEMA_WIDTH
+    "spark.sql.variant.shredding.maxSchemaDepth") // SQLConf.VARIANT_SHREDDING_MAX_SCHEMA_DEPTH
+
+  override def inferTypedValueSchemas(columnNames: ju.List[String],
+                                      rowSamples: ju.List[Array[VariantSample]]): ju.Map[String, HoodieSchema] = {
+    val names = columnNames.asScala.toSeq
+    val inputSchema = StructType(names.map(name => StructField(name, VariantType, nullable = true)))
+    val rows: Seq[InternalRow] = rowSamples.asScala.map { row =>
+      val values = new Array[Any](row.length)
+      var i = 0
+      while (i < row.length) {
+        if (row(i) != null) {
+          values(i) = new VariantVal(row(i).getValue, row(i).getMetadata)
+        }
+        i += 1
+      }
+      new GenericInternalRow(values): InternalRow
+    }.toSeq
+
+    // One call covers all variant columns of the file: Spark's max-width budget is global
+    // across the schema, and per-column calls would skew it. Resolve the caps before pinning
+    // them: inside the block `SQLConf.get` is `capConf` itself.
+    val capConf = new SQLConf()
+    shreddingCapKeys.foreach(key => resolveShreddingCap(key).foreach(capConf.setConfString(key, _)))
+    val inferred = SQLConf.withExistingConf(capConf) {
+      new InferVariantShreddingSchema(inputSchema).inferSchema(rows)
+    }
+
+    val result = new ju.HashMap[String, HoodieSchema]()
+    names.zipWithIndex.foreach { case (name, i) =>
+      inferred.fields(i).dataType match {
+        case shredded: StructType =>
+          // A column the inference declined (all null, mixed root types) has no typed_value member.
+          shredded.fields.find(_.name == typedValueField).map(_.dataType)
+            .flatMap(sanitizeTypedValue)
+            .foreach { typedValue =>
+              result.put(name, HoodieSchemaConversionUtils.convertStructTypeToHoodieSchema(
+                typedValue, typedValueField, "hoodie.variant." + name))
+            }
+        case _ => // defensive: updateSchema always substitutes a StructType
+      }
+    }
+    result
+  }
+
+  /**
+   * Resolves a shredding cap override for the [[InferVariantShreddingSchema]] constructor, which
+   * reads it off `SQLConf.get`: an offline compaction task runs outside any SQL execution scope, so
+   * no session conf reached it and the cap silently falls back to Spark's default. The SparkConf
+   * fallback mirrors `HoodieRowParquetWriteSupport#resolveSessionLocalTimeZone`; a missing or
+   * non-int value leaves the key unset, which restores Spark's own default.
+   */
+  private def resolveShreddingCap(key: String): Option[String] = {
+    Option(SQLConf.get.getConfString(key, null))
+      .orElse(Option(SparkEnv.get).flatMap(env => Option(env.conf.get(key, null))))
+      .filter(_.trim.toIntOption.isDefined)
+  }
+
+  /**
+   * Drops object fields whose names are not valid Avro identifiers (arbitrary JSON keys are
+   * legal in a StructType but not in the Avro-backed Hudi schema); dropped fields legally fall
+   * back to the residual value column at write time. Returns None when nothing survives, which
+   * declines typing at that level entirely.
+   */
+  private def sanitizeTypedValue(typedValue: DataType): Option[DataType] = typedValue match {
+    case obj: StructType =>
+      // Object shredding: field names are user JSON keys, each field a {value[, typed_value]} wrapper.
+      val kept = obj.fields.iterator
+        .filter(field => avroNamePattern.matcher(field.name).matches())
+        .map { field =>
+          field.dataType match {
+            case wrapper: StructType => field.copy(dataType = sanitizeWrapper(wrapper))
+            case _ => field
+          }
+        }.toArray
+      if (kept.isEmpty) None else Some(StructType(kept))
+    case ArrayType(wrapper: StructType, containsNull) =>
+      Some(ArrayType(sanitizeWrapper(wrapper), containsNull))
+    case scalar => Some(scalar)
+  }
+
+  /** A wrapper whose typed_value sanitizes to nothing drops it and falls back to value-only. */
+  private def sanitizeWrapper(wrapper: StructType): StructType = {
+    wrapper.fields.find(_.name == typedValueField) match {
+      case Some(innerTypedValue) =>
+        sanitizeTypedValue(innerTypedValue.dataType) match {
+          case Some(clean) if clean eq innerTypedValue.dataType => wrapper
+          case Some(clean) => StructType(wrapper.fields.map(field =>
+            if (field.name == typedValueField) field.copy(dataType = clean) else field))
+          case None => StructType(wrapper.fields.filterNot(_.name == typedValueField))
+        }
+      case None => wrapper
+    }
+  }
+}
diff --git a/hudi-spark-datasource/hudi-spark4.1.x/src/main/scala/org/apache/spark/sql/adapter/Spark4_1Adapter.scala b/hudi-spark-datasource/hudi-spark4.1.x/src/main/scala/org/apache/spark/sql/adapter/Spark4_1Adapter.scala
index e16def5b9373..c445d89f1e69 100644
--- a/hudi-spark-datasource/hudi-spark4.1.x/src/main/scala/org/apache/spark/sql/adapter/Spark4_1Adapter.scala
+++ b/hudi-spark-datasource/hudi-spark4.1.x/src/main/scala/org/apache/spark/sql/adapter/Spark4_1Adapter.scala
@@ -285,7 +285,7 @@ class Spark4_1Adapter extends BaseSpark4Adapter {
 
   // Apply LogicalTypeAnnotation.variantType((byte) 1) to the variant group, matching parquet 1.16+'s
   // SparkToParquetSchemaConverter convention.
-  override protected def applyVariantLogicalType(builder: Types.GroupBuilder[GroupType]): Types.GroupBuilder[GroupType] = {
+  override def applyVariantLogicalType(builder: Types.GroupBuilder[GroupType]): Types.GroupBuilder[GroupType] = {
     builder.as(LogicalTypeAnnotation.variantType(1.toByte))
   }
 
diff --git a/hudi-spark-datasource/hudi-spark4.2.x/src/main/scala/org/apache/hudi/variant/Spark42VariantShreddingSchemaInferrer.scala b/hudi-spark-datasource/hudi-spark4.2.x/src/main/scala/org/apache/hudi/variant/Spark42VariantShreddingSchemaInferrer.scala
new file mode 100644
index 000000000000..20ce83f601ac
--- /dev/null
+++ b/hudi-spark-datasource/hudi-spark4.2.x/src/main/scala/org/apache/hudi/variant/Spark42VariantShreddingSchemaInferrer.scala
@@ -0,0 +1,149 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.hudi.variant
+
+import org.apache.hudi.HoodieSchemaConversionUtils
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer
+import org.apache.hudi.common.avro.VariantShreddingSchemaInferrer.VariantSample
+import org.apache.hudi.common.schema.HoodieSchema
+
+import org.apache.spark.SparkEnv
+import org.apache.spark.sql.catalyst.InternalRow
+import org.apache.spark.sql.catalyst.expressions.GenericInternalRow
+import org.apache.spark.sql.execution.datasources.parquet.InferVariantShreddingSchema
+import org.apache.spark.sql.internal.SQLConf
+import org.apache.spark.sql.types.{ArrayType, DataType, StructField, StructType, VariantType}
+import org.apache.spark.unsafe.types.VariantVal
+
+import java.{util => ju}
+
+import scala.jdk.CollectionConverters.ListHasAsScala
+
+/**
+ * Infers per-file variant shredding schemas by delegating to Spark's
+ * [[InferVariantShreddingSchema]] (SPARK-53659), so Hudi inherits Spark's merge and
+ * finalization heuristics verbatim (field-frequency dropping, type widening, width/depth caps).
+ *
+ * Loaded reflectively from hudi-common via classpath detection; the Spark 4.2 twin of the
+ * spark4.1 module's inferrer (each spark4.x profile builds only its own version module, and the
+ * Spark class does not exist before 4.1).
+ */
+class Spark42VariantShreddingSchemaInferrer extends VariantShreddingSchemaInferrer {
+
+  private val typedValueField = HoodieSchema.Variant.VARIANT_TYPED_VALUE_FIELD
+  // Avro identifier shape; the Hudi schema the result splices into is Avro-backed.
+  private val avroNamePattern = "[A-Za-z_][A-Za-z0-9_]*".r.pattern
+  // Addressed by key because the SQLConf entries behind them are spark-private.
+  private val shreddingCapKeys = Seq(
+    "spark.sql.variant.shredding.maxSchemaWidth", // SQLConf.VARIANT_SHREDDING_MAX_SCHEMA_WIDTH
+    "spark.sql.variant.shredding.maxSchemaDepth") // SQLConf.VARIANT_SHREDDING_MAX_SCHEMA_DEPTH
+
+  override def inferTypedValueSchemas(columnNames: ju.List[String],
+                                      rowSamples: ju.List[Array[VariantSample]]): ju.Map[String, HoodieSchema] = {
+    val names = columnNames.asScala.toSeq
+    val inputSchema = StructType(names.map(name => StructField(name, VariantType, nullable = true)))
+    val rows: Seq[InternalRow] = rowSamples.asScala.map { row =>
+      val values = new Array[Any](row.length)
+      var i = 0
+      while (i < row.length) {
+        if (row(i) != null) {
+          values(i) = new VariantVal(row(i).getValue, row(i).getMetadata)
+        }
+        i += 1
+      }
+      new GenericInternalRow(values): InternalRow
+    }.toSeq
+
+    // One call covers all variant columns of the file: Spark's max-width budget is global
+    // across the schema, and per-column calls would skew it. Resolve the caps before pinning
+    // them: inside the block `SQLConf.get` is `capConf` itself.
+    val capConf = new SQLConf()
+    shreddingCapKeys.foreach(key => resolveShreddingCap(key).foreach(capConf.setConfString(key, _)))
+    val inferred = SQLConf.withExistingConf(capConf) {
+      new InferVariantShreddingSchema(inputSchema).inferSchema(rows)
+    }
+
+    val result = new ju.HashMap[String, HoodieSchema]()
+    names.zipWithIndex.foreach { case (name, i) =>
+      inferred.fields(i).dataType match {
+        case shredded: StructType =>
+          // A column the inference declined (all null, mixed root types) has no typed_value member.
+          shredded.fields.find(_.name == typedValueField).map(_.dataType)
+            .flatMap(sanitizeTypedValue)
+            .foreach { typedValue =>
+              result.put(name, HoodieSchemaConversionUtils.convertStructTypeToHoodieSchema(
+                typedValue, typedValueField, "hoodie.variant." + name))
+            }
+        case _ => // defensive: updateSchema always substitutes a StructType
+      }
+    }
+    result
+  }
+
+  /**
+   * Resolves a shredding cap override for the [[InferVariantShreddingSchema]] constructor, which
+   * reads it off `SQLConf.get`: an offline compaction task runs outside any SQL execution scope, so
+   * no session conf reached it and the cap silently falls back to Spark's default. The SparkConf
+   * fallback mirrors `HoodieRowParquetWriteSupport#resolveSessionLocalTimeZone`; a missing or
+   * non-int value leaves the key unset, which restores Spark's own default.
+   */
+  private def resolveShreddingCap(key: String): Option[String] = {
+    Option(SQLConf.get.getConfString(key, null))
+      .orElse(Option(SparkEnv.get).flatMap(env => Option(env.conf.get(key, null))))
+      .filter(_.trim.toIntOption.isDefined)
+  }
+
+  /**
+   * Drops object fields whose names are not valid Avro identifiers (arbitrary JSON keys are
+   * legal in a StructType but not in the Avro-backed Hudi schema); dropped fields legally fall
+   * back to the residual value column at write time. Returns None when nothing survives, which
+   * declines typing at that level entirely.
+   */
+  private def sanitizeTypedValue(typedValue: DataType): Option[DataType] = typedValue match {
+    case obj: StructType =>
+      // Object shredding: field names are user JSON keys, each field a {value[, typed_value]} wrapper.
+      val kept = obj.fields.iterator
+        .filter(field => avroNamePattern.matcher(field.name).matches())
+        .map { field =>
+          field.dataType match {
+            case wrapper: StructType => field.copy(dataType = sanitizeWrapper(wrapper))
+            case _ => field
+          }
+        }.toArray
+      if (kept.isEmpty) None else Some(StructType(kept))
+    case ArrayType(wrapper: StructType, containsNull) =>
+      Some(ArrayType(sanitizeWrapper(wrapper), containsNull))
+    case scalar => Some(scalar)
+  }
+
+  /** A wrapper whose typed_value sanitizes to nothing drops it and falls back to value-only. */
+  private def sanitizeWrapper(wrapper: StructType): StructType = {
+    wrapper.fields.find(_.name == typedValueField) match {
+      case Some(innerTypedValue) =>
+        sanitizeTypedValue(innerTypedValue.dataType) match {
+          case Some(clean) if clean eq innerTypedValue.dataType => wrapper
+          case Some(clean) => StructType(wrapper.fields.map(field =>
+            if (field.name == typedValueField) field.copy(dataType = clean) else field))
+          case None => StructType(wrapper.fields.filterNot(_.name == typedValueField))
+        }
+      case None => wrapper
+    }
+  }
+}
diff --git a/hudi-spark-datasource/hudi-spark4.2.x/src/main/scala/org/apache/spark/sql/adapter/Spark4_2Adapter.scala b/hudi-spark-datasource/hudi-spark4.2.x/src/main/scala/org/apache/spark/sql/adapter/Spark4_2Adapter.scala
index e971c4d6fc1d..388582c9e963 100644
--- a/hudi-spark-datasource/hudi-spark4.2.x/src/main/scala/org/apache/spark/sql/adapter/Spark4_2Adapter.scala
+++ b/hudi-spark-datasource/hudi-spark4.2.x/src/main/scala/org/apache/spark/sql/adapter/Spark4_2Adapter.scala
@@ -285,7 +285,7 @@ class Spark4_2Adapter extends BaseSpark4Adapter {
 
   // Apply LogicalTypeAnnotation.variantType((byte) 1) to the variant group, matching parquet 1.16+'s
   // SparkToParquetSchemaConverter convention.
-  override protected def applyVariantLogicalType(builder: Types.GroupBuilder[GroupType]): Types.GroupBuilder[GroupType] = {
+  override def applyVariantLogicalType(builder: Types.GroupBuilder[GroupType]): Types.GroupBuilder[GroupType] = {
     builder.as(LogicalTypeAnnotation.variantType(1.toByte))
   }