feat(c): build a catalog-free Table from a resolved schema JSON

[JunRuiLee]

Purpose

Add a catalog-free way to build a read-only-oriented Table from an already-resolved Paimon TableSchema, so a non-Java engine (e.g. Doris FE/BE via the C FFI) can rebuild a table for scan/read without a catalog lookup.

Today the only way to obtain a Table is Catalog::get_table, which re-resolves the table — risking schema/snapshot drift versus what the planner (the FE) already resolved — and ties the reader to a filesystem-catalog layout.

An earlier iteration proposed a dedicated TableDescriptor abstraction on the Java side to bundle path/schema/branch. The community felt it lacked sufficient motivation: it would re-define Paimon table metadata on the Java side and couple the paimon-rust interface to Doris integration details. That approach is dropped in favor of this generic, catalog-free entry point.

Design

The caller (Doris FE) passes everything a reader needs directly:

• table_path — the table location
• table_schema_json — the full TableSchema JSON, already resolved by the FE (parsed with the existing serde TableSchema shape; preserved as-is, not re-loaded, normalized, or overridden)
• database / table_name — used to synthesize the table Identifier
• branch — selects the branch-scoped managers (schema/snapshot/tag read paths); nullable, defaults to main
• storage_options — used only to build FileIO; they are not merged into the supplied schema

The Rust side constructs the Table directly: no Catalog, no warehouse derivation, and no re-resolution of the FE-provided schema. branch only decides which branch's schema/snapshot/tag paths reads follow; reads can still use FE-generated splits (paimon_plan_from_split_bytes), and Rust-side time travel remains available through the existing read-builder options.

Aligning with Java FileStoreTableFactory.create(fileIO, path, schema) (which uses CatalogEnvironment.empty()), the constructed table is a normal table — not made artificially read-only — and the existing non-main-branch / time-travel write guards still apply.

Brief change log

• crates/paimon/src/table/mod.rs: Table::from_resolved_schema(file_io, identifier, location, schema, branch) — preserves the supplied schema as-is, validates the identifier and branch name, validates the schema's structural invariants, wires a branch-scoped SchemaManager, sets rest_env = None and no time travel.
• crates/paimon/src/spec/schema.rs: TableSchema::validate_resolved_structure() — a non-mutating structural check for externally supplied schema JSON: duplicate field names, duplicate field ids (incl. nested), primary-key/partition column existence, primary keys not being exactly the partition columns (which would panic the read path on a zero-column key), and reserved system field names/ids (e.g. a user _ROW_ID column would otherwise be silently replaced by the system row number). It intentionally does not run create-time policy checks (merge-engine/changelog/aggregation/rowkind/blob strategy), which normalize the schema or reject shapes that are valid to read.
• bindings/c/src/table.rs: C FFI paimon_table_from_schema_json(table_path, table_schema_json, database, table_name, branch, storage_options, storage_options_len), mirroring the existing paimon_catalog_get_table handle/free contract, with an ABI signature guard. branch may be null (defaults to main); a non-null pointer is still fully UTF-8 and branch-name validated. Freed via paimon_table_free.
• Read/vector/write builder safety docs note that a handle from paimon_table_from_schema_json is also a valid source.
• Historical per-file schemas are still read from the immutable on-disk schema/schema-N by SchemaManager; the resolved schema pins the planned/current schema only.

Tests

• paimon-c FFI tests: build a table from a resolved schema; null-branch defaults to main; invalid branch name (../dev) rejected; malformed JSON rejected; null-pointer / null storage_options with non-zero length rejected; invalid identifier rejected; missing primary-key column rejected.
• paimon unit tests for validate_resolved_structure: accepts a valid schema; rejects missing primary-key column, missing partition column, duplicate field names, and duplicate field ids.

Not in this PR (known, pre-existing scan-planning limitations, independent of this entry point)

These are not introduced by this change and are unreachable through the read path Doris uses (paimon_plan_from_split_bytes reading FE-generated splits):

• IncrementalScan builds a root (main-branch) SnapshotManager, so incremental scans of a non-main branch would read the main branch's snapshots (Rust-side scan planning only).
• Time-travel selectors embedded directly in the schema JSON options are not honored by the plain read builder (only options passed to the read-builder call are).
• A stale path option embedded in the schema JSON is preferred by FormatTableScan over the table location (Rust-side format scan planning only; normal-table reads use the table location and are unaffected).
• A non-existent bucket-key is silently dropped and all data is written to bucket 0 — a write-path concern only; this entry point is for reading.
• Full Java-parity SchemaValidation (option-combination policy checks) is not mirrored; only the structural invariants above are enforced.

API and Format

• New public API: paimon::table::Table::from_resolved_schema, and C FFI paimon_table_from_schema_json (additive; existing symbols unchanged).
• No new on-disk or wire format, and no new cross-language DTO. Consumes the existing serde TableSchema JSON.

Documentation

None yet (new, evolving C FFI surface for the Doris integration); docs can follow once the integration stabilizes.