GFQL native types T5: adoption gates, strict/permissive rollout, and CI/docs receipts

[lmeyerov]

Summary

Execution slice T5 under #1262 / #1046.

Finalize adoption/rollout controls for native typing: strict/permissive toggles, CI coverage gates, and documentation receipts for operational rollout.

Scope

In scope:

• Define strict/permissive mode toggles and default behaviors
• Add CI gates ensuring typed-path coverage and non-regression checks
• Publish docs/migration notes for enabling strict mode safely

Out of scope:

• New type inference mechanics beyond established T1-T4 contracts
• Large unrelated refactors

Acceptance

1. Strict/permissive controls are wired and tested.
2. CI explicitly exercises both rollout modes where relevant.
3. Docs/migration notes are published with clear operator guidance.
4. Meta: #1046 native type-system staged decomposition program #1262 close criteria are satisfied and link back to [FEA] GFQL native type system: schemas, inference, validation, and Arrow representation #1046.

Related

• Parent: Meta: #1046 native type-system staged decomposition program #1262
• Umbrella: [FEA] GFQL native type system: schemas, inference, validation, and Arrow representation #1046
• Depends on: GFQL native types T4: Arrow/type bridge contracts and coercion semantics #1312 (T4)
• Complements: GFQL/Cypher: expose validate-only API (compile/bind checks without execution) #1320 (validate-only API)
• DAG: Meta: GFQL compiler/planner post-M4 execution DAG (active wave) #1259

[lmeyerov]

Dependency update: #1320 (T5.a validate-only API) landed via #1321, so this rollout lane can focus on remaining T4/T5 adoption gates.

[lmeyerov]

T5 closed via #1316 (merged 2026-05-06, master 256da5412c57b7017a29a30a533feb4e005c0526).

Acceptance receipt

1. Strict/permissive controls wired and tested — Added graphistry/compute/gfql/rollout.py with STRICT_SCHEMA_ENV, env_bool, strict_schema_env_default, resolve_strict_schema. Wired into binder._strict_schema_mode. Precedence on the execution compile path: explicit caller param > catalog metadata["strict"] > env > loose. 51 tests across helper + binder seam.
2. CI exercises both rollout modes — folded into existing test-gfql-core and test-pandas-compat-gfql lanes: default-loose path runs with the matrix's main pytest invocation; env-on canary path runs as a follow-on GRAPHISTRY_GFQL_STRICT_SCHEMA=true step in the same job.
3. Docs published — docs/source/gfql/strict_mode.rst (added to user-guide toctree) leads with GFQL/Cypher: expose validate-only API (compile/bind checks without execution) #1320/GFQL/Cypher: add validate-only gfql preflight API #1321's explicit preflight API as the primary operator entrypoint and frames the env-gate as the execution-path canary for staged rollout.

Scope clarification

T5 is complementary to the explicit preflight surface added in #1320/#1321 (g.gfql_validate(strict=True), g.gfql(..., validate=True)) which hardcode strict at preflight regardless of env. T5's env-gate exclusively governs the execution compile path's binder default — i.e., what g.gfql(query) does when the caller doesn't opt into explicit preflight. The two surfaces are independent on purpose: explicit preflight for predictable per-call diagnostics, environment ladder for organization-wide canary rollout.

Meta-issue #1262 close criteria are now satisfied — T1 (#1296), T2 (#1302), T3 (#1300), T3.b (#1309), T4 (#1313), T5 (#1311) all landed.