GFQL implementation shrink: IR metadata and verifier helper residue

[lmeyerov]

Goal

Shrink existing GFQL IR/metadata/verifier implementation code without changing behavior or colliding with the typed-schema PR.

Target 300-600 LOC of production GFQL implementation deletion/DRY if safely available. Tests/fixtures/changelog do not count toward the headline target; report them separately.

Context

Refs:

• perf: graphistry wheel size (625 kB) — GFQL engine files are large, investigate modularization #1058 cleanup/deletion meta
• GFQL cleanup: add CPU/GPU coverage audit for dead-code candidates #1517 coverage audit infrastructure
• GFQL deletion tranche: planner/IR private helper and fixture dedupe bundle #1542 planner/IR private helper cleanup
• feat(gfql): add public declarative schema model #1457 public declarative schema PR is open and separate
• perf: graphistry wheel size (625 kB) — GFQL engine files are large, investigate modularization #1058 implementation-LOC-first policy update

Planner/IR cleanup removed some private scaffolding under #1542. This lane should audit the remaining existing IR/metadata/verifier implementation for duplication and stale private helpers, while avoiding public typed-schema work and avoiding conflicts with #1457.

Candidate Surface

Start from latest master and audit this ownership area:

• graphistry/compute/gfql/ir/*.py
• graphistry/compute/gfql/ir/metadata.py
• graphistry/compute/gfql/ir/verifier.py
• graphistry/compute/gfql/ir/types.py
• IR tests only as validation/support

Avoid changing public schema API files or behavior being introduced by #1457. If #1457 conflicts, stop and report rather than absorbing typed-schema feature work.

Required Protocol

1. Build an inventory before editing: production symbol/file, callers, coverage signal, and expected implementation LOC deletion.
2. Prioritize production GFQL implementation shrink. Test/comment deletion is secondary and must be reported separately.
3. If implementation deletion opportunity is <300 LOC after a full audit, stop with an audit receipt rather than shipping a mostly-test cleanup PR.
4. Preserve current IR behavior and public APIs.
5. Use GFQL cleanup: add CPU/GPU coverage audit for dead-code candidates #1517 coverage as triage only; require static caller proof and focused validation.

Validation Expectations

• Focused IR/metadata/verifier tests.
• Planner/runtime tests if IR execution behavior is touched.
• Broad non-cuDF GFQL selection if production paths are touched.
• Ruff, typecheck, py_compile, surface guard if applicable, diff check.
• Review protocol before marking ready.

Merge Policy

Open a PR when ready, but do not auto-merge. Coordinator must approve after reviewing production-code deletion, test/support delta, and validation.

[lmeyerov]

#1567 post-#1457 IR/verifier shrink audit receipt

Base audited: origin/master @ 3d85344d083295a05c7619baa1a5e415a8d69b8f (#1457 merge)
Branch: issue-1567-ir-verifier-shrink
Outcome: receipt-only; no PR opened.

Decision

Post-#1457 IR does not expose a safe >=40 production LOC deletion surface in
graphistry/compute/gfql/ir/ outside ir/metadata.py.

The live #1580 inventory remains the controlling precondition: it is an open
protected-seam inventory, not a shrink-target list. Every apparent candidate in
the assigned subtree is either actively referenced, explicitly protected by
#1580, or both.

Evidence by surface

Surface	Audit result
ir/metadata.py	Not audited for deletion; explicitly excluded and canonical post-#1572.
ir/__init__.py	Protected package-level compatibility exports per #1580.
ir/types.py / ir/bound_ir.py	Protected schema/type-system and binder/planner contracts.
ir/logical_plan.py	CHILD_SLOTS, iter_children(), RowSchema, operators, optional arm fields, and ProcedureCall metadata protected by #1580.
ir/compilation.py	GraphSchemaCatalog, PlanContext, CompilerError, PhysicalPlan.route, metadata/context fields protected; #1457 consumes GraphSchemaCatalog.
ir/verifier.py	verify() and structural invariants protected. Private helpers are used by those checks; collapsing them would reduce diagnostic clarity, not safely delete behavior.
ir/arrow_bridge.py	Arrow/schema bridge, coercion modes, confidence metadata, and logical-type serialization protected; downstream #1339 territory.
ir/query_graph.py	Query graph, optional arms, nullable/join alias semantics protected.
ir/capabilities.py	Low-LOC protected pass/planner scheduling extension seam.
ir/pushdown_safety.py	Protected null-safety/WITH-barrier seam; #1565 remains reopened/protected.

Static caller check found no zero-call private IR helper outside its own
definition path. Existing getattr usage is limited to established
CHILD_SLOTS traversal/verifier guards; no new dynamic dispatch was added.

History check:

• chore(gfql): remove IR metadata helper residue #1568 (553bc321) deleted ir/metadata.py and related verifier/type-propagation coverage; fix(gfql): restore IR metadata compatibility seam #1572 reverted/restored that protected seam.
• feat(gfql): add public declarative schema model #1457 (3d85344d083295a05c7619baa1a5e415a8d69b8f) added public schema declarations/tests and did not modify IR implementation files, so it consumes existing IR contracts rather than making them redundant.

Validation

• Focused IR tests:
  python3 -m pytest -q graphistry/tests/compute/gfql/test_ir_verifier.py graphistry/tests/compute/gfql/test_ir_type_propagation.py graphistry/tests/compute/gfql/test_ir_query_graph.py graphistry/tests/compute/gfql/test_ir_compilation.py graphistry/tests/compute/gfql/test_ir_arrow_bridge.py
  → 198 passed in 2.05s
• Ruff focused IR/tests: pass.
• Typecheck focused IR: Success: no issues found in 11 source files.
• git diff --check origin/master...HEAD: pass.
• Review skill: converged after 2 no-finding waves.
• DGX RAPIDS 25.02/26.02: not run; no code PR and no runtime/cuDF path touched.
• Full PR CI: not run; no PR opened.

LOC / Surface

• Production code: +0 / -0, net 0.
• Tests/fixtures/baselines: +0 / -0, net 0.
• Comments/docs/changelog: +0 / -0, net 0.
• Compiler-plan surface touched: no.
• Typed-schema surface touched: no; feat(gfql): add public declarative schema model #1457 GraphSchemaCatalog and IR bridge seams preserved.

Recommendation

Keep #1567 paused/receipt-only unless the coordinator supplies a narrower
shrink-eligible target outside #1580 protected seams. The next high-leverage
typed-schema cluster work is downstream schema work, especially #1339
schema-Arrow boundary enforcement prep/implementation, not IR deletion.

[lmeyerov]

#1580 precondition update for #1567: #1631

The IR seam inventory is now in PR #1631 as graphistry/compute/gfql/ir/SEAM_INVENTORY.md, rebased on current origin/master after #1457 and follow-on shrink PRs through #1628.

Recommendation from the inventory:

• GFQL implementation shrink: IR metadata and verifier helper residue #1567 may resume only as a guarded narrow audit/shrink lane after coordinator acceptance.
• Avoid deleting, moving, or narrowing metadata helpers/re-exports restored by fix(gfql): restore IR metadata compatibility seam #1572, typed-schema/Arrow/schema catalog surfaces from feat(gfql): add public declarative schema model #1457/GFQL type system follow-on A: public declarative schema model + stable exports #1337, package-level compatibility exports, logical/physical planning contracts, query graph/pushdown safety contracts, and verifier invariants.
• Treat anything classified unknown-investigate as protected until a fresh caller/test audit proves otherwise.

Validation on #1631:

• review skill converged after rebase
• symbol coverage check passed
• full PR CI green

[lmeyerov]

Follow-up after final rebase/CI loop: PR #1631 is now based on origin/master 79a61f9ab7d3efa4984007c0ae30660adbd6df4e (#1630) with head 08b0261e.

The inventory document was updated to that base. Full PR CI is green, including Read the Docs.