T5 #1311: GFQL strict-schema rollout gate, CI receipt, operator docs

[lmeyerov]

Summary

Adds an env-driven canary rollout gate over the existing T2 binder strict-mode resolver, operator-guidance docs, and CI receipts (folded into existing GFQL lanes). Strictly additive — default loose mode behavior is unchanged.

Issue: #1311 (T5 under #1262, umbrella #1046).

Scope (post-#1320/#1321 reframing)

Master now has the explicit preflight surface from #1320/#1321:
g.gfql_validate(query, strict=True) and g.gfql(..., validate=True). That is the primary operator entrypoint for explicit, predictable strict-mode invocation, and it hardcodes strict=True at preflight regardless of T5's env.

T5 ships a complementary surface: a canary rollout gate for the execution compile path's binder default. When a caller uses g.gfql(query) without explicit preflight, the binder strictness comes from a three-tier precedence ladder (explicit binder param > catalog metadata > env > loose). T5 adds the env tier so org-wide rollout can flip the default for non-validate-flagged execution.

The two surfaces are independent on purpose:

• Explicit preflight (GFQL/Cypher: expose validate-only API (compile/bind checks without execution) #1320/GFQL/Cypher: add validate-only gfql preflight API #1321) — predictable per-call diagnostics, not env-driven.
• Execution-path rollout gate (this PR) — env-driven default for non-validate-flagged execution; canary for staged adoption.

What's in the diff

New — graphistry/compute/gfql/rollout.py (78 LOC). Stable contract surface re-exported from graphistry.compute.gfql:

• STRICT_SCHEMA_ENV = "GRAPHISTRY_GFQL_STRICT_SCHEMA" — public env-var name
• env_bool(name, default=False) — local env-bool helper (truthy {1,true,yes,on}, falsy {0,false,no,off}, unrecognized → default)
• strict_schema_env_default() — reads the env var, default off
• resolve_strict_schema(*, explicit, catalog_strict) — central monotonic resolver

Modified — graphistry/compute/gfql/frontends/cypher/binder.py. _strict_schema_mode(state) delegates to resolve_strict_schema(...). Precedence ladder is now: explicit caller param True > catalog metadata["strict"]=True > env GRAPHISTRY_GFQL_STRICT_SCHEMA=true > loose. An explicit False is "no preference" (does not force loose), preserving monotonic semantics.

Modified — graphistry/compute/gfql/__init__.py. Re-exports the four rollout symbols and adds them to __all__.

New — graphistry/tests/compute/gfql/test_rollout.py (39 tests):

• TestEnvBool (8) — env-var truth set + whitespace/case behavior
• TestStrictSchemaEnvDefault (4) — pinned env-var name + on/off/unset behavior
• TestResolveStrictSchema (15) — full precedence matrix + parametrized truthy/falsy values
• TestPackageSurface (1) — re-export contract pinned

New — graphistry/tests/compute/gfql/test_rollout_binder_integration.py (12 tests):

• TestBinderEnvGateOff — env unset / false preserves loose mode
• TestBinderEnvGateOn — env=true|1|yes|on|TRUE rejects unknown labels with GFQLValidationError
• TestBinderPrecedence — explicit param + catalog flag still win regardless of env state; valid queries continue to pass under env=strict

Modified — .github/workflows/ci.yml. Folded the rollout test files into the existing test-gfql-core and test-pandas-compat-gfql lanes (default-loose path runs with the main pytest invocation), with a follow-on GRAPHISTRY_GFQL_STRICT_SCHEMA=true step in each job exercising the env-on canary. No new standalone CI job.

New — docs/source/gfql/strict_mode.rst (added to the user-guide toctree). Operator-guidance reference: leads with the #1320 preflight API as the primary entrypoint, then documents the rollout gate's env / catalog / param precedence ladder for staged adoption. Cross-links to validation/fundamentals.rst and cypher.rst (where #1321 added preflight docs).

Modified — CHANGELOG.md (+1 LOC). Internal entry under [Development] / #1262 / T5.

Acceptance (per #1311)

1. Strict/permissive controls wired and tested — env-driven canary tier added on top of the existing T2 binder strict mode; resolver pinned by 51 tests across helper + binder seam.
2. CI explicitly exercises both rollout modes — test-gfql-core and test-pandas-compat-gfql each run the rollout slice with env unset (default-loose) and =true (canary on).
3. Docs/migration notes published with operator guidance — docs/source/gfql/strict_mode.rst ships the rollout sequence + precedence reference, leading with the GFQL/Cypher: expose validate-only API (compile/bind checks without execution) #1320 explicit preflight surface.
4. Meta: #1046 native type-system staged decomposition program #1262 close criteria satisfied — with T3.b (GFQL native types T3.b: migrate inline nullable patterns onto ir.metadata helpers #1309), T4 (GFQL native types T4: Arrow/type bridge contracts #1313), and this T5 PR, the meta lane is complete; meta-issue close after this PR merges.

Test plan

• pytest -q graphistry/tests/compute/gfql/test_rollout.py — 39 passed
• pytest -q graphistry/tests/compute/gfql/test_rollout_binder_integration.py — 12 passed
• pytest -q graphistry/tests/compute/gfql/cypher/test_binder.py — no regression on T2 strict-mode tests
• pytest -q graphistry/tests/compute/gfql/ — full GFQL suite green (post-rebase)
• ./bin/lint.sh (ruff on Python files) clean
• ./bin/typecheck.sh (mypy 1.20.2) clean
• mypy --strict --follow-imports=skip on IR + binder — clean
• CI green on rebased HEAD

🤖 Generated with Claude Code

[lmeyerov]

smell