Skip to content

perf(executor): the shortest route probes its seek endpoints at the pair bound instead of listing every match (ADR-0555, LABS-1318) - #131

Merged
jexp merged 1 commit into
mainfrom
perf/shortest-seek-cap
Nov 10, 2026
Merged

jexp merged 1 commit into
mainfrom
perf/shortest-seek-cap

Conversation

@jexp

@jexp jexp commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Summary

Optimization: the shortest route's endpoint anchor probes a property-seeked endpoint at the pair bound (16) instead of listing every match first, so a non-selective end map no longer builds a list of millions only to learn the pair product is over the bound (ADR-0555).

Changes

  • The candidate funnel gains an optional cap (node_candidates_capped, Capped::{Within, Over}); a residual scan stops at the first cap + 1 matches. Uncapped callers are unchanged.
  • Graph::lookup_nodes_upto_at / ExecGraph::lookup_nodes_upto thread the cap to the scan. A view with write scratch answers in full: a truncated base answer could lose members to scratch deletions and read as complete.
  • Route::anchor resolves each endpoint as scan / listed (<= 16) / over. A side is built in full only when it drives a fan (both sides over keeps the shorter-side choice, so 100 ends against 100k starts still fans backward from the 100).
  • Tests: four more anchor shapes in the route-versus-GPM parity matrix, an over-bound read-count and empty-side test, a write-view test (20 committed ends, 10 deleted in-statement), and funnel boundary and early-stop tests.

Verification

  • cargo test -p relate-executor (1389 passed), cargo fmt --all --check, cargo clippy --workspace --all-targets --exclude relate-python -- -D warnings
  • Mutation checks: capping the base under a write view fails the write-view test; removing the scan's early exit fails both the funnel and the route read-count tests
  • stellar-prep.sh local briefs generated; review passes not run in this session
  • Ready-gate CI matrix

Fixes LABS-1318.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Security review (security-review skill)

The diff is an executor optimization in the shortest-route anchor resolution: endpoint probes now stop at SEEK_PAIR_LIMIT + 1 matches instead of materializing every match, with a write-view guard that falls back to an uncapped base lookup so scratch deletions cannot make a truncated list read as complete. Reviewed for new input surface, panics, authorization/secrets, dependency changes, and resource-exhaustion regressions: the capped path is internal (pub(crate)), adds no I/O, auth, network, secrets, or dependencies, and strictly reduces work relative to the prior full materialization. The added expect is invariant-bound — Probe::Over is only produced after the same row and pattern passed seekable, so the full seek cannot return None — and the capped scan returns a complete list at or below the cap by construction, so no partial result is treated as complete.

No issues found.

Security review: ✅ no issues found

…air bound instead of listing every match (ADR-0555, LABS-1318)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@jexp
jexp force-pushed the perf/shortest-seek-cap branch from c9e210e to d70720a Compare November 10, 2026 11:21
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Stellar review (stellar-review skill)

Round 3 · head d70720a6 · scope: 0/125 units (125 sealed from earlier rounds).

Still open from earlier rounds

  • [Medium] structure (std-1) F-1-1: relate/relate-executor/src/exec/gpm/shortest_route/route.rs:255-315 — This branch takes route.rs from 718 to 795 lines by bolting a second, independent change-driver onto the file: the endpoint-resolution cost policy (Probe plus the anchor/listed/probe/seekable/seek_c
  • [Medium] branching (std-2) F-1-2: relate/relate-executor/src/exec/gpm/shortest_route/route.rs:273-277 — Both arms emit nothing, so the guard buys nothing: a listed side of length 0 makes the pair product empty and makes a fan from that side a no-op, so Pair{empty, empty} and Fan{origins: empty} are
  • [Medium] branching (std-0) F-1-3: relate/relate-executor/src/exec/gpm/shortest_route/route.rs:380-382 — seek_candidates has exactly one caller — the (Probe::Over, Probe::Over) arm — and Probe::Over is only produced after seekable returned true, so this None branch is unreachable at its only us
  • [Medium] boundaries (std-5) F-1-4: relate/relate-executor/src/pattern_walk/candidates/mod.rs:400-404 — The new cap reaches the lookup arm but is silently dropped by both fallthroughs: a pattern whose labels are not a static conjunction skips the lookup entirely, and the Unindexed arm returns every
  • [Medium] boundaries (std-6) F-1-5: relate/relate-executor/src/exec/gpm/shortest_route/route.rs:429-434 — capped_candidates is a second copy of the route's one candidate-resolution policy: its prologue is line-for-line candidates (408–414) and the only difference is the funnel entry point and return t
  • [Medium] boundaries (std-4) F-1-6: relate/relate-executor/src/exec/gpm/shortest_route/route.rs:291-294 — Self::listed is asked to choose pair-or-fan for two sides that probe already found past SEEK_PAIR_LIMIT, so its Pair arm is unreachable at this call site and the arm only needs the shorter-sid
  • [Medium] comparison (flag-canonical-dup) F-1-7: relate/relate-executor/src/overlay/seek.rs:38-38 — The new capped lookup gives up the cap for any write view, while the committed-answer shortcut beside it (lookup_range_cardinality, same file) declines only on overlay_changes_node_membership() —
  • [Low] branching (std-3) F-1-8: relate/relate-executor/src/graph/index_lookup.rs:237-242 — The capped rewrite replaced retain with a manual push/break loop, nesting the cap condition inside the hit condition inside the scan and adding mutable accumulation to the hot scan; the bound is o
  • [Low] branching (std-3) F-1-9: relate/relate-executor/src/exec/gpm/shortest_route/route.rs:71-76 — Both state docs promise more than probe delivers, and these states are what the 9-arm anchor table keys on. Scan also covers a property map that is present but not row-ready (seekable's second c

Stellar review: ⚠️ 9 issue(s) open (0 + 0 anchored new (fail/low) + 9 carried)

/// A bound node, or a seeked list of at most [`SEEK_PAIR_LIMIT`].
Listed(Side),
/// A seek matching more than [`SEEK_PAIR_LIMIT`] nodes; the list was
/// never built.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[Low] Documentation / allocation: Probe::Over claims "the list was never built", but the cap only reaches the residual scan.

Why this matters: Graph::lookup_nodes_upto_at (graph/index_lookup.rs:57-63) exempts index-served arms, so with a RANGE index on the endpoint's property the probe still materializes every match and then drops it; the (Probe::Over, Probe::Over) arm at route.rs:291 then re-seeks both sides in full, doing twice the work the pre-change code did once. The anchor comment at route.rs:272 ("the over side stays unbuilt") has the same over-claim.
Suggested fix: state the exemption in Probe::Over/lookup_nodes_upto_at ("an over-bound scan stops at cap+1; an index-served side answers in full"), or have Probe carry the list it already built instead of re-seeking it.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Rust review (rust-reviewer skill, full review)

Reviewed the shortest-route endpoint capping in full: the new Capped/node_candidates_capped funnel entry, Ask { conjuncts, cap }, the capped scan_match in Graph::lookup_nodes_upto_at, the overlay's uncapped base on a write scratch, and the Probe/Anchor table that replaces resolve, plus the new tests. Ownership and lifetimes are clean (borrowed Ask, no needless clones), no unsafe is touched, errors propagate through Result with an invariant-only expect, and the Probe match stays exhaustive. The Over decision is length-only, so truncation can never masquerade as a complete Within; the overlay correctly disables the base cap whenever scratch deletions could hide matches; and every Listed/Over/Scan combination reproduces the prior anchor choice, including the empty-side product.

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: 7 inline finding(s); see summary comment. (inline comments degraded to summary — see error above)

@jexp
jexp marked this pull request as ready for review November 10, 2026 11:34
@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

});
ids.sort();
ids
let mut matched = Vec::new();

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] Performance: scan_match now collects matches into a second Vec on every call, including the uncapped path (cap == None) that all existing callers use.

Why this matters: this is the fallback the shared node-candidate funnel takes for every non-index-served label/property match (including per-row inner patterns like (n:Person {name: …})). The old code filtered the candidate list in place with retain; the new code keeps the original ids buffer alive while matched grows by push, so a non-selective scan holds two vectors at once (up to ~3x the transient buffer) and pays the growth reallocs on a path the rest of the engine reads per row.
Suggested fix: branch on cap — when cap.is_none() keep the old in-place ids.retain(...) + ids.sort(); use the early-exit loop only for Some(cap).

@github-actions

Copy link
Copy Markdown

Spec-harness coverage — 🟡

  • 🟡 spec coverage 97.13% — 969 genuine failures (2.87% of the executed scenarios)
  • scenarios run: 33725 (passed 32756, failed 969)
  • bands: 🟢 zero failures · 🟡 failure share ≤ 10% · 🔴 beyond (ADR-0482 §4 — the light never fails the build)
  • suite runtime: 1m 44s
  • neo4j_expected_fail (not counted): 325
  • nondeterministic (not counted): 4
  • skipped (not counted): 2323
  • harness ref: bf1447a2a1bb9b0d5685745d61cb56b9049cebe0
failure category count
result-mismatch 464
error-class-mismatch 235
missing-validation 110
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

workload-indexed — processing_rss_min_bytes

Verdict: improvement

Given: a ledger at graph scale 10 loaded with the limits off, then reopened with --max-connections 0 and --concurrent-logical-workspace-limit 53.24 MB.

When: 8 warmup operations run uncounted. Then 16 Bolt clients share 40 operations at 80:20, reads mix, indexes indexed.

Then: every connection is accepted. A query that does not fit the workspace pool counts as limited. A write-write conflict counts as failed. Any other error fails the run.

Outcome: reads succeeded 32, limited 0, failed 0; writes succeeded 8, limited 0, failed 0; connection refusals 0; workspace refusals 0.

Measured 12.31 MB against the envelope 14.80 MB – 20.16 MB.

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

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 32.98 MB, ratio 0.970x.

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 33.00 MB, ratio 0.970x.

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 29.53 MB, ratio 1.073x.

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.20 MB, ratio 1.430x.

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 36.64 MB, ratio 1.280x.

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.32 MB, ratio 1.211x.

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 32.21 MB, ratio 1.026x.

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

@github-actions

github-actions Bot commented Nov 10, 2026 •

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 4553.73 +615.18 (+15.6%) ok
p99 (worst: flag_account) 8.21 ms 7.90 ms -0.30 ms (-3.7%) ok
logical bytes 17,344,481 17,284,307 -60,174 (-0.3%) ok
Per-use-case p99 latency
Use case ops Baseline p99 PR p99 Δ Status
p2p_transfer 3,845 8.04 ms 7.47 ms -0.58 ms (-7.2%) ok
payroll_scatter 1,067 17.85 ms 13.00 ms -4.85 ms (-27.2%) ok
onboard_customer 882 8.53 ms 7.12 ms -1.41 ms (-16.6%) ok
mule_scatter 812 14.80 ms 10.13 ms -4.68 ms (-31.6%) ok
layering_cycle 797 15.10 ms 10.50 ms -4.60 ms (-30.4%) ok
recent_transfers 2,191 7.65 ms 6.82 ms -0.84 ms (-10.9%) ok
customer_portfolio 1,436 7.37 ms 6.90 ms -0.47 ms (-6.4%) ok
outgoing_volume 1,094 7.48 ms 6.43 ms -1.05 ms (-14.1%) ok
detect_fanout 838 25.78 ms 17.13 ms -8.64 ms (-33.5%) ok
detect_cycle 900 7.55 ms 6.46 ms -1.09 ms (-14.5%) ok
activity_page 1,104 7.48 ms 6.64 ms -0.85 ms (-11.3%) ok
search_customer 871 7.84 ms 7.28 ms -0.56 ms (-7.2%) ok
counterparties 1,104 7.45 ms 7.07 ms -0.38 ms (-5.1%) ok
payment_path 825 7.47 ms 6.99 ms -0.48 ms (-6.4%) ok
amount_band 820 7.30 ms 6.65 ms -0.65 ms (-8.9%) ok
flag_account 691 8.21 ms 7.90 ms -0.30 ms (-3.7%) ok
reverse_last_out 723 8.04 ms 7.54 ms -0.50 ms (-6.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 640.74 +67.23 (+11.7%) ok
p99 (worst: group_roster) 7.72 ms 7.33 ms -0.39 ms (-5.1%) ok
logical bytes 7,167,614 7,165,893 -1,721 (-0.0%) ok
Per-use-case p99 latency
Use case ops Baseline p99 PR p99 Δ Status
provision_user 1,373 11.00 ms 9.91 ms -1.09 ms (-9.9%) ok
add_to_group 1,775 18.57 ms 17.38 ms -1.18 ms (-6.4%) ok
grant_role 1,079 18.52 ms 16.76 ms -1.76 ms (-9.5%) ok
attach_device 907 18.88 ms 16.91 ms -1.96 ms (-10.4%) ok
nested_grant 736 19.41 ms 16.63 ms -2.78 ms (-14.3%) ok
effective_access 2,173 25.25 ms 19.86 ms -5.39 ms (-21.4%) ok
org_walk 1,387 19.94 ms 16.76 ms -3.18 ms (-15.9%) ok
optional_manager 1,312 20.00 ms 16.91 ms -3.09 ms (-15.4%) ok
detect_nested_admin 810 19.97 ms 16.42 ms -3.56 ms (-17.8%) ok
detect_sod 817 19.60 ms 18.10 ms -1.50 ms (-7.7%) ok
stale_grants 827 15.06 ms 11.07 ms -4.00 ms (-26.5%) ok
search_directory 1,147 10.91 ms 9.98 ms -0.93 ms (-8.5%) ok
group_roster 1,047 7.72 ms 7.33 ms -0.39 ms (-5.1%) ok
access_review 801 20.02 ms 17.21 ms -2.81 ms (-14.0%) ok
reporting_path 794 30.98 ms 25.76 ms -5.22 ms (-16.8%) ok
disable_user 644 19.50 ms 17.58 ms -1.92 ms (-9.8%) ok
add_alias 710 19.99 ms 18.41 ms -1.58 ms (-7.9%) ok
revoke_membership 674 8.10 ms 7.46 ms -0.64 ms (-7.9%) ok
detach_device 538 14.79 ms 10.35 ms -4.44 ms (-30.0%) ok
clear_expiry 449 17.39 ms 16.48 ms -0.91 ms (-5.2%) ok

@jexp
jexp merged commit c48db2b into main Nov 10, 2026
139 of 149 checks passed
@jexp
jexp deleted the perf/shortest-seek-cap branch November 10, 2026 19:26
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