GFQL Cypher TCK Conformance Harness

This repo hosts the Cypher TCK -> GFQL translation harness used by PyGraphistry. It relies on an installed pygraphistry package to execute GFQL queries and validate results.

Layout

• tests/cypher_tck/: Scenario translations, runner, and gap analysis.
• docs/conformance-ownership-map.md: Ownership boundary with PyGraphistry and shared conformance artifact contracts.
• docs/capability-debt-manifest-schema.md: Public schema for scenario-level capability/debt metadata and validation drift checks.
• docs/conformance-profile-handoff-template.md: Coordinator-facing template for cross-repo conformance lanes.
• TCK clone (gitignored): plans/cypher-tck-conformance/tck.
• Cross-repo coordination guide: SYNC.md.

Links

• PyGraphistry repo: graphistry/pygraphistry
• GFQL docs: pygraphistry.readthedocs.io
• openCypher TCK: opencypher/openCypher
• Contributing: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security: SECURITY.md

Setup

1. Install or editable-link pygraphistry:

   uv pip install --python "$(command -v python)" networkx -e /path/to/pygraphistry

2. Clone the openCypher TCK locally (gitignored):

   mkdir -p plans/cypher-tck-conformance
   git clone https://github.com/opencypher/openCypher plans/cypher-tck-conformance/tck

Run

./bin/ci.sh
python3 -m pytest tests/cypher_tck -xvs
TEST_CUDF=1 python3 -m pytest tests/cypher_tck -xvs

./bin/ci.sh checks that the imported graphistry.compute package exposes the GFQL row-pipeline API and row expression parser backend required by this harness before pytest collection starts.

Local pygraphistry override

Use a sibling checkout and install its dependencies in editable mode:

PYGRAPHISTRY_INSTALL=1 PYGRAPHISTRY_PATH=../pygraphistry ./bin/ci.sh

PYGRAPHISTRY_PATH without PYGRAPHISTRY_INSTALL=1 only prepends source to PYTHONPATH; that is useful for quick import checks, but strict GFQL row expression tests also need pygraphistry's parser dependency installed.

Install a specific ref from GitHub:

PYGRAPHISTRY_INSTALL=1 PYGRAPHISTRY_REF=master ./bin/ci.sh

Dependency freshness policy:

• Non-graphistry dependencies should use a 6-day cooldown (UV_EXCLUDE_NEWER="6 days").
• graphistry/pygraphistry is first-party and may be installed same-day.

License

This repository is licensed under the Apache License 2.0. See LICENSE and NOTICE for details and upstream attribution.

Per-route conformance ledger

bin/routes-off.sh replays the TCK once per pygraphistry hot path with that path declined (GFQL_ROUTES_OFF, pygraphistry's test-side route switch) and diffs each run against the baseline (tests/cypher_tck/route_ledger.py): scenarios the route was masking (pass at baseline, fail with it off) and scenarios only the route answers (fail or expected-fail at baseline, pass with it off). It is a ledger, not a gate: it always exits 0. Modes: MODES="native-fast cypher-fast" OUT=build/routes-off ./bin/routes-off.sh.

Native Polars candidate validation

Set TEST_POLARS=1 to check native Polars results against the TCK expectations. An unavailable or broken Polars installation fails validation when this flag is set.

python bin/polars_candidate.py --product /path/to/pygraphistry --mode normal
python bin/polars_candidate.py --product /path/to/pygraphistry --mode all-off

The runner requires installed product dependencies, verifies imports come from the selected checkout, and sets TEST_POLARS=1. The second command disables every route in that checkout's route registry; newly registered routes are included automatically. Both commands must pass for the release candidate. The Polars candidate conformance Actions workflow runs both for an explicitly selected published PyGraphistry ref. Native operations that raise NotImplementedError remain reported declines; this does not establish support for those operations. The ordinary pandas CI run does not replace these Polars checks.