GFQL type system follow-on: schema effects for graph-growing calls

Summary

Follow-on design/implementation lane for #1046 after the public schema contract work: add an internal schema-effects model for graph-growing GFQL/Cypher operations.

This is not a #1457/#1337 merge blocker. It should run after the declared schema contract is stable enough to attach deltas to graph-valued operations.

Parent / sequencing

Umbrella: [FEA] GFQL native type system: schemas, inference, validation, and Arrow representation #1046
Depends conceptually on: feat(gfql): add public declarative schema model #1457 / GFQL type system follow-on A: public declarative schema model + stable exports #1337
Informs: GFQL type system follow-on B: schema inference API + typed topology extraction #1338, GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339, GFQL remote: send bound typed GraphSchema with gfql_remote requests #1465, GFQL schema tutorial: infer, refine, bind, and validate Cypher #1464

Recommended order:

feat(gfql): add public declarative schema model #1457/GFQL type system follow-on A: public declarative schema model + stable exports #1337: declared open schema contract.
GFQL type system follow-on B: schema inference API + typed topology extraction #1338: infer/refine/bind the same contract.
GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339: Arrow boundary enforcement/coercion.
This issue: schema effects for graph-growing calls.
GFQL remote: send bound typed GraphSchema with gfql_remote requests #1465: remote schema payload.
GFQL schema tutorial: infer, refine, bind, and validate Cypher #1464: tutorial after inference.

Goal

Represent graph-growing transforms as schema deltas, so GFQL can validate columns added by algorithms and ETL-like calls without pretending the graph is statically closed.

Example:

Graph[Person{name}]
  -> pagerank(write="pagerank")
  -> Graph[Person{name, pagerank: float64}]

Scope

Add an internal SchemaEffect / equivalent model for graph-valued GFQL operations.
Represent added node/edge properties, updates, drops, and confidence/provenance.
Cover graph-growing builtins such as degree.write, pagerank.write, cugraph/igraph write variants, and ETL-like call(...) enrichments where current safelists already know effects.
Thread effects through planner/validation metadata as Graph[S] -> Graph[S + delta].
Preserve existing runtime behavior; this lane is about validation/planning metadata first.
Add tests showing a column added by an earlier graph-growing call is visible to later validation/matching through the effect model.

Out of scope

Public tutorial work; tracked in GFQL schema tutorial: infer, refine, bind, and validate Cypher #1464 after inference.
Remote schema payload; tracked in GFQL remote: send bound typed GraphSchema with gfql_remote requests #1465.
Full public Arrow boundary enforcement; tracked in GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339.
Broad schema inference; tracked in GFQL type system follow-on B: schema inference API + typed topology extraction #1338.
A complete static graph calculus.

Design constraints

Cypher labels are predicates, not classes.
NodeType / EdgeType are trait-like contracts.
(:A:B) should merge trait/property fragments.
(:A|B) should branch; guaranteed properties are intersection, admissible properties are union/maybe.
Relationship type disjunction branches; positive relationship-type conjunction should reject or be unsatisfiable.
Conflict/presence rules must distinguish required, optional, maybe-absent, and unknown.
First-class graph values should be modeled as Graph[SchemaSnapshot] over time.

Acceptance

Internal schema-effect representation exists and is documented in code comments or developer docs.
At least one graph-growing builtin has a tested effect path.
Later validation can see a property added by a prior effect.
No user-facing API is overpromised beyond current declared schema behavior.
[FEA] GFQL native type system: schemas, inference, validation, and Arrow representation #1046, GFQL type system follow-on B: schema inference API + typed topology extraction #1338, GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339, GFQL remote: send bound typed GraphSchema with gfql_remote requests #1465, and GFQL schema tutorial: infer, refine, bind, and validate Cypher #1464 are cross-linked with this issue.

Coordinator cross-link:

This issue is the concrete follow-on created from the 2026-05-17 graph type-system research pass.

Research summary is recorded locally at:

plans/gfql-type-system-research-2026-05-17/report.md

Published related updates:

[FEA] GFQL native type system: schemas, inference, validation, and Arrow representation #1046 umbrella: [FEA] GFQL native type system: schemas, inference, validation, and Arrow representation #1046 (comment)
GFQL type system follow-on B: schema inference API + typed topology extraction #1338 inference: GFQL type system follow-on B: schema inference API + typed topology extraction #1338 (comment)
GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339 Arrow boundary: GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339 (comment)
GFQL remote: send bound typed GraphSchema with gfql_remote requests #1465 remote payload: GFQL remote: send bound typed GraphSchema with gfql_remote requests #1465 (comment)
GFQL schema tutorial: infer, refine, bind, and validate Cypher #1464 tutorial: GFQL schema tutorial: infer, refine, bind, and validate Cypher #1464 (comment)

Keep this issue out of the #1457 merge gate; it is the later home for graph-growing transform effects.

Coordinator audit cross-link: typed-schema cluster dispatch audit posted on #1058:

#1058 (comment)

This issue/PR was included in the 2026-05-20 audit covering #1457/#1337/#1338/#1339/#1485/#1465 and downstream implications for #1567/#1580.

Post-#1339 pre-scope: #1339 landed via PR #1635 (dcdf93b), so the declared-schema + Arrow boundary pieces are now available for this lane.\n\nRecommended next implementation shape:\n- Keep SchemaEffect internal/experimental; do not add a broad public API yet.\n- Build effects over the #1457 GraphSchema/NodeType/EdgeType contracts and the #1339 Arrow-declared property types/nullability.\n- Start with one narrow graph-growing builtin family whose write params are already explicit and stable, e.g. degree.write or pagerank.write.\n- Represent added node/edge properties as typed deltas with provenance/confidence; later validation should see an added property after the graph-growing call.\n- Preserve runtime behavior: this is validation/planning metadata first, not algorithm semantics or remote transport.\n\nGuardrails:\n- Do not absorb #1338 inference or #1465 remote schema transport.\n- Do not touch protected IR/compiler-plan seams unless the effect metadata path truly requires it and tests prove diagnostic/source-span fidelity is preserved.\n- Keep labels-as-predicates and trait-like NodeType/EdgeType semantics from #1457.\n\nSuggested first acceptance slice: one graph-growing call writes a declared Arrow-typed node property, validation accepts a later reference to that property, and a control test still rejects undeclared/non-effect properties.

Implementation PR opened: https://github.com/graphistry/pygraphistry/pull/1638\n\nCurrent slice:\n- internal-only SchemaEffect model in graphistry.compute.gfql.schema_effects; no top-level graphistry/schema re-export\n- successful local graph-growing calls update the returned graph's bound GraphSchema snapshot\n- covered paths: degree/get_degrees, PageRank-style node writes, and edge-property writes\n- remote GFQL transport is unchanged; #1465 remains separate\n- #1338 inference remains separate and can feed this path by binding/producing public GraphSchema instances\n\nValidation so far is recorded in the PR body; review-skill convergence and full CI are pending.

Implemented and merged via PR #1638:

#1638

Merge commit: 882133e

Closeout:

Added internal-only graphistry.compute.gfql.schema_effects.SchemaEffect; no top-level/public re-export.
Threaded schema effects through successful local graph-growing GFQL calls for bound GraphSchema continuation.
Covered degree, PageRank-style node writes, cugraph edge-property writes, and cugraph multi-column node writes.
Preserved remote GFQL transport and GFQL type system follow-on C: public schema-Arrow APIs + plottable boundary enforcement #1339 Arrow boundary semantics; no IR/planner/compiler-plan seam touched.
Review skill converged: wave 1 finding fixed, waves 2 and 3 clean.
CI green, RTD green, changed-line coverage green.
DGX RAPIDS 26.02 + 25.02 smoke green: schema-effects tests plus real cugraph edge and multi-column write calls, 9 passed on each.

Closing #1485 as delivered by the internal-first schema-effect slice. Public effect exposure and remote transport remain separate follow-ons.

Navigation Menu

Repository navigation

GFQL type system follow-on: schema effects for graph-growing calls #1485

Summary

Parent / sequencing

Goal

Scope

Out of scope

Design constraints

Acceptance

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

GFQL type system follow-on: schema effects for graph-growing calls #1485

Description

Summary

Parent / sequencing

Goal

Scope

Out of scope

Design constraints

Acceptance

Activity

lmeyerov commented on May 17, 2026

lmeyerov commented on May 20, 2026

lmeyerov commented on May 25, 2026

lmeyerov commented on May 25, 2026

lmeyerov commented on May 25, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions