GFQL remote: send bound typed GraphSchema with gfql_remote requests

[lmeyerov]

Summary

Add remote transport for the typed graph schema introduced by the GFQL schema/type-system work. A graph with a bound public GraphSchema should be able to call gfql_remote() and send the schema contract to the server-side GFQL executor instead of using schema metadata only for local preflight.

Schedule

This is not part of the immediate #1457 merge gate. Run after the local schema contract is stable and serializable:

1. feat(gfql): add public declarative schema model #1457 / GFQL type system follow-on A: public declarative schema model + stable exports #1337 lands public GraphSchema binding and local validation.
2. GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339 defines stable schema serialization / Arrow-plottable boundary semantics, or this issue explicitly defines the remote JSON contract as a narrow subset.
3. Then this issue wires schema transport through gfql_remote() / gfql_remote_shape().

It does not need to wait for #1338 inference, but the tutorial #1464 should mention remote schema support only after this lane lands.

Scope

• Define a stable serialized schema payload for remote GFQL requests.
• Include bound GraphSchema metadata from g.bind(schema=schema) in gfql_remote() request envelopes.
• Preserve current behavior when no schema is bound.
• Decide whether strict/permissive mode is sent as schema metadata, request option, or both.
• Ensure server/backward compatibility: old servers should ignore or reject with a clear capability error rather than silently misinterpreting the request.
• Add request-shape tests for chain/DAG/Cypher string gfql_remote() paths as applicable.
• Add docs note linking local gfql_validate() and remote execution behavior.

Out of scope

• Implementing local schema declaration; GFQL type system follow-on A: public declarative schema model + stable exports #1337 / feat(gfql): add public declarative schema model #1457.
• Implementing schema inference; GFQL type system follow-on B: schema inference API + typed topology extraction #1338.
• Broad Arrow/plottable boundary enforcement unless needed for the remote payload contract; GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339.
• Server-side implementation outside pygraphistry unless separately tracked.

Acceptance

• Bound typed schema appears in the remote GFQL payload in a stable documented form.
• No-schema remote requests preserve current payloads/behavior.
• Tests cover at least one remote chain or Cypher request with schema metadata and one no-schema request.
• Compatibility behavior for older/unsupported server surfaces is documented or guarded.
• [FEA] GFQL native type system: schemas, inference, validation, and Arrow representation #1046/GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339/GFQL schema tutorial: infer, refine, bind, and validate Cypher #1464 are updated with schedule/links.

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 type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339
• GFQL schema tutorial: infer, refine, bind, and validate Cypher #1464
• Guarantee _url_params propagation through gfql_remote(persist=True) server roundtrip #1251

[lmeyerov]

Coordinator research follow-up note for #1465:

Remote schema transport should wait until the local contract is stable and serializable, but the recommended payload direction is now:

• JSON schema payload first for capability negotiation, debuggability, and old-server behavior.
• Optional Arrow IPC payload later/alongside after GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339 settles exact conversion/coercion.
• Preserve strict / permissive policy explicitly in the payload or request envelope.
• Old servers should ignore safely or return a clear capability error; they must not silently misinterpret schema metadata.

The payload should align with the design direction:

• Cypher labels are predicates.
• NodeType / EdgeType are trait-like contracts.
• First-class graph values should eventually carry Graph[SchemaSnapshot] plus deltas, especially for GRAPH { ... } and graph-growing calls.

This issue does not need to wait for #1338 inference, but the user-facing tutorial #1464 should mention remote schema behavior only after this lane lands.