Skip to content

fix(cypher): range() arity is enforced at the front end (LABS-1307) - #140

Merged
jexp merged 1 commit into
mainfrom
fix/range-arity
Nov 10, 2026
Merged

jexp merged 1 commit into
mainfrom
fix/range-arity

Conversation

@jexp

@jexp jexp commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fix: range() accepted a wrong argument count — range(1) passed the builtin arity gate and reached the implementation, where the missing end surfaced as a type error, and a fourth argument was silently ignored. The builtin row now carries the live-verified two-to-three contract through the one min/max arity table, so the shared gate refuses both counts before any argument is evaluated.

Changes

  • registry.rs: new ARITY_TWO_TO_THREE contract (min 2, max 3, "requires two to three arguments"), pinned to live Neo4j 2026.10.1; the range row moves off the ARITY_AT_LEAST_ONE floor
  • scalar_function_arity.rs (renamed from labs667_zero_arg_arity.rs, module doc re-scoped to all scalar-arity refusals): range(), range(1) and range(1, 2, 3, 4) are arity errors; the two- and three-argument forms keep their values, asserted through the shared common::list helper; the zero-argument coverage is unchanged

User-facing impact

range(1) and range(...) with four or more arguments now raise Neo.ClientError.Statement.SyntaxError (InvalidNumberOfArguments), matching Neo4j, instead of a type error (one argument) or a silently truncated result (four+).

Example usage

RETURN range(1)
// before: type error: InvalidArgumentType: range() end
// after:  InvalidNumberOfArguments: range() requires two to three arguments, got 1

RETURN range(1, 5, 2, 99)
// before: [1, 3, 5]   (extra argument ignored)
// after:  InvalidNumberOfArguments: range() requires two to three arguments, got 4

RETURN range(1, 5, 2)
// => [1, 3, 5]

Verification

  • live Neo4j 2026.10.1 over Bolt: range(1) -> Neo.ClientError.Statement.SyntaxError "Insufficient parameters for function 'range'"; range(1,2,3,4) -> the "Too many parameters" SyntaxError; range(1,5) / range(1,10,2) return their lists
  • cargo test -p relate --test scalar_function_arity — 4/4; range_takes_two_or_three_arguments fails on the pre-fix row and passes with it
  • cargo test -p relate-executor --lib — 1386 passed, 2 ignored
  • cargo test -p relate-planner — all suites pass
  • cargo test -p relate — all suites pass except the host-calibration test cancellation::cancelling_inside_a_one_hop_pushdown_aggregation_errors_promptly, which asserts a wall-clock floor (80 ms) on this host (measured 69-79 ms, varies run to run; untouched by this diff, 2-arg range unchanged)
  • cargo fmt --all --check and cargo clippy --workspace --all-targets --exclude relate-python -- -D warnings clean @1.88

Fixes LABS-1307.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Security review (security-review skill)

Reviewed the range() arity tightening: a new ARITY_TWO_TO_THREE contract in the builtin registry plus the renamed scalar-arity test file. The change is a pure input-validation strictness increase on the Cypher front end — the shared arity gate now refuses wrong argument counts in both the scalar dispatch and the lazy range path before any argument is evaluated, so the previously silent truncation of a fourth argument and the downstream type error are closed. No auth, secrets, network, file-path, serialization, or dependency surface is touched; range output remains bounded by the existing ADR-0463 charge path, unchanged by this diff.

No issues found.

Security review: ✅ no issues found

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Rust review (rust-reviewer skill, full review)

Full review of the PR diff. The only Rust changes are the executor's builtin registry — range moving from the generic at-least-one floor to a new two-to-three-argument window — and the renamed engine-level arity test. The new Arity constant carries a non-empty verified set, so the lockstep registration test still pins it, and the same contract already feeds the lazy_range path. The test additions exercise both refused counts and both valid shapes with typed value assertions; the catalogue already advertises the two- and three-argument range rows, so no parallel arity state diverges. No panics, unnecessary clones, &String parameters, unsafe, or non-idiomatic patterns were introduced.

No issues found.

Rust review: ✅ no issues found

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stellar review round 1: 3 inline finding(s); see summary comment.

fn range_takes_two_or_three_arguments() {
let mut conn = common::connection();
for query in ["RETURN range(1)", "RETURN range(1, 2, 3, 4)"] {
let text = common::err_text(conn.execute(query));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Medium] structure (q-right-file): This file is named for and documented as one contract — //! Zero-argument scalar calls (LABS-667) (lines 1-6) — but the added unit is a different arity subject: range's one- and four-argument refusa

Suggested fix: Give the range contract a home whose name says what it tests: either broaden this file into a scalar-arity file (rename to match the sibling topic-named arity files such as temporal_constructor_arity.rs / integer_argument_error_classes.rs, and re-scope the module doc to all scalar-arity refusals

finding F-1-1

relate::Value::Int(3)
]
.into()
)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Medium] boundaries (std-6): The expectation hand-rolls relate::Value::List(vec![…].into()) even though this crate's common module — already imported and used here for connection/err_text/scalar_one — ships `common::lis

Suggested fix: Build the expectation with common::list(vec![relate::Value::Int(1), relate::Value::Int(2), relate::Value::Int(3)]) instead of the raw relate::Value::List(vec![…].into()).

finding F-1-2

relate::Value::Int(5)
]
.into()
)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Medium] boundaries (std-6): The sibling expectation repeats the same hand-rolled relate::Value::List(vec![…].into()) shape instead of calling the crate's canonical common::list helper that the surrounding test files use for

Suggested fix: Build the expectation with common::list(vec![relate::Value::Int(1), relate::Value::Int(3), relate::Value::Int(5)]).

finding F-1-3

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Stellar review (stellar-review skill)

Round 3 · head 38e68548 · scope: 0/15 units (15 sealed from earlier rounds).

No open issues.

Stellar review: ✅ no issues found

`range()`'s builtin row carried ARITY_AT_LEAST_ONE with no ceiling, so
`range(1)` passed the arity gate and reached `range_plan`, whose missing
`end` argument surfaced as a type error instead of Neo4j's 42I13
SyntaxError. The row now states the verified contract, two to three
arguments, through the one min/max arity table; the shared gate rejects
both `range(1)` and `range(1, 2, 3, 4)` before evaluating any argument or
calling the implementation.

Verified live against Neo4j 2026.10.1 (Bolt): `range(1)` is
"Neo.ClientError.Statement.SyntaxError: Insufficient parameters for
function 'range'", `range(1, 2, 3, 4)` is the "Too many parameters"
SyntaxError, and the two- and three-argument forms return their lists.

The engine-level test file is renamed `labs667_zero_arg_arity.rs` ->
`scalar_function_arity.rs` and re-scoped to all scalar-arity refusals (the
zero-argument side, calls above an exact or capped contract, and range's
two-to-three window); the expected lists use the shared `common::list`
helper.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@jexp

jexp commented Nov 10, 2026

Copy link
Copy Markdown
Contributor Author

Round-2 test-shape fixes at head 38e6854:

  • F-1-1: relate/relate/tests/labs667_zero_arg_arity.rs -> relate/relate/tests/scalar_function_arity.rs (git rename), module doc re-scoped to all scalar-arity refusals: zero-argument calls (LABS-667), calls above an exact or capped contract, and range's two-to-three window (LABS-1307). Zero-argument coverage unchanged.
  • F-1-2 / F-1-3: both range value expectations use the shared common::list helper instead of a hand-rolled relate::Value::List(vec![...].into()).

Gates @1.88 (CARGO_TARGET_DIR=target-gate): cargo fmt --all --check clean; cargo clippy --workspace --all-targets --exclude relate-python -- -D warnings exit 0; cargo test -p relate 140 suites, 1499 passed, 0 failed, 1 ignored (includes the renamed scalar_function_arity binary, 4/4).

Note: cancellation::cancelling_inside_a_one_hop_pushdown_aggregation_errors_promptly flaked on two earlier runs (wall-clock calibration floor 80 ms, measured 69-79 ms on this host, file untouched by the diff, 2-arg range unchanged); green on the final full run.

@jexp
jexp marked this pull request as ready for review November 10, 2026 14:09
@oplane-bot

oplane-bot Bot commented Nov 10, 2026

Copy link
Copy Markdown

Oplane Security Review

Oplane reviewed this PR and did not identify any security requirements that need attention. Review the generated threat model.


Change comment settings · Set up Oplane in your agent · Workflow guidance

@github-actions

Copy link
Copy Markdown

Loadtest baselines comparison

Note: loadtest comparison completed with no failing rows.


Loadtest baseline comparison

Frozen baselines vs current reports; bands match the compare-loadtests gate.

Status: ok

Pairs: fraud-loadtest: compared · identity-loadtest: compared

fraud-loadtest

baselines/fraud-loadtest.json → target/fraud-loadtest.json

Metric Baseline PR Δ Status
environment relate-loadtest-baseline/v1 relate-loadtest-baseline/v1 — match
errors 0 0 +0 ok
ops/s 3938.56 3782.15 -156.41 (-4.0%) ok
p99 (worst: amount_band) 7.30 ms 7.09 ms -0.22 ms (-3.0%) ok
logical bytes 17,344,481 17,248,554 -95,927 (-0.6%) ok
Per-use-case p99 latency
Use case ops Baseline p99 PR p99 Δ Status
p2p_transfer 3,793 8.04 ms 7.72 ms -0.32 ms (-4.0%) ok
payroll_scatter 1,120 17.85 ms 16.01 ms -1.84 ms (-10.3%) ok
onboard_customer 816 8.53 ms 8.21 ms -0.33 ms (-3.8%) ok
mule_scatter 799 14.80 ms 11.23 ms -3.57 ms (-24.1%) ok
layering_cycle 781 15.10 ms 11.22 ms -3.88 ms (-25.7%) ok
recent_transfers 2,280 7.65 ms 7.19 ms -0.47 ms (-6.1%) ok
customer_portfolio 1,400 7.37 ms 6.72 ms -0.65 ms (-8.8%) ok
outgoing_volume 1,127 7.48 ms 7.21 ms -0.27 ms (-3.6%) ok
detect_fanout 853 25.78 ms 17.18 ms -8.59 ms (-33.3%) ok
detect_cycle 837 7.55 ms 7.08 ms -0.47 ms (-6.3%) ok
activity_page 1,103 7.48 ms 7.02 ms -0.46 ms (-6.2%) ok
search_customer 936 7.84 ms 7.39 ms -0.46 ms (-5.8%) ok
counterparties 1,133 7.45 ms 7.10 ms -0.35 ms (-4.7%) ok
payment_path 806 7.47 ms 6.61 ms -0.86 ms (-11.5%) ok
amount_band 811 7.30 ms 7.09 ms -0.22 ms (-3.0%) ok
flag_account 697 8.21 ms 7.52 ms -0.69 ms (-8.4%) ok
reverse_last_out 708 8.04 ms 7.46 ms -0.59 ms (-7.3%) ok

identity-loadtest

baselines/identity-loadtest.json → target/identity-loadtest.json

Metric Baseline PR Δ Status
environment relate-loadtest-baseline/v1 relate-loadtest-baseline/v1 — match
errors 0 0 +0 ok
ops/s 573.51 733.97 +160.46 (+28.0%) ok
p99 (worst: group_roster) 7.72 ms 7.43 ms -0.29 ms (-3.8%) ok
logical bytes 7,167,614 7,165,605 -2,009 (-0.0%) ok
Per-use-case p99 latency
Use case ops Baseline p99 PR p99 Δ Status
provision_user 1,373 11.00 ms 9.46 ms -1.54 ms (-14.0%) ok
add_to_group 1,775 18.57 ms 15.86 ms -2.71 ms (-14.6%) ok
grant_role 1,079 18.52 ms 15.61 ms -2.90 ms (-15.7%) ok
attach_device 907 18.88 ms 15.63 ms -3.25 ms (-17.2%) ok
nested_grant 736 19.41 ms 14.51 ms -4.90 ms (-25.3%) ok
effective_access 2,173 25.25 ms 18.98 ms -6.26 ms (-24.8%) ok
org_walk 1,387 19.94 ms 16.51 ms -3.42 ms (-17.2%) ok
optional_manager 1,312 20.00 ms 15.98 ms -4.02 ms (-20.1%) ok
detect_nested_admin 810 19.97 ms 15.46 ms -4.52 ms (-22.6%) ok
detect_sod 817 19.60 ms 15.48 ms -4.12 ms (-21.0%) ok
stale_grants 827 15.06 ms 11.91 ms -3.16 ms (-21.0%) ok
search_directory 1,147 10.91 ms 9.99 ms -0.92 ms (-8.4%) ok
group_roster 1,047 7.72 ms 7.43 ms -0.29 ms (-3.8%) ok
access_review 801 20.02 ms 16.22 ms -3.80 ms (-19.0%) ok
reporting_path 794 30.98 ms 20.71 ms -10.27 ms (-33.1%) ok
disable_user 644 19.50 ms 15.29 ms -4.21 ms (-21.6%) ok
add_alias 710 19.99 ms 16.81 ms -3.18 ms (-15.9%) ok
revoke_membership 674 8.10 ms 7.23 ms -0.87 ms (-10.8%) ok
detach_device 538 14.79 ms 11.11 ms -3.69 ms (-24.9%) ok
clear_expiry 449 17.39 ms 13.54 ms -3.85 ms (-22.2%) ok

@github-actions

Copy link
Copy Markdown

Spec-harness coverage — 🟡

  • 🟡 spec coverage 98.22% — 600 genuine failures (1.78% of the executed scenarios)
  • scenarios run: 33737 (passed 33137, failed 600)
  • bands: 🟢 zero failures · 🟡 failure share ≤ 10% · 🔴 beyond (ADR-0482 §4 — the light never fails the build)
  • suite runtime: 1m 53s
  • neo4j_expected_fail (not counted): 314
  • nondeterministic (not counted): 3
  • skipped (not counted): 2323
  • harness ref: e6b894b9fceb326eea8d63eaf763151114dafec5
failure category count
error-class-mismatch 236
missing-validation 110
result-mismatch 94
side-effects 51
result-temporal-fidelity 29
syntax-error 28
notification-missing 19
type-error 12
other 10
semantic-error 8
setup-failed-syntax 2
setup-failed-type 1

Rerun spec-harness to refresh. Coverage below 100% never fails the build (ADR-0482 §4).

@github-actions

Copy link
Copy Markdown

Memory controls and workspace memory calibration

Warning: memory controls reported improvement.


Memory controls and workspace memory calibration

Status: improvement

sort — max_cgroup_to_logical_ratio

Verdict: improvement

Given: a fresh server per observation, admission on, a hold of 2500 ms, and 1 repeats. Families: sort, expand, aggregation, distinct, and create.

When: each observation parks its sessions on RETURN 1, then holds one workspace family at the target reservation. The shapes are one holder at 1.00 MB, 4.00 MB, and 16.00 MB, then the same 16.00 MB across two and four holders.

Then: each observation records VmRSS and cgroup deltas against the live held logical bytes. The child stays alive.

Outcome: Expected cgroup ratio 0.999x–1.082x. A reading may sit 5% outside that range. Measured 1.24 MB, ratio 0.901x.

Investigate whether this improvement is a false positive. When it is real, re-freeze the envelope with the create-loadtest-baselines workflow.

expand — max_rss_to_logical_ratio

Verdict: improvement

Given: a fresh server per observation, admission on, a hold of 2500 ms, and 1 repeats. Families: sort, expand, aggregation, distinct, and create.

When: each observation parks its sessions on RETURN 1, then holds one workspace family at the target reservation. The shapes are one holder at 1.00 MB, 4.00 MB, and 16.00 MB, then the same 16.00 MB across two and four holders.

Then: each observation records VmRSS and cgroup deltas against the live held logical bytes. The child stays alive.

Outcome: Expected RSS ratio 2.099x–2.147x. A reading may sit 5% outside that range. Measured 2.14 MB, ratio 1.006x.

Investigate whether this improvement is a false positive. When it is real, re-freeze the envelope with the create-loadtest-baselines workflow.

expand — max_cgroup_to_logical_ratio

Verdict: improvement

Given: a fresh server per observation, admission on, a hold of 2500 ms, and 1 repeats. Families: sort, expand, aggregation, distinct, and create.

When: each observation parks its sessions on RETURN 1, then holds one workspace family at the target reservation. The shapes are one holder at 1.00 MB, 4.00 MB, and 16.00 MB, then the same 16.00 MB across two and four holders.

Then: each observation records VmRSS and cgroup deltas against the live held logical bytes. The child stays alive.

Outcome: Expected cgroup ratio 2.072x–2.215x. A reading may sit 5% outside that range. Measured 8.50 MB, ratio 1.000x.

Investigate whether this improvement is a false positive. When it is real, re-freeze the envelope with the create-loadtest-baselines workflow.

distinct — max_rss_to_logical_ratio

Verdict: improvement

Given: a fresh server per observation, admission on, a hold of 2500 ms, and 1 repeats. Families: sort, expand, aggregation, distinct, and create.

When: each observation parks its sessions on RETURN 1, then holds one workspace family at the target reservation. The shapes are one holder at 1.00 MB, 4.00 MB, and 16.00 MB, then the same 16.00 MB across two and four holders.

Then: each observation records VmRSS and cgroup deltas against the live held logical bytes. The child stays alive.

Outcome: Expected RSS ratio 1.256x–1.322x. A reading may sit 5% outside that range. Measured 1.95 MB, ratio 1.132x.

Investigate whether this improvement is a false positive. When it is real, re-freeze the envelope with the create-loadtest-baselines workflow.

@github-actions

Copy link
Copy Markdown

Memory shape

Note: loadtest comparison completed with no failing rows.


Memory shape

Status: ok

All memory shapes held. 🟢

base

Given: an empty relate serve, 1 integer properties on every node, text indexes 0, point indexes 0, range indexes 0, and a 32.00 MB logical ceiling.

When: the base shape is loaded to 0 nodes and 0 relationships, then checkpointed. The child RSS is sampled.

Then: the database holds those counts. The load finishes under the ceiling. Logical bytes, disk, attributed RSS, and the ratio stay inside the frozen boundaries.

Baseline: logical 0.00 MB – 0.00 MB, disk 0.00 MB – 0.00 MB, attributed RSS 0.00 MB – 0.00 MB, ratio 0.000x–0.000x. A reading may sit 5% outside the ratio, and 15% or 1.00 MB outside the sizes.

Validated: logical 0.00 MB, disk 0.00 MB, attributed RSS 0.00 MB, ratio 0.000x.

Report: logical, disk, attributed RSS, and the ratio held.

flat

Given: an empty relate serve, 1 integer properties on every node, text indexes 0, point indexes 0, range indexes 0, and a 32.00 MB logical ceiling.

When: the flat shape is loaded to 120000 nodes and 0 relationships, then checkpointed. The child RSS is sampled.

Then: the database holds those counts. The load finishes under the ceiling. Logical bytes, disk, attributed RSS, and the ratio stay inside the frozen boundaries.

Baseline: logical 26.02 MB – 26.02 MB, disk 1.95 MB – 1.95 MB, attributed RSS 36.49 MB – 36.93 MB, ratio 1.402x–1.419x. A reading may sit 5% outside the ratio, and 15% or 1.00 MB outside the sizes.

Validated: logical 26.02 MB, disk 1.95 MB, attributed RSS 37.36 MB, ratio 1.436x.

Report: logical, disk, attributed RSS, and the ratio held.

fanout

Given: an empty relate serve, 1 integer properties on every node, text indexes 0, point indexes 0, range indexes 0, and a 32.00 MB logical ceiling.

When: the fanout shape is loaded to 52016 nodes and 52000 relationships, then checkpointed. The child RSS is sampled.

Then: the database holds those counts. The load finishes under the ceiling. Logical bytes, disk, attributed RSS, and the ratio stay inside the frozen boundaries.

Baseline: logical 28.62 MB – 28.62 MB, disk 1.75 MB – 1.75 MB, attributed RSS 34.93 MB – 36.61 MB, ratio 1.220x–1.279x. A reading may sit 5% outside the ratio, and 15% or 1.00 MB outside the sizes.

Validated: logical 28.62 MB, disk 1.76 MB, attributed RSS 35.73 MB, ratio 1.248x.

Report: logical, disk, attributed RSS, and the ratio held.

ring

Given: an empty relate serve, 1 integer properties on every node, text indexes 0, point indexes 0, range indexes 0, and a 32.00 MB logical ceiling.

When: the ring shape is loaded to 46000 nodes and 46000 relationships, then checkpointed. The child RSS is sampled.

Then: the database holds those counts. The load finishes under the ceiling. Logical bytes, disk, attributed RSS, and the ratio stay inside the frozen boundaries.

Baseline: logical 29.99 MB – 29.99 MB, disk 1.77 MB – 1.77 MB, attributed RSS 35.30 MB – 35.89 MB, ratio 1.177x–1.197x. A reading may sit 5% outside the ratio, and 15% or 1.00 MB outside the sizes.

Validated: logical 29.99 MB, disk 1.77 MB, attributed RSS 36.08 MB, ratio 1.203x.

Report: logical, disk, attributed RSS, and the ratio held.

dense ring

Given: an empty relate serve, 1 integer properties on every node, text indexes 0, point indexes 0, range indexes 0, and a 32.00 MB logical ceiling.

When: the dense ring shape is loaded to 5000 nodes and 100000 relationships, then checkpointed. The child RSS is sampled.

Then: the database holds those counts. The load finishes under the ceiling. Logical bytes, disk, attributed RSS, and the ratio stay inside the frozen boundaries.

Baseline: logical 31.41 MB – 31.41 MB, disk 1.62 MB – 1.62 MB, attributed RSS 31.27 MB – 32.46 MB, ratio 0.996x–1.034x. A reading may sit 5% outside the ratio, and 15% or 1.00 MB outside the sizes.

Validated: logical 31.41 MB, disk 1.61 MB, attributed RSS 31.72 MB, ratio 1.010x.

Report: logical, disk, attributed RSS, and the ratio held.

@jexp
jexp merged commit 6a2a0fc into main Nov 10, 2026
78 checks passed
@jexp
jexp deleted the fix/range-arity branch November 10, 2026 14:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant