planning and tasks for expanded order_by support in schemas

[ajtmccarty]

Summary by cubic

Adds metadata-aware schema order_by with explicit direction and applies it across node lists, relationship peer lists, and hierarchy queries. Query-time order now replaces schema defaults (no stacking), and ordering is stable across paths (UUID tiebreaker) (INFP-530).

• New Features

  • Parser + validator: require an attribute property segment (e.g., name__value), allow properties beyond value, support optional __asc|__desc, and add stricter checks with clearer errors.
  • Metadata ordering: node_metadata__{created_at|updated_at}[__asc|__desc] in NodeGetListQuery, RelationshipGetPeerQuery, and NodeGetHierarchyQuery.
  • Reserved names: node_metadata reserved.
  • Inheritance: metadata order_by entries are preserved during attribute renames.
  • GraphQL many relationships: accept order overrides; honor left-to-right order of multiple clauses, including metadata/attribute combos.
  • Behavior change: a query-time order fully replaces schema-level order_by defaults.

• Tests & Docs

  • Component tests for metadata ordering across all three query paths and GraphQL defaults when no query-time order is provided.
  • Unit tests for the parser, inheritance behavior, and reserved-name enforcement.
  • Docs/specs updated; order_by field description clarified; spec and plan synced with implementation and redundant checklist removed.

^{Written for commit 34ae804. Summary will update on new commits.}

[cubic-dev-ai]

5 issues found across 8 files

Confidence score: 4/5

• This PR looks safe to merge with low-to-moderate risk: the reported issues are documentation/spec accuracy problems (mostly 4–5/10), not direct runtime regressions in application code.
• The most significant concern is in dev/specs/infp-530-order-by-metadata-direction/data-model.md, where OrderDirection is described as an existing enum even though it is not present in the codebase; this can mislead follow-up implementation work.
• dev/specs/infp-530-order-by-metadata-direction/plan.md includes dependency/version mismatches (Neo4j driver 5.28 vs project 6.0.3, Pydantic 2.10 vs supported >=2.12,<2.13) plus an unsupported Strawberry GraphQL claim, which increases planning ambiguity.
• Pay close attention to dev/specs/infp-530-order-by-metadata-direction/data-model.md, dev/specs/infp-530-order-by-metadata-direction/plan.md, dev/specs/infp-530-order-by-metadata-direction/tasks.md - align dependency/version references and task sequencing guidance before implementation.

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

<sub>Shadow auto-approve: would auto-approve. This PR adds only specification and planning documents (markdown files) for a future schema feature; no code changes, no risk of breaking production logic or data integrity.

Re-trigger cubic</sub>

[cubic-dev-ai]

2 issues found across 7 files (changes from recent commits).

<sub>Shadow auto-approve: would not auto-approve because issues were found.
Tip: Review your code locally with the cubic CLI to iterate faster.
Tip: cubic used a learning from your PR history. Let your coding agent read cubic learnings directly with the cubic MCP.

Re-trigger cubic</sub>

[codspeed-hq]

Merging this PR will not alter performance

✅ 12 untouched benchmarks

---

_{Comparing infp-530-schema-order-by-metadata (34ae804) with develop (01710d9)}

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Shadow auto-approve: would require human review. This PR introduces a substantial new feature (metadata-aware ordering across node lists, relationships, and hierarchy queries) with over 2900 lines changed, touching core query logic, schema validation, GraphQL resolvers, and database subqueries, so the blast radius and risk of breakage are too...

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 10 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="dev/specs/infp-530-order-by-metadata-direction/plan.md">

<violation number="1" location="dev/specs/infp-530-order-by-metadata-direction/plan.md:73">
P3: The plan references a non-existent `RelationshipGetListQuery`; the implemented class is `RelationshipGetPeerQuery`, so this line is misleading.</violation>
</file>

<sub>Shadow auto-approve: would not auto-approve because issues were found.
Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The plan references a non-existent RelationshipGetListQuery; the implemented class is RelationshipGetPeerQuery, so this line is misleading.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At dev/specs/infp-530-order-by-metadata-direction/plan.md, line 73:

<comment>The plan references a non-existent `RelationshipGetListQuery`; the implemented class is `RelationshipGetPeerQuery`, so this line is misleading.</comment>

<file context>
@@ -62,15 +62,17 @@ dev/specs/infp-530-order-by-metadata-direction/
     ├── node.py                                  # NodeGetListQuery direction + precedence + UUID tiebreaker;
     │                                            # NodeGetHierarchyQuery direction + metadata + UUID tiebreaker
-    └── relationship.py                          # RelationshipGetListQuery direction + metadata + UUID tiebreaker
+    ├── relationship.py                          # RelationshipGetListQuery direction + metadata + UUID tiebreaker;
+    │                                            # adds requested_order plumbing for the peer path
+    └── subquery.py                              # NEW build_subquery_order_metadata helper, shared by peer/hierarchy paths
</file context>

Suggested change

	├── relationship.py # RelationshipGetListQuery direction + metadata + UUID tiebreaker;
	├── relationship.py # RelationshipGetPeerQuery direction + metadata + UUID tiebreaker;