perf(query): F17 — UNION/BIND row-budget forwarding + budget-met branch skip (q029 125s→2.6s)

[aaj3f]

What

q029 ({ WebEvent, eventType="purchase" } UNION { WebEvent, eventType="add_to_cart" } LIMIT 100) re-scanned both FACT_WEB_EVENT branches ~253× — 1.94 M file decodes for a 100-row answer — because the LIMIT 100 budget never reached the branch scans. It died at two absorb points: UnionOperator and BindOperator (q029's branch root is BIND(const AS ?et)), both inheriting the trait's no-op set_row_budget; and once branch-1 filled the budget the union still drained branch-2.

Two changes, both gated by FLUREE_R2RML_UNION_BUDGET (default on):

1. Forward the budget through UnionOperator (the full k to each branch — a single branch may supply all k) and BindOperator (to its child; BIND is categorically 1:1/order-preserving, reclassified from absorb to forward). The R2RML scan then caps its materialize window at k.
2. Budget-met branch/input skip (secondary lever): the union stops building further branches / pulling further input once pending_output_rows >= row_budget. Sound on two counts — a budget reaches the union only under row/order-preserving operators up to the LIMIT (Sort/Distinct absorb ⇒ arbitrary-k-subset / rows_only), and the check fires only when the budget is actually MET (an under-filled branch-1 still runs branch-2).

Result

q029: 125 s (pre-slate) → 2.61 s in-protocol (3-rep per-head baseline, F17 + the #1503/artifact cache stack) — under the ≤3 s bar; burndown row closes. Deterministic, network-invariant evidence (live gate): scan_table 253 → 2, parquet decodes 1,940,510 → 7,703 (2 sweeps → 1), OFF byte-preserved, oracle-parity 0-mismatch. Full-corpus baseline: 59 records, 0 hash mismatches.

Cold isolated first-ask is ~57 s-class and is reported, not gated: the residual is one full FACT_WEB_EVENT sweep, S3-fetch-bound (decode trivial). Wall model: ~7 s fixed (loadTable+oauth+scan_plan) + N_sweeps × one-sweep-fetch; the union is sequential, so the lever removes one whole sweep. This is the shared PR-2a floor (q016/q031/q056) — fetch-rate-sensitive, not decode.

Honest notes

• NOT byte-identical (a sketch prediction, refuted + corrected in-tree): eventType is a post-decode residual and the scan window is geometric-growth, so the budget materializes a different valid first-100 → rows_only (same class as q055/q057). Oracle parity holds.
• Blast radius = q029 only (q042 is UNION without LIMIT; q029 is the sole BIND-under-LIMIT query in the corpus).

Perf violations at this head — documented, not blessed away

The 3-rep baseline flagged 5 pre-existing perf violations (q002/q004/q024/q030/q043, 2.5–8× over blessed). Attributed and NOT caused by F17:

q	blessed	observed	ratio	load_table (GET)
q002	1136 ms	2827 ms	2.49×	1.77 s
q004	415 ms	3320 ms	8.00×	1.52 s
q024	510 ms	2828 ms	5.55×	1.22 s
q030	1221 ms	3047 ms	2.50×	0.96 s
q043	2125 ms	12879 ms	6.06×	11.17 s (6 GETs)

• F17 verified inert for all five — none has a UNION or a BIND, so F17's switch-gated code never executes for them.
• fetch_bytes ≈ 0 for every one (files disk-served; artifact cache 90 MB, 5.7× under the 512 MiB cap) — disproves any cache-eviction / regression story.
• The wall is the loadTable catalog GET: ~1.5 s now vs ~0.4 s when the baselines were blessed — a network-path / environmental slowdown of the catalog endpoint. q043 is worst because it does 6 GETs = the edw:name name-dim fan-out (F20-family, pre-existing).
• Not re-blessed (that would lower the bar on a catalog-slow day) — tracked as register F21; re-check catalog latency in a later window.

#1503 scope note (comment for the reviewer): attributing F21 showed the #1503 loadTable-pointer cache is TTL-window-bounded — TTL default 300 s and get_metadata_location prunes on an expired read, so the pointer spares the GET only within ~5 min of a table's last touch (a first-ask after a quiet gap still pays it). Only one .pointer.json (FACT_WEB_EVENT) survived on disk. That is an honest narrowing of #1503's "credential-free first-ask" claim to an intra-window/intra-session win; whether it's purely TTL or also a per-table gap, and how to widen it, is F21's design question (separate sketch + PR). Dated note added to 21-loadtable-metadata-cache.md.

Tests

• Hermetic (fluree-db-query, 13 union tests): BIND forwards; Sort/Distinct absorb (decline proofs); union stores; Limit→Union correctness; 3 build-count lever tests (branch-1 fills k ⇒ branch-2 not built; under-fills ⇒ built; no budget ⇒ both run).
• Full -p fluree-db-query suite: 1256 passed, 0 failed.
• Scan-level effects (early-stop, ON vs OFF counters) are live-gated — only the R2RML scan honors row_budget and union branches are pattern-built, so there is no hermetic mock-scan seam (a #[cfg(test)] injection hook was considered and declined to keep the binary scaffolding-free).

Harness

The live-gate script's OFF arm ceiling was raised 180 s → 300 s (its ~167 s baseline is fragile at 180 — same headroom ratio as q056 168/180). Manifest timeout_s stays 180 (shipped F17-ON q029 is ~2.6 s in-protocol, far under it).

Stacked on #1506 (test/exploration-corpus-family). Commits: sketch → forwarding → doc-correction → lever → baseline-verdict/F21-docs.