GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement

[lmeyerov]

Summary

Follow-on child slice for #1046: expose public schema/Arrow boundary APIs for plottable workflows, backed by existing internal IR bridge semantics.

Parent

• Umbrella: [FEA] GFQL native type system: schemas, inference, validation, and Arrow representation #1046
• Depends on: GFQL type system follow-on A: public declarative schema model + stable exports #1337 (public declarative schema model)
• Informed by: GFQL native types T4: Arrow/type bridge contracts and coercion semantics #1312 (internal T4 Arrow bridge)

Goal

Promote schema/Arrow conversion and enforcement to stable public APIs for practical data IO workflows.

In scope

• Public API(s) to convert public schema objects to/from Arrow schema
• Public Plottable boundary hooks for schema enforcement/coercion on Arrow import/export
• Explicit strict/widen coercion semantics and confidence metadata behavior
• Regression tests for round-trip stability and coercion behavior

Out of scope

• Non-Arrow storage backends
• Full inference implementation (tracked separately)

Acceptance

1. Public schema↔Arrow conversion API is stable and documented.
2. Plottable boundary schema enforcement/coercion is test-covered.
3. Strict vs widen modes are deterministic and explicitly documented.
4. Existing behavior is preserved unless explicitly versioned/migration-noted.
5. CHANGELOG/docs include user-facing recipes.

Related

• [FEA] GFQL native type system: schemas, inference, validation, and Arrow representation #1046
• GFQL type system follow-on A: public declarative schema model + stable exports #1337
• GFQL native types T4: Arrow/type bridge contracts and coercion semantics #1312
• Meta: GFQL compiler/planner post-M4 execution DAG (active wave) #1259

[lmeyerov]

Scoping alignment note: lane D #1345 tracks cross-lane API contract alignment in parallel.\n\nThis lane C issue remains independently executable and non-blocked by D; please include compatibility notes needed for D drift checks.

[lmeyerov]

Coordinator schedule note: #1464 now owns the primary community-facing schema tutorial and is intentionally placed after #1338 inference.

For #1339, assume the tutorial baseline will already cover infer/refine/bind/validate. Keep this issue focused on schema↔Arrow APIs and plottable boundary enforcement/coercion; any docs here should extend or link from #1464 rather than becoming the first schema tutorial.

[lmeyerov]

Coordinator schedule update: filed #1465 for sending bound typed GraphSchema through gfql_remote().

For this #1339 lane, please keep an eye on serialization boundaries: #1465 can either consume a stable schema serialization defined here, or define a narrow remote JSON contract itself. Avoid making #1339 implement the whole remote request path unless explicitly retargeted.