Skip to content

perf(engine): OR'd-label keyed MATCH serves as a union of per-label seeks (LABS-1083) - #145

Merged
jexp merged 1 commit into
mainfrom
perf/labs-1083-label-disjunction-seek
Nov 10, 2026
Merged

jexp merged 1 commit into
mainfrom
perf/labs-1083-label-disjunction-seek

Conversation

@oskarhane

@oskarhane oskarhane commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Optimization: MATCH (p) WHERE (p:Model OR p:Source) AND p.id = $d — the shape agents write whenever a key can point at several node types — planned as a per-row AllNodesScan (291.7M dbHits, 108.9 s on the ticket's repro vs 0.64 s for the per-label rewrite). The planner folds static label disjunctions into the pattern; the executor serves them as a union of per-label keyed seeks. Port of a change that landed in the repository's pre-split tree after the initial import, adapted to the ADR-0541 token-id plan representation.

Changes

  • Planner fold (relate-planner/src/rewrite.rs): a static disjunction of plain labels on an introduced, unbound variable folds into the pattern node's label_expr (And-joined with the node's own labels; one entailed disjunct makes the whole Or fold away — never narrowed; mixed And/Or trees, negations, wildcards, dynamic labels stay filters). Both WHERE spellings fold: p:(A|B) and p:A OR p:B — the WHERE-spelled recognizer answers the typed fact (one variable, its disjuncts), never a bag the caller re-validates. The fold-eligibility gate (introduced and not bound) is named once and consulted by every arm; the disjunction classifier derives from the IR's one arm classifier with the fold's conservatism guards stated beside it; the three folds share one node-targeting walk (fold_target_nodes).
  • Executor union arm (pattern_walk/candidates): LabelExpr::static_disjunction_arms (relate-ir, exposed on NodePattern as the one accessor) classifies Or([A,B]) → arms [A],[B] and And([C,Or([A,B])]) → per-arm conjunctions {C,A}/{C,B}, iterated through a natural arms() iterator (no unchecked arm index); every arm must pass the existing seek eligibility; the union dedups by node id through the tiered word-set utility (ADR-0522) so a both-labels node yields one row; the residual re-check stays the exactness net. The scan tail's base scan states its always-served invariant with the same expect the per-arm serve does.
  • Adjacent fixes from the ticket: the keyed, effectively index-backed lookup narrates NodeByLabelSeek (documented in the cli/rust/bolt specs) instead of overstating a scan — only for bounds the funnel can actually key (a bound reading a variable the clause's own patterns introduce is skipped, mirroring the funnel's LABS-328 decline; the map's anchored equalities and the WHERE conjuncts are gated as the funnel gates them — every map key served per arm, any one conjunct key); single_static_label answers the folded base-carrying shape, so the :C estimate and the MissingIndex diagnostic survive the fold (pinned); a folded disjunction no seek serves carries its own typed LabelDisjunctionScan warning (03C94, message the disjunction scan answers per label; consider the property index (:Model(id), :Source(id))) — never the AllNodesScan payload for a scan that is not one; the "store carries a range index on (label, property)" predicate lives once on the stats contract (range_index_serves), and the :Label(property) schema text once in the catalog (index_schema_text).
  • Tests: engine-level EXPLAIN/answer differential (no AllNodesScan, 2 NodeByLabelSeek with per-arm details, both-labels node exactly once), candidates unit tests (union+dedup, per-arm conjunctions, unindexed-arm decline), planner fold tests (both spellings, entailment fold-away, mixed-tree non-fold), the LabelDisjunctionScan notification pin, the partition pin in the formatter — with the keyed and scan-path comparison stores sharing one row-seeding fixture.

User-facing impact

EXPLAIN/PROFILE narrate per-row keyed lookups and disjunction unions as NodeByLabelSeek (details RANGE INDEX <var>:<Label>(<prop>), one target per arm, comma-joined, no WHERE clause, no count of its own) instead of the fused scan name; a folded disjunction no seek serves raises the new LabelDisjunctionScan notification (Relate.Notification.Statement.LabelDisjunctionScan, 03C94) suggesting the predicate's own :Label(property) pairs; the folded And shape keeps its :C label-count estimate.

Example usage

relate> EXPLAIN MATCH (n:Column) MATCH (m:Model {id: n.id})
        MATCH (p) WHERE (p:Model OR p:Source) AND p.id = n.id
        RETURN p.id AS id;

before: the third MATCH narrates the fused NodeByLabelScan/AllNodesScan and scans every node per row; after: it narrates NodeByLabelSeek with details RANGE INDEX p:Model(id), p:Source(id) and consults only the per-arm indexes.

Deferred

Three stellar rounds (local + two CI): every finding on the port's own code is fixed on-branch — round 3 added the single_static_label base-shape widening (the folded base keeps its MissingIndex diagnostic and its :C estimate), the typed keyed_equalities (the two key shapes gated as the funnel gates them), the canonical clause-variable enumerator, the catalog's one index_schema_text, the scan_disjunction_arms helper, the recognizers' move to subject.rs, the typed Option<&IndexSeek> warning threading, the notification vocabulary pin, and the planner fold's base-as-names. Deliberately deferred to the review-tasks ticket: plan_node/mod.rs's proximity to the 1k ceiling (892 lines before this PR), the or_pattern/eq_conjunct cross-crate fixture consolidation, and plan_warning.rs's second exhaustive match (both it and vocabulary()'s match are compile-forced on a new variant — a new variant cannot compile without choosing in both, so they cannot drift silently; the payload-extractor redesign would trade a compile-forced match for wildcard-bearing accessors).

Verification

  • cargo test -p relate --test label_disjunction_seek_labs1083 --test notifications — ported pins + the new MissingIndex-survives-the-fold pin green (post round-3 fix)
  • cargo test -p relate-planner / cargo test -p relate-executor / cargo test -p relate --lib plan_node / cargo test -p relate-formatter -p relate-cli / cargo test -p relate-model -p relate-catalog
  • cargo fmt --all --check
  • workspace clippy @1.88 -D warnings
  • stellar rounds 1–3: all findings on the port's own code fixed on-branch; deferrals ticketed
  • rebased onto fresh main (post-fix(executor): kernel MATCH emission charges each row before landing (LABS-1077) #146): one commit, same 23 files, combined-tree suites + fmt + clippy @1.88 re-run green
  • full CI matrix (ready gate, rebased head)

This description was auto generated.

seek: &Seek,
arms: &DisjunctionArms<'_>,
) -> Result<Option<Vec<NodeId>>> {
let mut served: Vec<Vec<NodeId>> = Vec::with_capacity(arms.len());

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] Resource exhaustion: seek_union materializes every arm's full posting list into one Vec<Vec<NodeId>> before deduplicating, so peak memory scales with (query-controlled disjunct count) × (index posting size), outside the charged workspace budget.

Why this matters: a crafted query such as WHERE (p:Big OR p:Big OR …) AND p.id = n.id reaches this path once per driving row; the charged TieredWordSet dedup does not account for the retained per-arm vectors, so a small query against a large store can drive the process to OOM.
Suggested fix: fold each arm's ids into the charged set as it is served — the lazy shape the scan_ids call site already uses with union_dedup((0..arms.len()).map(…)) — keeping at most one arm's Vec alive instead of collecting served.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Security review (security-review skill)

Reviewed the PR's engine/planner/executor changes: the label-disjunction fold, the keyed per-arm seek union, the new plan warning/notification wire row, and the accompanying docs/tests. No authN/authZ, secrets, network endpoints, filesystem/command execution, or dependency changes are introduced; query text is already the trusted parser's untrusted input boundary and the new candidate paths only narrow/union index postings that the existing per-candidate check re-verifies. The added production expect calls are invariant-guarded (a non-empty label set always serves lookup_nodes_upto), and label-derived text only flows into already-escaped plan details/notification strings.

No issues found.

Security review: ✅ no issues found

Comment thread relate/relate/src/plan_node/seek.rs Outdated
continue;
};
if let Some(((conjunct_var, key), _)) =
relate_ir::orient_side(relate_ir::var_prop, left, right)

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] Correctness (plan narration): equality_filter_keys accepts any <var>.<key> = <expr> conjunct, so keyed_label_seek narrates NodeByLabelSeek when the bound is a property of a variable the same pattern introduces — MATCH (c:Cell) WHERE c.key = c.cluster, or MATCH (a:Model)-[:R]->(b) WHERE a.id = b.id with a :Model(id) range index.

Why this matters: the funnel declines exactly these bounds — range_seek_expr evaluates the bound against the current row and bails when the pattern variable is unbound (the LABS-328 case its own comment at pattern_walk/candidates/seek.rs:302-311 documents), so lookup_range never runs and scan_ids scans the label instead; EXPLAIN/PROFILE then claim a seek that never executes, contradicting ADR-0486's rule quoted in this function's doc ("the plan never claims a seek the funnel would decline").

Suggested fix: pass the pattern's own variable set into equality_filter_keys and skip a conjunct whose bound side references one of them (only constants/parameters and earlier-clause variables qualify), mirroring range_seek_expr's bound evaluation.

{
return add_labels(patterns, v, &labels);
}
if let Some(disjuncts) = static_label_disjunction(label_expr) {

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] Correctness (plan estimate): this fold rewrites the node's label_expr to And([Label(C), Or([A,B])]), which single_static_label rejects (it requires a static conjunction), so match_estimate now returns None for MATCH (p:C) WHERE p:A OR p:B — pre-fold the :C pattern priced at label_rows(C).

Why this matters: estimated_rows silently disappears from the plan for a shape whose scan is still the :C population, contradicting the updated docs that the fused narration keeps "the label-count estimate" (and this PR's own keyed_label_seek comment that the estimate "keeps the fused path's"); a blank estimate also makes EstimationMiss unreachable for the shape.

Suggested fix: price the folded shape from its conjunction base — let match_estimate fall back to DisjunctionArms::base() when single_static_label declines an And([C, Or(..)]) expression (a bare Or has an empty base and keeps None).

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Rust review (rust-reviewer skill, full review)

Reviewed the full 23-file diff: the planner's label-disjunction fold and its order-independent two-pass conjunct handling, the executor's per-arm union serve and dedup (seek_union/union_dedup/scan_disjunction_arms), the DisjunctionArms borrowed-view classifier and its NodePattern accessor, the new per-row keyed-seek narration and LabelDisjunctionScan warning, the notification vocabulary row, and the accompanying unit/integration pins. Overall posture is clean on the skill's axes: no ownership, lifetime, or unsafe concerns; the two expects in the union/scan paths are invariant-backed and documented (non-empty arm/base label lists make lookup_nodes_upto always serve); error paths propagate workspace-charge failures through Result; no unwrap/panic in non-test code and no unnecessary clones on API boundaries. One Low documentation defect was posted inline.

  • Low — relate/relate-ir/src/ast/pattern.rs:404: the static_disjunction_arms doc links [DisjunctionArms::arms] to DisjunctionArms::arm, a method that does not exist, so rustdoc reports an unresolved intra-doc link.

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: 11 inline finding(s); see summary comment.

if let Some(index) = scan_index_suggestion(node, where_clause, stats, seek_engaged) {
warnings.push(PlanWarning::AllNodesScan { index });
}
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[High] boundaries (std-5): scan_index_suggestion now returns Some for the folded Or shape, so this pushes the typed PlanWarning::AllNodesScan for a pattern that subject::is_all_nodes_scan rejects and fused_subject nam

Suggested fix: Derive the scan shape once, as a typed value (e.g. a ScanShape enum from subject: all-nodes / label conjunction / label disjunction), name the operator and select the warning from that single fact, and give the disjunction shape its own typed warning payload/message instead of reusing `AllNodesS

finding F-1-1

where_clause: None,
force_scan: false,
}
}

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] comparison (flag-canonical-dup): This pair is one fixture spelled twice: relate/relate/src/plan_node/fixtures.rs::or_node (lines 33-48) is field-for-field identical apart from variable: Option<&str>, so or_pattern(v, ds) is jus

Suggested fix: Put the one disjunction NodePattern builder in testing/relate-test-support (both crates already dev-depend on it, and values.rs / plan_rung.rs are the precedent for a shape shared across the executor's and relate's suites) and have both test suites — including and_nested_pattern's nested s

finding F-1-10

CREATE (:Model {id: i}), (:Source {id: i}), (:Column {id: i})",
)
.unwrap();
scanning.query("CREATE (:Model:Source {id: 1})").unwrap();

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] comparison (std-6): The scan-side comparison store re-spells store()'s row creation inline (the UNWIND trio plus the both-labels row) instead of sharing it. The test's claim is that the keyed and scan paths answer over

Suggested fix: Extract the row seeding (the UNWIND range(1,3) trio and the :Model:Source row) into one helper that store() calls before adding its two CREATE INDEX statements; the unindexed comparison fixture calls the same seeding helper, so the two stores cannot drift apart.

finding F-1-11

Comment thread relate/relate/src/plan_node/seek.rs Outdated
// The plan narration renders text: the variable and the pick's
// names render once, here.
if let Some(narration) = seek_narration(
node.variable.as_ref().map(|v| v.to_string()).as_deref(),

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] branching (std-3): The counted-seek derivation used to be a ? chain; the diff wraps it in three nested if lets whose only purpose is to fall through to the new keyed lookup, and single_static_label(node) is derive

Suggested fix: Extract the counted path as its own fn counted_seek(node, where_clause, stats) -> Option<IndexSeek> spelled with ? (single_static_label(node)?; let pick = best_seek(...)?; seek_narration(...)) and compose counted_seek(...).or_else(|| keyed_label_seek(...)); the nesting and the duplicated cla

finding F-1-2

Comment thread relate/relate-planner/src/rewrite.rs Outdated
let v = v.clone();
let one_var = pairs.iter().all(|(other, _)| *other == v);
if pairs.len() >= 2 && one_var && introduced_unbound(&v) {
let disjuncts: Vec<SmallName> = pairs.into_iter().map(|(_, label)| label).collect();

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] branching (q-missing-model): A bare LabelPredicate has already returned in the branch above, so or_label_predicates can only succeed on a Binary Or with at least two leaves: pairs.first() and pairs.len() >= 2 are cond

Suggested fix: Have or_label_predicates return Option<(SmallName, Vec<SmallName>)> — only ≥2 plain label predicates on one variable, mixed variables declined as its doc states. Then this branch reduces to `if let Some((v, disjuncts)) = or_label_predicates(expr) { if introduced_unbound(&v) { return add_label_di

finding F-1-3

Comment thread relate/relate-ir/src/ast/pattern.rs Outdated
};
let LabelExpr::Or(items) = or else {
return None;
};

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-5): The same LabelExpr is discriminated twice: the outer match already proves or is an Or (the top arm binds self under Or, the And arm only assigns under LabelExpr::Or(_)), so this `let ...

Suggested fix: Let each outer arm yield the Or's item slice directly (LabelExpr::Or(items) => (Vec::new(), items.as_slice()); the And arm captures Some(items.as_slice())), then drop the second match and its unreachable else.

finding F-1-5

np.label_expr
.as_ref()
.and_then(LabelExpr::static_disjunction_arms)
}

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): This derivation (label_expr + static_disjunction_arms) is now spelled three times — this private wrapper, plan_node/seek.rs::keyed_label_seek, and plan_node/warning.rs::scan_index_suggestion —

Suggested fix: Move the accessor onto NodePattern in relate-ir and call it from all three sites; better, return the one typed classification (e.g. enum LabelShape<'a> { Conjunction, Disjunction(DisjunctionArms<'a>), Other }) so binding_arm/scan_ids classify the label criterion once and the conjunction path

finding F-1-6

Comment thread relate/relate/src/plan_node/seek.rs Outdated
label.with_str(|l| {
indexed
.iter()
.any(|pair| pair.label == l && pair.property == key)

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 "the store carries a range index on (label, property)" predicate is already spelled in plan_node/notifications.rs::missing_index_notifications over the same stats.range_indexed_properties() fa

Suggested fix: Put the predicate on the stats contract once (e.g. fn range_index_serves(&self, label: &str, property: &str) -> bool, defaulted over range_indexed_properties()) and call it from both keyed_label_seek and missing_index_notifications.

finding F-1-7

Comment thread relate/relate-planner/src/rewrite.rs Outdated
if n.variable.as_ref() != Some(var) {
continue;
}
let mut arms: Vec<LabelExpr> = match n.label_expr.as_ref() {

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): This is the third copy of the fold's node-targeting scaffolding: skip GPM patterns, walk nodes, match the variable, normalize the node's existing label_expr through static_labels and decline non

Suggested fix: Extract the shared policy (e.g. matched_pattern_nodes(patterns, var) plus static_conjunction_labels(node) -> Option<Vec<SmallName>>) and have both label folds read it; add_label_disjunction then only composes the Or/And expression.

finding F-1-8

return None;
};
Some(vec![(v.clone(), label.clone())])
}

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-5): The doc promises None for "a non-Or leaf" and "mixed variables", but this leaf arm answers Some for any plain label predicate and never compares variables, so the caller compensates with one_var

Suggested fix: Make the recognizer answer the typed fact it documents — Option<(SmallName, Vec<SmallName>)> only for an Or of at least two plain label predicates on one variable, validated at the leaf join — or re-document/re-name it as a flat leaf collector and drop the caller's redundant arity check.

finding F-1-9

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Stellar review (stellar-review skill)

Round 10 · head 43ab7669 · scope: 2/434 units (432 sealed from earlier rounds).

Still open from earlier rounds

  • [Medium] comparison (flag-canonical-dup) F-1-10: relate/relate-executor/src/pattern_walk/candidates/tests.rs:211-226 — This pair is one fixture spelled twice: relate/relate/src/plan_node/fixtures.rs::or_node (lines 33-48) is field-for-field identical apart from variable: Option<&str>, so or_pattern(v, ds) is jus
  • [Medium] branching (q-missing-model) F-2-8: relate/relate-model/src/plan_warning.rs:169-175 — Adding LabelDisjunctionScan here turns suggested_index into a second exhaustive match over the same four-variant vocabulary vocabulary() already owns: message(), name(), and `notification_ki
  • [Medium] branching (q-repeated-conditionals) F-3-1: relate/relate/src/plan_node/seek.rs:157-174 — The two serving policies — every map key must be served, any conjunct key suffices — differ only in which key they pick, yet each spells the same IndexSeek literal, and the !map_keys.is_empty() gu
  • [Medium] branching (std-2) F-3-2: relate/relate/src/plan_node/subject.rs:136-154 — Recognizing one WHERE equality costs three nested ifs plus a let-else continue inside a for inside an if let: the variable-optional wrapper, the conjunct-shape test, and the variable/bound f
  • [Medium] boundaries (std-6) F-3-3: relate/relate/src/plan_node/seek.rs:158-163 — The two key shapes differ only in which key they select; each branch spells the same six-line IndexSeek literal again (operator, line, rows are byte-identical), so the narration's construction
  • [Medium] boundaries (std-5) F-3-4: relate/relate/src/plan_node/warning.rs:119-124 — KeyedEqualities was introduced precisely to keep the two key shapes apart — every map key must be served on every arm, any one WHERE key suffices (subject.rs:161-171) — and this consumer chains them
  • [Medium] boundaries (std-5) F-3-5: relate/relate/src/plan_node/warning.rs:228-232 — The test fabricates the typed artifact — including an empty details line no real narration produces — rather than the derivation the production path uses (seek::index_seek), which is the sole reason
  • [Medium] boundaries (flag-parallel-table) F-3-7: relate/relate-model/src/notification_wire/tests.rs:11-22 — The comment promises a guard the code does not implement: ALL_KINDS and the expected vec![(…)] are two literals in this same test, so a new vocabulary kind omitted from both leaves the lengths e
  • [Low] structure (q-legibility) F-3-8: relate/relate/src/plan_node/subject.rs:100-105 — The F-2-3 fix switched this helper to the canonical relate_ir::pattern_anchor_variables, so the body now yields node, relationship, and subpath variables alike (its own doc now says so) — but the na
  • [Low] branching (std-3) F-3-9: relate/relate/src/plan_node/warning.rs:65-70 — scan_warning already answers Option<PlanWarning>, but the caller opens a second conditional whose only effect is a push, asking the same "is there a warning?" question twice and shadowing the re
  • [Medium] structure (flag-missed-decomposition) F-5-1: relate/relate-executor/src/pattern_walk/candidates/mod.rs:418-423 — binding_arm is now a 98-line body holding three peer strategies, but only one has a home: the OR pass is or_union_candidates over a shared OrCtx, while the ranked-seek pass (lines 405-434) sits
  • [Medium] branching (std-2) F-5-2: relate/relate-executor/src/pattern_walk/candidates/mod.rs:418-425 — A pattern-level label strategy is bolted into the middle of the residual-seek loop as a three-deep sandwich whose continue bypasses the loop's one eligibility→serve→narrow step, so the loop now answ
  • [Medium] branching (q-missing-model) F-5-3: relate/relate-executor/src/pattern_walk/candidates/mod.rs:490-493 — The funnel already classified this pattern's label shape before the seek loop — binding_arm derives label_seekable (397) and the very same disjunction_arms (400) — and the scan tail re-derives b
  • [Medium] branching (q-repeated-conditionals) F-5-4: relate/relate-executor/src/pattern_walk/candidates/mod.rs:527-530 — The two serving branches spell the same lookup block — render the label set, call lookup_nodes_upto, assert the lookup always serves — so the always-served policy is written twice with two different
  • [Medium] boundaries (std-6) F-5-5: relate/relate-executor/src/pattern_walk/candidates/mod.rs:526-531 — The base branch below (lines 540-544) is the same three-step policy spelled again: render the labels, call lookup_nodes_upto, and restate the "non-empty labels are always served" invariant in an `ex
  • [Low] boundaries (std-5) F-5-6: relate/relate-executor/src/pattern_walk/candidates/mod.rs:490-493 — This new branch is the one non-seekable-label path that forces the props thunk (&props()?), so scan_ids's own doc contract two items above — "a caller whose labels are not seekable never evaluat
  • [High] branching (std-0) F-6-1: relate/relate-planner/src/rewrite.rs:247-252 — The disjunction phase is enforced by a second classifier: this guard re-tests or_label_predicates and static_label_disjunction(label_expr) — exactly the two arms fold_conjunct folds as disjuncti
  • [Medium] structure (flag-missed-decomposition) F-6-2: relate/relate-planner/src/rewrite.rs:255-259 — The new order-independence rule has no model of its own: the driver re-derives which conjuncts are disjunction folds (defers_to_disjunction_pass is a second spelling of the two disjunction arms `fol
  • [Medium] boundaries (std-6) F-6-3: relate/relate-planner/src/rewrite.rs:247-259 — fold_conjunct already owns the whole conjunct-shape vocabulary — the static-label conjunction, the label-expression disjunction, the WHERE-spelled Or, and the property equality — yet `defers_to_di
  • [Medium] structure (std-1) F-8-2: relate/relate/src/plan_node/subject.rs:107-128 — The file's name and module doc promise the MATCH narration (pattern text) plus the estimate, but this branch appended the shared keyed-equality recognition (keyed_equalities/KeyedEqualities/`bound

Resolved: F-9-1, F-9-2

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

@oskarhane
oskarhane force-pushed the perf/labs-1083-label-disjunction-seek branch from 8c80bcb to e1d249f Compare November 10, 2026 18:28
};

const LABEL_DISJUNCTION_SCAN_ROW: NotificationRow = NotificationRow {
code: "Relate.Notification.Statement.LabelDisjunctionScan",

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 Testing: The new LabelDisjunctionScan vocabulary row is not added to the drift pin.

Why this matters: notification_wire/tests.rs::vocabulary_matches_the_adr_table_row_for_row is the guard for every kind's code/GQLSTATUS/severity/title/remedy, and its ALL_KINDS array is fixed-size — the test keeps passing without ever pinning the new row, contrary to its own comment ("a kind missing here also misses its expectation").

Suggested fix: add NotificationKind::LabelDisjunctionScan to ALL_KINDS and its matching expected tuple ("Relate.Notification.Statement.LabelDisjunctionScan", "03C94", "INFORMATION", "PERFORMANCE", "Label disjunction scan", the remedy string).

// shared base (a base-carrying shape keeps its labels and its
// `NodeByLabelScan` narration, which names them).
let arms = node.static_disjunction_arms()?;
if !arms.base().is_empty() {

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 Correctness: The base-carrying fold silently loses its MissingIndex notification.

Why this matters: MATCH (p:C) WHERE (p:A OR p:B) AND p.id = 1 now folds to And([Label(C), Or(Label(A), Label(B))]). This early return skips the new scan warning for that shape, while missing_index_notifications also skips it (single_static_label rejects the non-conjunction label_expr). With no index on (C, id) the plan scans :C and emits no diagnostic, where before the fold it emitted MissingIndex for :C(id) (the shape that fires today for MATCH (p:C) WHERE p.id = 1).

Suggested fix: keep a warning path for the base shape — e.g. let missing_index_notifications read the retained node.labels / DisjunctionArms::base instead of single_static_label, or let this arm emit a LabelDisjunctionScan/MissingIndex naming :C(<key>) when the base pair is unindexed.

@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 2: 8 inline finding(s); see summary comment.

Comment thread relate/relate/src/plan_node/subject.rs Outdated
.find(|(name, _)| name == base)
.map_or(Token::Unresolved, |(_, token)| *token);
return stats.label_rows(&(base.clone(), token));
}

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] branching (std-0): The new base-arm estimate re-reads the node's conjunction through static_disjunction_arms() and then recovers the label's token by searching node.labels (lines 196-200) — the list that already hol

Suggested fix: Drop the branch and read the retained conjunction once: let [(label, token)] = node.labels.as_slice() else { return None; }; then stats.label_rows(&(label.clone(), *token)). The single-static-label arm and the fold's base arm become the same estimate, deleting the arms call, the name→token re-fi

finding F-2-1

where_clause: Option<&Expr>,
stats: &dyn PlanStats,
seek_engaged: bool,
) -> Vec<PlanWarning> {

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] branching (flag-one-off-bool): The new bool is a lossy projection of the Option<IndexSeek> the same ClauseNode holds one line away: the estimate is threaded the artifact (seek.as_ref().and_then(|seek| seek.rows)) while the wa

Suggested fix: Pass seek: Option<&IndexSeek> into match_warnings/scan_warning and let the warning read the serving fact there (or derive the warning beside index_seek, where the arms and the every-arm-serves test already live), so the operator name, the estimate, and the warning suppression all read one ar

finding F-2-2

.iter()
.flat_map(relate_ir::pattern_node_anchor_variables)
.collect()
}

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 doc calls this "the one spelling of the variables that bind inside this clause", but pattern_node_anchor_variables yields node variables only while the canonical `relate_ir::pattern_anchor_varia

Suggested fix: Enumerate the clause's bindings with relate_ir::pattern_anchor_variables (the canonical "every variable one pattern binds") instead of pattern_node_anchor_variables, so relationship and subpath variables are filtered too.

finding F-2-3

.iter()
.map(|label| format!(":{label}({key})"))
.collect::<Vec<_>>()
.join(", ");

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): IndexDef::index_text is the catalog's one spelling of the :Label(property) schema text — its doc explicitly says "never a per-site format!" — and the AllNodesScan suggestion already renders th

Suggested fix: Reuse the canonical schema text: extract a free index_schema_text(label, property) in relate-catalog (with IndexDef::index_text delegating to it) and build each suggested pair through it.

finding F-2-4

Comment thread relate/relate/src/plan_node/seek.rs Outdated
.all(|mut arm| arm.any(|label| label.with_str(|l| stats.range_index_serves(l, &key))));
if !every_arm_serves {
continue;
}

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-5): equality_filter_keys flattens the pattern map's keys and the WHERE equality keys into one list, but the executor gates them differently: a WHERE conjunct becomes its own Seek (one served key suffi

Suggested fix: Keep the two key shapes distinct (e.g. a typed KeyedEqualities { map_keys, conjunct_keys }) and require every map key to be served on every arm before narrating; WHERE-conjunct keys stay any-key.

finding F-2-5

return Ok(graph
.lookup_nodes(&labels, &props)
.expect("the base labels are non-empty: lookup_nodes always serves"));
}

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 (flag-busy-function): scan_ids used to be the one-label-conjunction scan; it now hosts three shape policies inline (conjunction lookup, per-arm property union, conjunction-base scan) with nested branches and two render-t

Suggested fix: Give the disjunction shape its own helper — scan_disjunction_arms(graph, arms, props) beside seek_union — and leave scan_ids the three-branch dispatch over the pattern's shape: conjunction lookup, disjunction helper, all-nodes scan.

finding F-2-6

Comment thread relate/relate/src/plan_node/seek.rs Outdated
}
}
keys
}

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 (std-6): This recognizer declares itself shared ("the narration's index-pair check and the scan warning's suggestion") and is now read from two sibling submodules, but it lives inside one consumer's file, so `

Suggested fix: Move equality_filter_keys and its bound_reads_pattern_var helper beside the other MATCH-shape recognizers (subject.rs's single_static_label/clause_node_variables), or into a shared plan_node shape module, and have both keyed_label_seek and scan_warning read it from there.

finding F-2-7

PlanWarning::LabelDisjunctionScan { indexes } => Some(indexes.as_str()),
PlanWarning::EstimationMiss | PlanWarning::CartesianProduct => None,
}
}

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] branching (q-missing-model): Adding LabelDisjunctionScan here turns suggested_index into a second exhaustive match over the same four-variant vocabulary vocabulary() already owns: message(), name(), and `notification_ki

Suggested fix: Give VocabularyRow the payload (e.g. payload: Option<fn(&PlanWarning) -> &str>, or return Option<&str> beside the row) and derive suggested_index and the parenthesized tail of message() from vocabulary(), so one match owns name, text, notification kind, and payload presence.

finding F-2-8

@oskarhane
oskarhane force-pushed the perf/labs-1083-label-disjunction-seek branch from e1d249f to 192c0d5 Compare November 10, 2026 19:05
@oskarhane

Copy link
Copy Markdown
Contributor Author

Round-3 notes: (1) the carried F-1-8 ("the third copy of the fold's node-targeting scaffolding") is a stale re-report — the scaffolding was extracted as fold_target_nodes in relate/relate-planner/src/rewrite.rs in round 2 (both label folds and the doc reference read it; add_prop keeps its own walk because it also targets relationships, stated in its comment). (2) F-2-8 (plan_warning.rs's suggested_index as a second exhaustive match) is deliberately kept and ticketed: both matches are compile-forced on a new variant — a fourth variant cannot compile without choosing its row AND its payload arm, so the two cannot drift silently; the payload-extractor redesign trades a compile-forced match for wildcard-bearing accessors. Both are on the review-tasks ticket (LABS-1333). Three stellar fix rounds are now spent; anything further batches to the ticket per the bounded loop.

seek: &Seek,
arms: &DisjunctionArms<'_>,
) -> Result<Option<Vec<NodeId>>> {
let mut served: Vec<Vec<NodeId>> = Vec::with_capacity(arms.len());

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] Unbounded memory (availability): seek_union retains every arm's full posting in served until all arms are served, so peak memory is O(disjuncts × posting size) instead of O(distinct ids).

Why this matters: a single ≤4 MiB statement (MATCH (p) WHERE (p:A OR p:A OR … ) AND p.name CONTAINS 'a') folds to thousands of identical arms; each Seek::serve returns a whole TEXT/RANGE posting and line 82 keeps it live, so a read-only query can materialise gigabytes and OOM the Bolt/HTTP process — the per-arm Vecs bypass the statement charge that TieredWordSet applies to the dedup set.

Suggested fix: fold each arm into the dedup set as it arrives instead of collecting it (for id in ids.into_ids() { if seen.insert(id as u64)? { out.push(id) } }), and cap the folded disjunct count.

/// allocation-free. `NodeId` is `i64` and the set knows raw `u64` words:
/// the bit-pattern cast is injective over the whole `i64` range, so
/// distinct ids stay distinct words whatever their sign.
fn union_dedup(served: impl Iterator<Item = Vec<NodeId>>) -> Result<Vec<NodeId>> {

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] Ownership & Borrowing: union_dedup re-implements the ascending id-list union that union_ids already owns, and the dedup/sort it adds is redundant: every arm answer reaching it is already ascending and deduplicated (Seek::serve via merge_string_lookup and graph.lookup_nodes both sort and dedup — this module states that contract at the OR-pass comment).

Why this matters: the tiered set charges the workspace, so a pure candidate-id union can now fail the query with a capacity error the existing merge cannot hit, and large unions pay one hash insert per id plus an O(n log n) re-sort instead of the O(n+m) merge used by the OR-union pass in the same file.
Suggested fix: fold the canonical merge over the arms, e.g. served.fold(Vec::new(), union_ids) (and drop the now-unneeded Result/set from the call chain).

let label_seekable = label_index_seekable(np);
// The disjunction fold's per-arm views (LABS-1083): `None` for every
// shape the single keyed arm or the scan tail already serves.
let disjunction_arms = np.static_disjunction_arms();

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] Ownership & Borrowing: np.static_disjunction_arms() runs on every candidate evaluation and heap-allocates its base/disjunct Vecs before it can decline. Every And-shaped label expression — a multi-label pattern, or any pattern whose WHERE label predicate was folded in (MATCH (n) WHERE n:Person becomes And([Label(Person)])) — pays that allocation per candidate and drops the None.

Why this matters: this is the node funnel's per-candidate hot path and those shapes had no allocation here before; the unserved disjunction shapes additionally re-run the classifier inside scan_ids (np.static_disjunction_arms() again), so the view is built twice per candidate on the scan tail.
Suggested fix: gate the derivation on a non-allocating shape check (or thread the derived view into scan_ids) so And-without-Or patterns never allocate here.

@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 3: 7 inline finding(s); see summary comment.

});
}
}
None

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] branching (q-repeated-conditionals): The two serving policies — every map key must be served, any conjunct key suffices — differ only in which key they pick, yet each spells the same IndexSeek literal, and the !map_keys.is_empty() gu

Suggested fix: Pick the key once, then construct once: let key = keys.map_keys.first().filter(|_| keys.map_keys.iter().all(|key| every_arm_serves(key))).or_else(|| keys.conjunct_keys.iter().find(|key| every_arm_serves(key)))?; followed by one `Some(IndexSeek { operator: NODE_BY_LABEL_SEEK, line: keyed_seek_line(

finding F-3-1

}
}
}
}

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] branching (std-2): Recognizing one WHERE equality costs three nested ifs plus a let-else continue inside a for inside an if let: the variable-optional wrapper, the conjunct-shape test, and the variable/bound f

Suggested fix: Make the conjunct stream a pipeline: `where_conjuncts_of(where_clause).iter().filter_map(|conjunct| match conjunct { Expr::Binary { op: BinaryOp::Eq, left, right } => relate_ir::orient_side(relate_ir::var_prop, left, right), _ => None }).filter(|((conjunct_var, _), bound)| node.variable.as_ref() ==

finding F-3-2

operator: NODE_BY_LABEL_SEEK,
line: keyed_seek_line(var.as_deref(), &arms, key),
rows: None,
});

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 two key shapes differ only in which key they select; each branch spells the same six-line IndexSeek literal again (operator, line, rows are byte-identical), so the narration's construction

Suggested fix: Select the winning key once — a map key only when every map key serves, else the first serving conjunct key — then build the single IndexSeek { operator: NODE_BY_LABEL_SEEK, line: keyed_seek_line(var.as_deref(), &arms, key), rows: None } after the selection.

finding F-3-3

Comment thread relate/relate/src/plan_node/warning.rs Outdated
.iter()
.chain(&keys.conjunct_keys)
.next()?
.clone();

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-5): KeyedEqualities was introduced precisely to keep the two key shapes apart — every map key must be served on every arm, any one WHERE key suffices (subject.rs:161-171) — and this consumer chains them

Suggested fix: Move the suggestion policy onto KeyedEqualities — a method answering the keys a per-arm serve requires (every map key when the map is non-empty, else one conjunct key) — and have scan_warning render that method's answer through relate_catalog::index_schema_text instead of re-flattening the two

finding F-3-4

operator: super::super::seek::NODE_BY_LABEL_SEEK,
line: String::new(),
rows: None,
};

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-5): The test fabricates the typed artifact — including an empty details line no real narration produces — rather than the derivation the production path uses (seek::index_seek), which is the sole reason

Suggested fix: Derive the value: let narrated = super::super::seek::index_seek(&patterns, Some(&where_eq), &served).expect("the served union narrates a seek");, pass Some(&narrated), and drop NODE_BY_LABEL_SEEK's pub(super) (no reader outside seek.rs remains).

finding F-3-5

.contains("the equality predicate on id filters :C"),
"the folded base keeps its MissingIndex diagnosis: {:?}",
explained.notifications()
);

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-5): The test's claim is typed — the base-carrying fold keeps its MissingIndex diagnosis — yet it is checked only through a substring of the rendered description, so nothing pins the kind: any single not

Suggested fix: Assert the typed fact first — assert_eq!(explained.notifications()[0].kind(), NotificationKind::MissingIndex) (or its code() == "Relate.Notification.Statement.MissingIndex") — and keep the description substring only for the interpolated label/property.

finding F-3-6

NotificationKind::MissingIndex,
NotificationKind::EagerAggregation,
NotificationKind::EstimationMiss,
NotificationKind::LabelDisjunctionScan,

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 (flag-parallel-table): The comment promises a guard the code does not implement: ALL_KINDS and the expected vec![(…)] are two literals in this same test, so a new vocabulary kind omitted from both leaves the lengths e

Suggested fix: Collapse the two lists into one authored table — (NotificationKind, code, gql_status, severity, category, title, remedy) rows — asserted row by row against the kind's own accessors (which also gives per-row failure messages), and make completeness compiler-forced rather than length-coincidental: d

finding F-3-7

@oskarhane
oskarhane marked this pull request as ready for review November 10, 2026 19:18
@oskarhane
oskarhane force-pushed the perf/labs-1083-label-disjunction-seek branch from 192c0d5 to 53da831 Compare November 10, 2026 19:18
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Spec-harness coverage — 🟡

  • 🟡 spec coverage 98.23% — 596 genuine failures (1.77% of the executed scenarios)
  • scenarios run: 33738 (passed 33142, failed 596)
  • bands: 🟢 zero failures · 🟡 failure share ≤ 10% · 🔴 beyond (ADR-0482 §4 — the light never fails the build)
  • suite runtime: 1m 43s
  • neo4j_expected_fail (not counted): 314
  • nondeterministic (not counted): 2
  • skipped (not counted): 2323
  • harness ref: e6b894b9fceb326eea8d63eaf763151114dafec5
failure category count
error-class-mismatch 236
missing-validation 105
result-mismatch 95
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

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 4203.45 +264.89 (+6.7%) ok
p99 (worst: counterparties) 7.45 ms 7.51 ms +0.07 ms (+0.9%) ok
logical bytes 17,344,481 17,322,333 -22,148 (-0.1%) ok
Per-use-case p99 latency
Use case ops Baseline p99 PR p99 Δ Status
p2p_transfer 3,826 8.04 ms 7.96 ms -0.08 ms (-1.0%) ok
payroll_scatter 1,099 17.85 ms 15.35 ms -2.50 ms (-14.0%) ok
onboard_customer 848 8.53 ms 7.58 ms -0.95 ms (-11.2%) ok
mule_scatter 838 14.80 ms 13.82 ms -0.98 ms (-6.6%) ok
layering_cycle 848 15.10 ms 11.19 ms -3.91 ms (-25.9%) ok
recent_transfers 2,202 7.65 ms 7.19 ms -0.46 ms (-6.1%) ok
customer_portfolio 1,481 7.37 ms 6.90 ms -0.47 ms (-6.4%) ok
outgoing_volume 1,173 7.48 ms 6.53 ms -0.95 ms (-12.7%) ok
detect_fanout 842 25.78 ms 18.65 ms -7.13 ms (-27.6%) ok
detect_cycle 823 7.55 ms 6.62 ms -0.94 ms (-12.4%) ok
activity_page 1,125 7.48 ms 7.02 ms -0.47 ms (-6.2%) ok
search_customer 822 7.84 ms 7.62 ms -0.23 ms (-2.9%) ok
counterparties 1,082 7.45 ms 7.51 ms +0.07 ms (+0.9%) ok
payment_path 816 7.47 ms 7.04 ms -0.43 ms (-5.8%) ok
amount_band 817 7.30 ms 6.84 ms -0.46 ms (-6.4%) ok
flag_account 678 8.21 ms 7.15 ms -1.06 ms (-12.9%) ok
reverse_last_out 680 8.04 ms 7.59 ms -0.45 ms (-5.6%) 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 598.01 +24.50 (+4.3%) ok
p99 (worst: group_roster) 7.72 ms 7.98 ms +0.27 ms (+3.5%) ok
logical bytes 7,167,614 7,166,190 -1,424 (-0.0%) ok
Per-use-case p99 latency
Use case ops Baseline p99 PR p99 Δ Status
provision_user 1,373 11.00 ms 10.32 ms -0.68 ms (-6.2%) ok
add_to_group 1,775 18.57 ms 17.27 ms -1.30 ms (-7.0%) ok
grant_role 1,079 18.52 ms 17.68 ms -0.83 ms (-4.5%) ok
attach_device 907 18.88 ms 17.28 ms -1.59 ms (-8.4%) ok
nested_grant 736 19.41 ms 17.47 ms -1.94 ms (-10.0%) ok
effective_access 2,173 25.25 ms 20.14 ms -5.11 ms (-20.2%) ok
org_walk 1,387 19.94 ms 17.95 ms -1.99 ms (-10.0%) ok
optional_manager 1,312 20.00 ms 18.95 ms -1.05 ms (-5.2%) ok
detect_nested_admin 810 19.97 ms 18.65 ms -1.33 ms (-6.7%) ok
detect_sod 817 19.60 ms 16.59 ms -3.01 ms (-15.3%) ok
stale_grants 827 15.06 ms 11.24 ms -3.82 ms (-25.4%) ok
search_directory 1,147 10.91 ms 10.08 ms -0.83 ms (-7.6%) ok
group_roster 1,047 7.72 ms 7.98 ms +0.27 ms (+3.5%) ok
access_review 801 20.02 ms 18.06 ms -1.96 ms (-9.8%) ok
reporting_path 794 30.98 ms 27.01 ms -3.97 ms (-12.8%) ok
disable_user 644 19.50 ms 18.04 ms -1.46 ms (-7.5%) ok
add_alias 710 19.99 ms 18.28 ms -1.71 ms (-8.6%) ok
revoke_membership 674 8.10 ms 7.99 ms -0.11 ms (-1.4%) ok
detach_device 538 14.79 ms 10.59 ms -4.20 ms (-28.4%) ok
clear_expiry 449 17.39 ms 15.12 ms -2.26 ms (-13.0%) ok

@github-actions

github-actions Bot commented Nov 10, 2026 •

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 19.23 MB, ratio 0.874x.

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 34.05 MB, ratio 1.001x.

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 34.00 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.

@github-actions

github-actions Bot commented Nov 10, 2026 •

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.26 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.10 MB, attributed RSS 36.02 MB, ratio 1.258x.

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.20 MB, attributed RSS 36.16 MB, ratio 1.206x.

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 0.73 MB, attributed RSS 32.02 MB, ratio 1.020x.

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

@oskarhane

Copy link
Copy Markdown
Contributor Author

Fix-budget note (same shape as #146): three stellar fix rounds are spent — the local round, CI round 2, and CI round 3 (which landed the single_static_label base widening, the typed keyed_equalities, the canonical enumerator, index_schema_text, scan_disjunction_arms, and the vocabulary pin). Round 4 on the rebased head reviews 0 new units and carries only the round-3 verdict items and the ticketed findings — all polish-class (duplicated narration literals, nested recognizers, test-pin strength) — batched to the review-tasks ticket (LABS-1333) per the bounded loop. rust-review and security-review pass on this head; the full CI matrix is running.

@oskarhane
oskarhane force-pushed the perf/labs-1083-label-disjunction-seek branch from 53da831 to ba68d32 Compare November 10, 2026 19:47

@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 5: 5 inline finding(s); see summary comment.

if let Some(ids) = seek_union(graph, seek, arms)? {
return Ok(ids);
}
continue;

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 (flag-missed-decomposition): binding_arm is now a 98-line body holding three peer strategies, but only one has a home: the OR pass is or_union_candidates over a shared OrCtx, while the ranked-seek pass (lines 405-434) sits

Suggested fix: Build the shared evaluation context once, before the ranked pass, and extract the pass as or_union_candidates' peer — fn ranked_serve(ctx: &OrCtx<'_>, var: &SmallName, conjuncts: &[Expr], arms: Option<&DisjunctionArms<'_>>) -> Result<Option<ServedIds>> — so both serve passes narrow at the one `S

finding F-5-1

}
continue;
}
}

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] branching (std-2): A pattern-level label strategy is bolted into the middle of the residual-seek loop as a three-deep sandwich whose continue bypasses the loop's one eligibility→serve→narrow step, so the loop now answ

Suggested fix: Give the label view its own serve step (a serve_seek/LabelView::serve beside seek_union and scan_disjunction_arms) that owns the union-vs-single choice, eligibility, serve, and narrowing, so the loop body is a single if let Some(ids) and the special case lives once, not nested in the share

finding F-5-2

} else if let Some(arms) = np.static_disjunction_arms() {
if let Some(ids) = scan_disjunction_arms(graph, &arms, &props()?, cap)? {
return Ok(ids);
}

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] branching (q-missing-model): The funnel already classified this pattern's label shape before the seek loop — binding_arm derives label_seekable (397) and the very same disjunction_arms (400) — and the scan tail re-derives b

Suggested fix: Derive one label view at the funnel entry (conjunction labels / disjunction arms / other) and thread it to the seek loop and the scan tail; scan_ids then matches the view instead of recomputing it (and no longer needs np just for the label facts).

finding F-5-3

let labels: Vec<String> = arm.map(|label| label.to_string()).collect();
graph
.lookup_nodes_upto(&labels, props, cap)
.expect("an arm's labels are non-empty: lookup_nodes always serves")

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] branching (q-repeated-conditionals): The two serving branches spell the same lookup block — render the label set, call lookup_nodes_upto, assert the lookup always serves — so the always-served policy is written twice with two different

Suggested fix: Select the label sets first (per arm when equalities exist, the base alone otherwise) and serve them through one always-served lookup helper; the function then states which sets are scanned and the invariant exists once.

finding F-5-4

graph
.lookup_nodes_upto(&labels, props, cap)
.expect("an arm's labels are non-empty: lookup_nodes always serves")
}))

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 base branch below (lines 540-544) is the same three-step policy spelled again: render the labels, call lookup_nodes_upto, and restate the "non-empty labels are always served" invariant in an `ex

Suggested fix: Extract one always-served lookup helper — e.g. fn label_lookup(graph: &ExecGraph<'_>, labels: impl Iterator<Item = &SmallName>, props: &BTreeMap<String, Value>, cap: Option<usize>) -> Vec<NodeId> — that renders the labels and states the non-empty-labels invariant once; the per-arm branch maps it t

finding F-5-5

{
return add_labels(patterns, v, &labels);
}
if let Some(disjuncts) = static_label_disjunction(label_expr) {

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] Behavior: conjunct order decides whether a label disjunction keeps a companion label's narrowing — WHERE (p:A OR p:B) AND p:C now degrades to an all-nodes scan.

Why this matters: fold_where visits conjuncts left to right, so the Or folds into the pattern's label_expr first; add_labels then sees a non-conjunctive label_expr and declines, leaving p:C in the WHERE. The pattern carries a bare Or (no base), so scan_disjunction_arms — no base, no property map — returns None and scan_ids falls through to graph.all_node_ids(). Before this change p:C folded and the clause ran as NodeByLabelScan(:C); the mirror order (p:C AND (p:A OR p:B)) still gets the base-carrying And([C, Or([A, B])]) scan, so the cost depends on how the predicate is written.

Suggested fix: fold plain-label conjuncts before disjunctions (two passes over the conjunct list), or let add_labels merge a later label into a folded disjunction's base as And([C, Or([A, B])]).

@oskarhane
oskarhane force-pushed the perf/labs-1083-label-disjunction-seek branch from ba68d32 to 96085f5 Compare November 10, 2026 20:25

@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 6: 3 inline finding(s); see summary comment.

|| matches!(
conjunct,
Expr::LabelPredicate { label_expr, .. }
if static_label_disjunction(label_expr).is_some()

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[High] branching (std-0): The disjunction phase is enforced by a second classifier: this guard re-tests or_label_predicates and static_label_disjunction(label_expr) — exactly the two arms fold_conjunct folds as disjuncti

Suggested fix: Make the label folds compose instead of ordering them: one merge step on the node (fn merge_label_constraint(n: &mut NodePattern, conjunction: &[SmallName], disjunction: Option<&[SmallName]>)) reads the node's current (base conjunction, Option<Or>) from label_expr/labels, keeps the existing

finding F-6-1

defers_to_disjunction_pass(conjunct)
|| !fold_conjunct(patterns, conjunct, bound, introduced)
});
conjuncts.retain(|conjunct| !fold_conjunct(patterns, conjunct, bound, introduced));

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 (flag-missed-decomposition): The new order-independence rule has no model of its own: the driver re-derives which conjuncts are disjunction folds (defers_to_disjunction_pass is a second spelling of the two disjunction arms `fol

Suggested fix: Give the fold a family model: fold_conjunct answers the family it folded (e.g. Option<FoldFamily> — LabelConjunction / LabelDisjunction / Property), and fold_where drives an explicit ordered fold — partition the conjuncts by family once, fold each family in the documented order, and collect th

finding F-6-2

defers_to_disjunction_pass(conjunct)
|| !fold_conjunct(patterns, conjunct, bound, introduced)
});
conjuncts.retain(|conjunct| !fold_conjunct(patterns, conjunct, bound, introduced));

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): fold_conjunct already owns the whole conjunct-shape vocabulary — the static-label conjunction, the label-expression disjunction, the WHERE-spelled Or, and the property equality — yet `defers_to_di

Suggested fix: Split fold_conjunct by fold family — fold_conjunction_conjunct (the static_labels arm plus eq_prop) and fold_disjunction_conjunct (the static_label_disjunction/or_label_predicates arms) — and run one retain per family in the required order. The ordering then reads as two named passes

finding F-6-3

/// after the fold: the `:C` population is still the scan, LABS-1083) —
/// the only shape a single `(label, property)` index serves, and the
/// one derivation the estimate and the `MissingIndex` notification
/// share. A bare `Or` over no base answers none: its scan is the whole

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 Correctness: A folded bare label disjunction with no equality predicate (MATCH (p) WHERE p:Model OR p:Source) now narrates NodeByLabelScan (p) although the executor scans every node, and the previous AllNodesScan warning no longer fires.

Why this matters: for this shape scan_ids takes the disjunction branch with an empty base and empty property map, scan_disjunction_arms returns None, and the funnel answers with graph.all_node_ids() — but is_all_nodes_scan only tests labels/label_expr, so fused_subject names a label scan that never runs, the details render (p) (the Or is dropped because the disjuncts live in label_expr, not labels), and scan_warning returns None (no key to suggest), leaving the plan silent about a whole-store scan that used to be reported as AllNodesScan.

Suggested fix: give this shape an honest narration — treat a bare Or with an empty base as an all-nodes scan for operator naming, or always emit the LabelDisjunctionScan warning for it and render the label expression in push_node — plus an EXPLAIN test for the no-equality disjunction.

let label_seekable = label_index_seekable(np);
// The disjunction fold's per-arm views (LABS-1083): `None` for every
// shape the single keyed arm or the scan tail already serves.
let disjunction_arms = np.static_disjunction_arms();

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 Performance: np.static_disjunction_arms() is now called on every funnel invocation, and its And arm allocates the base Vec before discovering that the expression carries no Or.

Why this matters: binding_arm runs once per row for a non-bound start element (for example MATCH (a) MATCH (b:Person:Employee)), so an ordinary multi-label conjunction — the common LabelExpr::And shape that can never produce disjunction arms — pays a heap allocation plus a full child scan per row, on the executor's hottest node-matching path.

Suggested fix: derive the arms only when the label expression is not a static conjunction, e.g. let disjunction_arms = if label_seekable { None } else { np.static_disjunction_arms() };, or scan And for the single Or before building base.

@oskarhane
oskarhane force-pushed the perf/labs-1083-label-disjunction-seek branch from 96085f5 to 49e0073 Compare November 10, 2026 20:49
.iter()
.any(|indexed| indexed.label == label && indexed.property == property)
{
if stats.range_index_serves(&label, &property) {

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] Ownership & Borrowing: range_index_serves re-materializes the store's whole index list on every call, and this loop calls it per property pair.

Why this matters: the removed let indexed = stats.range_indexed_properties(); hoisted the list once per missing_index_notifications call, while the new default helper (stats.rs:46) rebuilds a Vec of owned Strings and locks the catalog (range_indexed_node_properties) on every call, so P equality pairs × M indexes now pay P×M clones/locks; every_arm_serves in plan_node/seek.rs repeats the same pattern per arm per key.
Suggested fix: fetch the pair list once per clause and test it, or add a slice-taking range_index_serves_in(&indexed, label, property) both loops reuse, so the policy stays single-spelled without re-materializing.

@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 7: 8 inline finding(s); see summary comment.

let keys = super::subject::keyed_equalities(node, where_clause, pattern_vars);
let Some(key) = keys.map_keys.iter().chain(&keys.conjunct_keys).next() else {
return all_nodes_scan();
};

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[High] structure (std-6): The keyless fallback answers AllNodesScan from a second derivation of the scan shape, while the one derivation this branch widened for exactly that warning — subject::is_all_nodes_scan, with its `

Suggested fix: Answer the all-nodes case through super::subject::is_all_nodes_scan(node) in both places this function spells it (the label-less branch and the keyless fallback), leaving scan_warning to own only the disjunction suggestion; the scan-shape fact then has the one home both functions' docs already c

finding F-7-1

Comment thread relate/relate/src/plan_node/subject.rs Outdated
!expr.is_static_conjunction()
&& node
.static_disjunction_arms()
.is_some_and(|arms| arms.base().is_empty() && node.properties.is_none())

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[High] branching (std-2): The new bare-Or branch answers true for a node that still carries a label expression, but this predicate is also the estimate's unfiltered-endpoint gate (node_is_unfiltered, subject.rs:333): aft

Suggested fix: Split the two questions: keep the all-nodes scan shape for the operator naming and the warning, and give the estimate its own 'no labels, no properties, no predicates' derivation (or make node_is_unfiltered reject any label_expr), so a later disjunction shape cannot widen the estimate.

finding F-7-2

Comment thread relate/relate/src/plan_node/subject.rs Outdated
!expr.is_static_conjunction()
&& node
.static_disjunction_arms()
.is_some_and(|arms| arms.base().is_empty() && node.properties.is_none())

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] branching (q-missing-model): The all-nodes answer tests whether the map is present while the funnel's scan_disjunction_arms tests whether the evaluated map is empty, so a written empty map (MATCH (p {}) is legal and lower

Suggested fix: Classify the pattern's map once — no map or a literal empty map is the no-equals all-nodes shape, a keyed map is the per-arm shape — and have the operator naming and the warning read that classification instead of properties.is_none().

finding F-7-3

let keys = super::subject::keyed_equalities(node, where_clause, pattern_vars);
let Some(key) = keys.map_keys.iter().chain(&keys.conjunct_keys).next() else {
return all_nodes_scan();
};

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] branching (q-missing-model): The fallback infers 'the scan answers every node' from an empty eligible-literal-key list, but that is not the funnel's gate: a whole-map $param (MATCH (p $props) WHERE p:A OR p:B) or a map whose

Suggested fix: Fall back to AllNodesScan only when the pattern has no map to key on at all — not when the keys are unnamed ($param) or disqualified — and read the bare-Or shape from the one scan-shape derivation instead of re-deciding it here; otherwise stay silent rather than claim an every-node scan.

finding F-7-4

Comment thread relate/relate/src/plan_node/subject.rs Outdated
match node.label_expr.as_ref() {
None => true,
Some(expr) => {
!expr.is_static_conjunction()

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): static_disjunction_arms already answers None for every static conjunction — Label falls to its _ arm and a plain And is declined before the base list is built — so this conjunct re-tests the

Suggested fix: Drop the conjunct and let the classifier decide: match node.static_disjunction_arms() { Some(arms) => arms.base().is_empty() && node.properties.is_none(), None => node.label_expr.is_none() }.

finding F-7-5

Comment thread relate/relate/src/plan_node/subject.rs Outdated
!expr.is_static_conjunction()
&& node
.static_disjunction_arms()
.is_some_and(|arms| arms.base().is_empty() && node.properties.is_none())

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 doc calls this the "one derivation the operator naming and the AllNodesScan warning detection share", but scan_warning now decides the same shape from keyed_equalities while this arm reads t

Suggested fix: Decide the folded arm through the same equality recognition keyed_equalities owns (an absent, empty, or equality-free map), or better, derive one scan-shape value that both fused_subject's naming and scan_warning read, so the operator name and its warning cannot diverge.

finding F-7-6

assert!(
explained.notifications()[0]
.description()
.contains("the scan matches every node"),

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-5): The claim is typed — the AllNodesScan notification fires — but it is checked as a whole-list length plus a substring of the rendered description, so any kind carrying that sentence passes and an add

Suggested fix: Assert the typed kind through the canonical helper: assert!(has_notification(&explained, relate_model::wire::NotificationKind::AllNodesScan)), or compare kinds(&explained) with vec![NotificationKind::AllNodesScan]; drop the length and description-substring checks.

finding F-7-7

// ADR-0363's warning, whatever predicates filter it.
if node.labels.is_empty() && node.label_expr.is_none() {
return all_nodes_scan();
}

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] comparison (flag-canonical-dup): is_all_nodes_scan (subject.rs:91-104) is documented as "the one derivation the operator naming and the AllNodesScan warning detection share", yet this warning never reads it: the old helper body i

Suggested fix: Make is_all_nodes_scan the one fact both consumers read: scan_warning should take its early return and its keyless fallthrough from that predicate and keep the keyed-equality chain only for selecting the LabelDisjunctionScan payload; settle the keyless-map case once inside that predicate (a ma

finding F-7-8

@oskarhane
oskarhane force-pushed the perf/labs-1083-label-disjunction-seek branch from 49e0073 to 9159c25 Compare November 10, 2026 21:36
Comment thread relate/relate-ir/src/ast/pattern.rs Outdated
/// consumers read this.
///
/// The views borrow: arm *i* is
/// [`DisjunctionArms::arm`](DisjunctionArms::arm) — the base's names

@github-actions github-actions Bot Nov 10, 2026 •

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: the intra-doc link names DisjunctionArms::arm, but the method is arms.

Why this matters: rustdoc cannot resolve the target, so the public LabelExpr::static_disjunction_arms docs carry a broken cross-reference.
Suggested fix: point the link at DisjunctionArms::arms (the iterator method).

@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 8: 4 inline finding(s); see summary comment.

Comment thread relate/relate/src/plan_node/subject.rs Outdated
&& map_keys_nothing(node)
&& keyed_equalities(node, where_clause, pattern_vars)
.conjunct_keys
.is_empty()

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[High] branching (std-2): The round-8 fix folds the disjunction warning's keyed-WHERE selection into the predicate the operator naming reads: conjunct_keys.is_empty() is the warning's "is there a keyed equality to suggest an

Suggested fix: Take the keyed-WHERE term out of the naming's predicate: is_all_nodes_scan keeps the classic every-node shape and the bare-Or-with-no-map shape, while scan_warning adds the keyed-WHERE branch that selects LabelDisjunctionScan (or return a scan-shape value whose naming and warning consumers e

finding F-8-1

None => false,
},
}
}

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 (std-1): The file's name and module doc promise the MATCH narration (pattern text) plus the estimate, but this branch appended the shared keyed-equality recognition (keyed_equalities/KeyedEqualities/`bound

Suggested fix: Split along the two self-contained seams instead of letting the file accrete: move the pure rendering (pattern_text(s), push_element/push_node/push_rel/push_quantifier/push_name) to plan_node/pattern_text.rs, and the pattern-shape plus keyed-equality recognition (lone_node/`lone_node

finding F-8-2

where_clause: Option<&Expr>,
optional: bool,
seek: Option<&IndexSeek>,
) -> (Cow<'static, str>, String) {

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-5): Two mutually exclusive Options now decide the subject: where_clause is read only by the fused path and the seek path never looks at it, so the real invariant (exactly one source picks the operator

Suggested fix: Make the source a typed choice instead of two Options: enum SubjectSource<'a> { Fused { where_clause: Option<&Expr> }, Seek(&'a IndexSeek) } and match_subject(patterns, source, optional) (or split out a seek_subject entry point the caller of a narrated seek uses directly). The sealed-seek path

finding F-8-3

explained.notifications()[0].description(),
"the disjunction scan answers per label; consider the property index \
(:Model(id), :Source(id))"
);

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): After pinning the kind with has_notification, the payload is read off notifications()[0] — a positional assumption over a mixed-kind list, so the assertion checks whichever notification happens to

Suggested fix: Read the payload through the typed accessor: notifications_of_kind(&explained, NotificationKind::LabelDisjunctionScan)[0].description(), or compare the collected descriptions as a Vec<&str> so the count and the element are both typed.

finding F-8-4

@oskarhane
oskarhane force-pushed the perf/labs-1083-label-disjunction-seek branch from 9159c25 to 8547a26 Compare November 10, 2026 22:25
// Each arm IS a static conjunction by construction of the arm
// classifier, so the arm's own label criterion passes; the
// crossover prices the arm's own scan population.
if !seek.servable(graph, &labels, true) {

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: the union arm's per-arm crossover gate prices the window against the arm's own population, while the funnel's fallback on a decline is the base label scan (the all-nodes scan for a bare Or).

Why this matters: for MATCH (p:C) WHERE (p:A OR p:B) AND p.age > 5 with a range index on (C, age), the fold makes the label expression non-conjunctive, so the comparison is routed here; a 500-id window over 1M :C rows is gated against min(|C|, |A|) (say 100), declines, and scan_ids then scans all 1M :C rows — before the fold the same seek was priced against :C and served from the (C, age) index, and the plan still narrates that counted seek (ADR-0486's "never claim a seek the funnel would decline").
Suggested fix: price each arm's window against the population the funnel actually falls through to (the base conjunction, or no gate when there is no base), not the arm's own labels.

@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 9: 2 inline finding(s); see summary comment.

served.notifications().is_empty(),
"a served union scans nothing: {:?}",
served.notifications()
);

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] comparison (std-6): The claim is kind-scoped — the served union emits no LabelDisjunctionScan — but it is checked as whole-list emptiness, while the other kind-scoped negatives in this file assert through the shared he

Suggested fix: Assert the typed absence: assert!(!has_notification(&served, NotificationKind::LabelDisjunctionScan), "a served union scans nothing: {:?}", served.notifications()); — keep the whole-list dump only as the failure message.

finding F-9-1

/// its WHERE-aware refinement must not touch the classic warning.
pub(super) fn is_label_less(node: &NodePattern) -> bool {
node.labels.is_empty() && node.label_expr.is_none()
}

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] comparison (flag-canonical-dup): This round extracts "no labels, however spelled" as a named helper, but the estimate's endpoint gate in the same file (node_is_unfiltered, subject.rs:365-370) spells those same two conjuncts inline

Suggested fix: Compose the estimate's gate from the helper: is_label_less(node) && node.properties.is_none() && node.where_clause.is_none() — the estimate keeps its own narrower four-clause derivation, but the label-less half has one home.

finding F-9-2

Comment thread relate/relate-ir/src/ast/pattern.rs Outdated
/// consumers read this.
///
/// The views borrow: arm *i* is
/// [`DisjunctionArms::arm`](DisjunctionArms::arm) — the base's names

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: this doc links DisjunctionArms::arm, which does not exist — the per-arm accessor is arms(), so the public API reference does not resolve.

Why this matters: the only doc for the per-arm view points at a method a consumer cannot find, and cargo doc emits broken_intra_doc_links for it.
Suggested fix: [DisjunctionArms::arms](DisjunctionArms::arms).

/// `LabelDisjunctionScan` (the scan answers per disjunct label, never
/// every node): the suggestion names the predicate's own per-disjunct
/// `:Label(property)` pairs, never an unrelated store index the
/// predicate never mentions. `None` otherwise: a labeled node, a

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: this clause says a disjunction with no equality predicate answers None, but the function returns Some(AllNodesScan) for that shape (None => return all_nodes_scan()) whenever the store carries a property index.

Why this matters: the documented contract contradicts the code, and the unit test's final assertion ("no equality predicate: no pair to suggest") passes only because the Seeking stub reports no property indexes, so the real fallthrough behavior is unpinned.
Suggested fix: document the AllNodesScan fallthrough and assert it with a stub that carries a property index, or make the code return None.

@oskarhane
oskarhane force-pushed the perf/labs-1083-label-disjunction-seek branch from 8547a26 to 43ab766 Compare November 10, 2026 22:51
@oplane-bot

oplane-bot Bot commented Nov 10, 2026

Copy link
Copy Markdown

Oplane Security Review

Oplane identified security requirements relevant to this PR and checked the implementation against them, finding that 1 requirement needs attention. Push changes to rerun the review, update a status with a justification if needed, or review the generated threat model.

StatusRequirementSeverityAction
🟠 Partially implementedOutput Encoding for Label Names in Plan Narration and Warnings
OPLANE_REQ-00354521
MediumPrompt · Claude · Cursor
🟢 ImplementedResource Usage Enforcement for Disjunction Index Seek Unions
OPLANE_REQ-00354522
Medium

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

/// consumers read this.
///
/// The views borrow: arm *i* is
/// [`DisjunctionArms::arms`](DisjunctionArms::arm) — the base's names

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: the intra-doc link targets a method that does not exist.

Why this matters: rustdoc::broken_intra_doc_links reports this as unresolved, so the reference dead-ends instead of opening the iterator it describes.
Suggested fix: link the existing method — [`DisjunctionArms::arms`](DisjunctionArms::arms) (or just [`DisjunctionArms::arms`]).

@oskarhane

Copy link
Copy Markdown
Contributor Author

Terminal state (head 43ab766): rust-review ✅, security-review ✅, Lint + the full CI matrix ✅ (38 checks). Stellar round 10 reports 0 new findings — everything this port introduced is resolved on-branch across the ten rounds; the 19 carried items are the previously-ticketed set in LABS-1333 (the subject.rs split, the subject-source enum, the crossover/fallback-population design item, the funnel decomposition pass, the fixture consolidation, and the dual-match rationale), every one predating or adjacent to this port rather than in its main paths. Per the bounded review loop, this is the landing state.

@jexp
jexp merged commit 3199d24 into main Nov 10, 2026
43 of 44 checks passed
@jexp
jexp deleted the perf/labs-1083-label-disjunction-seek branch November 10, 2026 23: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.

2 participants