feature - implement RFC 026 variant values (#52)

[dannymeijer]

Summary

This PR implements RFC 026 semi-structured variant logical values as the third remaining RFC013 slice. It adds typed VariantExpr / VariantLogicalType metadata, variant parse/path/inspection helpers, registry policy metadata, Substrait extension anchors/options, public docs, and a DataFusion backend capability diagnostic for variant execution until that adapter has a native variant runtime.

The PR is now based on current main after RFC025 / PR #55 merged. The variant helper surface reflects the typed ValueOrColumn API style from the preceding scalar work: parse helpers accept StrValueOrColumn, variant_get accepts literal or dynamic string paths through StrValueOrColumn, variant_value accepts ScalarValueOrColumn, typeof(...) returns StringColumnExpr, and variant predicates such as is_array(...) return BoolColumnExpr.

Type of change

• Bug fix
• New feature
• Refactor / maintenance
• Documentation
• CI / tooling
• RFC (adds/updates docs/rfcs/*)

Area(s)

Select the primary areas touched (labels sync from checked lines when the triage workflow runs):

• Package & tests
• Specification (RFCs)
• Documentation
• Automation & repo config
• Other

Key details

• User-facing behavior: Authors can model semi-structured values with parse_variant_json, try_parse_variant_json, variant_get, typeof, and variant predicates such as is_object / is_null_value without treating payloads as ordinary JSON strings.
• Typed surfaces: parse_variant_json(...) and try_parse_variant_json(...) take StrValueOrColumn; variant_get(...) takes a typed variant plus a literal or dynamic StrValueOrColumn path; variant_value(...) takes ScalarValueOrColumn; typeof(...) returns StringColumnExpr; variant kind predicates return BoolColumnExpr.
• Internals: Variant semantics are captured in InQL registry metadata and Substrait function options. VariantKind.Any is a runtime-discovered kind and is compatible with concrete variant kinds when encodings match. DataFusion rejection is kept in the backend adapter as a capability diagnostic, not encoded as normal Substrait state.
• Risks: The variant helper surface is new and backend execution is intentionally gated until a backend adapter implements variant runtime behavior.

Testing / verification

• make ci (or make fmt-check, make build, make test)
• Manual verification described below

Manual verification notes:

• make fmt INCAN=/Users/danny/Development/encero/incan/target/debug/incan
• /Users/danny/Development/encero/incan/target/debug/incan test tests/test_variant_functions.incn — 5 passed
• /Users/danny/Development/encero/incan/target/debug/incan test tests/test_function_registry.incn — 21 passed
• /Users/danny/Development/encero/incan/target/debug/incan test tests/test_substrait_plan.incn — 54 passed
• /Users/danny/Development/encero/incan/target/debug/incan test tests/test_session_projection.incn — 18 passed
• make fmt-check INCAN=/Users/danny/Development/encero/incan/target/debug/incan
• make test-style INCAN=/Users/danny/Development/encero/incan/target/debug/incan
• make registry-metadata INCAN=/Users/danny/Development/encero/incan/target/debug/incan — 216 helpers
• make build INCAN=/Users/danny/Development/encero/incan/target/debug/incan
• make test INCAN=/Users/danny/Development/encero/incan/target/debug/incan — 238 passed
• make smoke-consumer INCAN=/Users/danny/Development/encero/incan/target/debug/incan — sandboxed run failed on crates.io DNS; rerun with network escalation passed
• git diff --check

Docs impact

• No docs changes needed
• Docs updated
• Docs follow Divio intent (tutorial/how-to/reference/explanation) where applicable

If docs updated:

• Link(s): docs/language/reference/functions/variants.md, docs/language/reference/functions/index.md, docs/language/reference/functions/format.md, docs/rfcs/026_semi_structured_variant_values.md, docs/rfcs/README.md, docs/release_notes/v0_1.md

Checklist

• I kept public docs user-focused and moved internals to contributing docs when appropriate
• I avoided duplicating canonical install/run instructions in multiple places
• I added/updated tests where it materially reduces regressions

Closes #52