IR seam inventory: surfaces protected from #1567 (IR/verifier) future reassignment

[lmeyerov]

Parent/meta: #1058
Corrective restoration reference: #1572
Paused lane reference: #1567

This issue is a coordinator-facing precondition for any future reassignment of #1567 (IR/verifier). It records the protected IR seams that should not be removed or refactored as deletion/shrink work without an explicit migration plan and replacement tests.

Context:

• chore(gfql): remove IR metadata helper residue #1568 accidentally deleted graphistry/compute/gfql/ir/metadata.py, a protected schema/type-system hook.
• fix(gfql): restore IR metadata compatibility seam #1572 restored the metadata module, IR package re-exports, and contract tests.
• Follow-up audit found no additional chore(gfql): remove IR metadata helper residue #1568 collateral protected-surface deletion beyond the intentional .nullable simplifications kept by fix(gfql): restore IR metadata compatibility seam #1572.

Do-not-touch seam inventory:

• graphistry/compute/gfql/ir/metadata.py: stable type/nullability metadata compatibility seam. Preserve is_nullable, with_nullable, widen_to_nullable, column_logical_type, column_is_nullable, merge_types, bound_variable_type, bound_variable_is_nullable.
• graphistry/compute/gfql/ir/__init__.py: package-level re-exports are compatibility surface. Do not remove IR metadata exports or core IR dataclass exports without a coordinated migration.
• graphistry/compute/gfql/ir/types.py: logical type dataclasses (ScalarType, NodeRef, EdgeRef, PathType, ListType, BoundPredicate, PatternGraph) are schema/type-system contracts.
• graphistry/compute/gfql/ir/bound_ir.py: BoundVariable.nullable, null_extended_from, entity_kind, ScopeFrame.schema, and BoundIR.scope_stack are binder-to-planner contracts.
• graphistry/compute/gfql/ir/logical_plan.py: CHILD_SLOTS, iter_children(), RowSchema, operator dataclasses, optional arm fields, and ProcedureCall output metadata are pass/verifier/physical-planner contracts.
• graphistry/compute/gfql/ir/compilation.py: GraphSchemaCatalog, PlanContext, CompilerError, PhysicalPlan.route, PhysicalPlan.metadata, and scope/catalog/index/backend/config fields are planning and route-selection contracts.
• graphistry/compute/gfql/ir/verifier.py: verify() and its structural invariants are verifier extension points and safety gates. Keep optional-arm/nullability/type-continuity checks unless a replacement proof lands first.
• graphistry/compute/gfql/ir/arrow_bridge.py: Arrow/schema bridge, coercion modes, confidence metadata, and logical type serialization are typed-schema / Arrow-boundary surfaces.
• graphistry/compute/gfql/ir/query_graph.py: QueryGraph, ConnectedComponent, OptionalArm, and extract_query_graph() are join-ordering / optional-arm scaffolding. Preserve nullable/join alias semantics.
• graphistry/compute/gfql/ir/capabilities.py: capability flags are pass/planner scheduling contracts.
• graphistry/compute/gfql/ir/pushdown_safety.py: null-rejecting/null-safe predicate classification and WITH-barrier checks are protected pass-manager/predicate-pushdown safety seams. GFQL implementation shrink: pass manager and pushdown residue #1565 remains reopened/protected; do not assign deletion work here.

Acceptance for future #1567 reassignment:

• Treat this inventory as protected scope.
• Any proposed IR/verifier cleanup must classify each touched surface against this list.
• If a protected seam must move, require an explicit compatibility migration, replacement exports where applicable, and tests proving the old and new contracts.
• Do not touch typed-schema PR feat(gfql): add public declarative schema model #1457 / GFQL type system follow-on A: public declarative schema model + stable exports #1337 territory unless the coordinator explicitly assigns that work.

[lmeyerov]

Created from the clean #1568/#1572 collateral audit posted on #1058:
#1058 (comment)

This issue is the coordinator-facing IR seam inventory/precondition for any future #1567 reassignment.

[lmeyerov]

#1580 inventory PR is ready: #1631

Delivered graphistry/compute/gfql/ir/SEAM_INVENTORY.md against current origin/master (9b4a2727c2df9d58be1867f5462ebba2620f5356) after #1457 and follow-on shrink PRs through #1628.

Coverage:

• every current public + private symbol in graphistry/compute/gfql/ir/
• protection status per symbol: typed-schema-seam, IR-metadata-seam, planner/verifier-seam, shrink-eligible, or unknown-investigate
• explicit chore(gfql): remove IR metadata helper residue #1568 deletion / fix(gfql): restore IR metadata compatibility seam #1572 restoration audit context
• explicit feat(gfql): add public declarative schema model #1457/GFQL type system follow-on A: public declarative schema model + stable exports #1337 typed-schema surface context
• perf: graphistry wheel size (625 kB) — GFQL engine files are large, investigate modularization #1058 audit references:
  • perf: graphistry wheel size (625 kB) — GFQL engine files are large, investigate modularization #1058 (comment)
  • perf: graphistry wheel size (625 kB) — GFQL engine files are large, investigate modularization #1058 (comment)

Recommendation in the inventory: #1567 can resume only as a guarded narrow audit/shrink lane after coordinator acceptance. It should remain paused for any deletion touching metadata helpers, typed-schema/Arrow/schema catalog surfaces, package re-exports, logical/physical planning contracts, query graph/pushdown contracts, or verifier invariants.

Validation:

• review skill converged after rebase
• git diff --check
• symbol coverage script: symbol coverage ok
• 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.

[lmeyerov]

Closing #1580 as not-merging-the-broad-inventory.

Worker pygraphistry3/ delivered PR #1631 with a comprehensive SEAM_INVENTORY.md covering every current graphistry.compute.gfql.ir symbol with seam-classification. On review, both worker and coordinator concluded this is high-churn repo documentation that captures internal implementation state better-suited to issue/coordinator notes than maintained source docs.

The valuable underlying concerns find better homes:

• Public stable interfaces: API/user-facing docs or an architecture doc that's actually maintained
• Internal-but-protected seams: focused tests + type contracts + narrow local comments where invariants matter
• Temporary shrink-lane guidance: issue comments / coordinator handoff — not committed repo docs
• Do-not-delete lessons from #1568/#1572: regression tests around the restored metadata seam — not symbol catalogs

#1567 IR/verifier shrink stays paused / coordinator-guarded regardless. Do not use #1631/#1580 as a merge prerequisite for #1567 — the protection signal lives in coordinator instructions and existing regression tests, not in a global inventory file.

PR #1631 is being closed unmerged. This issue can stay open as "not-a-deliverable" or be closed; coordinator-handoff lives on pygraphistry#1058.