perf(row-model): the adopted identity sweep answers verdict and keys from one cache read

Under adoption (every warm keystroke — a filter-only set-query above the
sync gate), carryRecord paid two evaluation-cache WeakMap gets on the
same key per survivor: filterVerdict looked the entry up, failed the
verdictPlan guard by design, and discarded it; fillSortKeysFromPrevious
then looked the same key up in the same (adopted) map to hit its early
return, behind two instanceof revalidations. ~500k redundant lookups per
50k keystroke settle.

The fused sortKeysIfPasses answers both questions from ONE get: the
verdict is still recomputed under the new plan (the memo guard still
fails for adopted entries), the keys are the same unguarded sortKeys
read the fill's early return performed, and a lineage-miss falls back to
the fill's accessor arm with a keys-only seed. The un-adopted lane is
untouched.

Certified by a new evaluationCacheLookups work counter (counts the
identity-carry path's cache reads only): the adopted-lane pin asserts
ONE lookup per swept row (read 10_050 for 10_000 sweeps + 50 survivors
before the fusion; mutation-verified — disabling the fused arm fails it
at exactly 10_050), and the un-adopted control pins 10_100 so a fusion
that merely stopped counting cannot pass. Verdict correctness is pinned
by the flipped visible set (the new filter keeps exactly the 50 rows the
old one rejected).

Zero public report drift (pnpm api clean). row-model 719, grid-core 169,
core 7, renderer-dom 168, react 1570 — all green. The ms payoff is
unmeasured (load 18 machine) and not claimed; it rides with the owed
#490 confirmation round.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 2 people

packages/row-model/src/__tests__/filter-fast-path.test.ts

@@ -180,6 +180,7 @@ function testInstrumentation(): LocalRowModelInstrumentation {
       bulkOrderVerificationsSkipped: 0,
       evaluationCacheAdoptions: 0,
       slotChunksTouched: 0,
+      evaluationCacheLookups: 0,
       sortKeyCarries: 0,
       sortKeyEvaluations: 0,
       schedulerSliceDurations: [],

packages/row-model/src/__tests__/order-statistic-tree.test.ts

@@ -1028,6 +1028,7 @@ describe("bulk-build byId routing", () => {
         bulkOrderVerificationsSkipped: 0,
         evaluationCacheAdoptions: 0,
         slotChunksTouched: 0,
+        evaluationCacheLookups: 0,
         sortKeyCarries: 0,
         sortKeyEvaluations: 0,
         snapshotOutputRowsRead: 0,

packages/row-model/src/__tests__/sort-fast-path.test.ts

@@ -189,6 +189,7 @@ function testInstrumentation(): LocalRowModelInstrumentation {
       bulkOrderVerificationsSkipped: 0,
       evaluationCacheAdoptions: 0,
       slotChunksTouched: 0,
+      evaluationCacheLookups: 0,
       sortKeyCarries: 0,
       sortKeyEvaluations: 0,
       schedulerSliceDurations: [],

packages/row-model/src/__tests__/work.test.ts

@@ -234,6 +234,118 @@ describe("instrumented local row-model work", () => {
     },
   );
 
+  test(
+    "carries a flat filter-only set-query with ONE evaluation-cache lookup per swept row",
+    { timeout: 30_000 },
+    async () => {
+      const scheduled: Array<() => void> = [];
+      const instrumented = createInstrumentedLocalRowModel({
+        rows: rows(10_000),
+        columns,
+        query: {
+          filters: [{ columnId: "filterValue", operator: "gte", value: 1_000 }],
+          sort: [{ columnId: "score", direction: "asc" }],
+          rowGroups: [],
+        },
+        transitionScheduler: {
+          schedule(task) {
+            scheduled.push(task);
+            return () => undefined;
+          },
+        },
+        transitionClock: () => 0,
+        // Test-forcing direction of #488's gate: a filter-only change at 10k
+        // would take the synchronous rebuild; production trips this lane at
+        // >15k resident rows (the warm-keystroke path at 50k).
+        ɵfilterFastPathRowLimit: 0,
+      });
+
+      instrumented.diagnostics.resetWork();
+      // Filter changes ALONE: `isFilterOnlyChange` holds, so the identity
+      // lane adopts the previous plan's evaluation cache wholesale and every
+      // carried record's entry is already in the shared map.
+      const transition = instrumented.model.setQuery({
+        filters: [{ columnId: "filterValue", operator: "lte", value: 1_500 }],
+        sort: [{ columnId: "score", direction: "asc" }],
+        rowGroups: [],
+      });
+      while (scheduled.length > 0) scheduled.shift()!();
+      await transition.finished;
+
+      const work = instrumented.diagnostics.read().work;
+      expect(work.evaluationCacheAdoptions).toBe(1);
+      expect(work.transitionRows).toBe(10_000);
+      expect(work.rowsEvaluated).toBe(0);
+      // The adopted-lane budget: ONE evaluation-cache read per swept row,
+      // total. Before the fused reader the sweep paid two on every SURVIVOR
+      // (`filterVerdict` looked the entry up and discarded it, then
+      // `fillSortKeysFromPrevious` looked the same key up again to hit its
+      // early return) — this read 10_050 with 50 survivors, and at the
+      // 50k/5-commit warm-keystroke scale that was ~500k redundant lookups.
+      expect(work.evaluationCacheLookups).toBe(10_000);
+      // Keys came from the adopted entries, not from accessor re-runs, and
+      // not from the per-row carry fill.
+      expect(work.sortKeyCarries).toBe(0);
+      expect(work.sortKeyEvaluations).toBe(0);
+      // The verdict itself must still be recomputed under the NEW plan (the
+      // adopted entries memo the OLD plan's verdict): the new filter keeps
+      // exactly the 50 rows the old one rejected, in the unchanged sort.
+      const snapshot = instrumented.model.getState().snapshot;
+      expect(snapshot.visibleRowCount).toBe(50);
+      expect(snapshot.range(0, 1)[0]).toMatchObject({
+        kind: "data",
+        rowId: 900,
+      });
+      instrumented.model.dispose();
+    },
+  );
+
+  test(
+    "counts the un-adopted carry fill's evaluation-cache lookups (counter control)",
+    { timeout: 30_000 },
+    async () => {
+      const scheduled: Array<() => void> = [];
+      const instrumented = createInstrumentedLocalRowModel({
+        rows: rows(10_000),
+        columns,
+        query: {
+          filters: [{ columnId: "filterValue", operator: "gte", value: 1_000 }],
+          sort: [{ columnId: "score", direction: "asc" }],
+          rowGroups: [],
+        },
+        transitionScheduler: {
+          schedule(task) {
+            scheduled.push(task);
+            return () => undefined;
+          },
+        },
+        transitionClock: () => 0,
+      });
+
+      instrumented.diagnostics.resetWork();
+      // Filter AND sort change: not a filter-only change, so no adoption —
+      // the identity lane pays the verdict lookup per swept row plus the
+      // carry fill's two reads (fresh-cache miss, then the previous plan's
+      // store) per SURVIVOR. This pin is the control proving the counter
+      // observes every read site: if the fused reader ever "wins" by simply
+      // not counting, this expectation catches it.
+      const transition = instrumented.model.setQuery({
+        filters: [{ columnId: "filterValue", operator: "lte", value: 1_500 }],
+        sort: [{ columnId: "score", direction: "desc" }],
+        rowGroups: [],
+      });
+      while (scheduled.length > 0) scheduled.shift()!();
+      await transition.finished;
+
+      const work = instrumented.diagnostics.read().work;
+      expect(work.evaluationCacheAdoptions).toBe(0);
+      expect(work.transitionRows).toBe(10_000);
+      expect(work.evaluationCacheLookups).toBe(10_100);
+      expect(work.sortKeyCarries).toBe(50);
+      instrumented.model.dispose();
+    },
+  );
+
   test(
     "builds a flat set-derivations candidate without persistent per-row path copying",
     { timeout: 30_000 },

packages/row-model/src/compiled-query.ts

@@ -103,6 +103,18 @@ export interface SortKeyFillInstrumentation {
   readonly work: {
     sortKeyCarries: number;
     sortKeyEvaluations: number;
+    evaluationCacheLookups: number;
+  };
+}
+
+/**
+ * Structural slice consumed by `filterVerdict`'s lookup counting — the
+ * verdict-only callers that thread instrumentation (the flat identity-carry
+ * sweep) count their cache reads; everyone else passes nothing.
+ */
+export interface EvaluationCacheLookupInstrumentation {
+  readonly work: {
+    evaluationCacheLookups: number;
   };
 }
 
@@ -1999,11 +2011,14 @@ class CompiledQueryPlan<TColumns>
   static filterVerdict<TColumns, TRowId extends PretableRowId>(
     plan: unknown,
     input: CompiledRowInput<RowForColumns<TColumns>, TRowId>,
+    instrumentation?: EvaluationCacheLookupInstrumentation,
   ): boolean {
     if (!(plan instanceof CompiledQueryPlan)) {
       throw new TypeError("Filter verdicts require a compiled query plan.");
     }
     const compiled = plan as CompiledQueryPlan<TColumns>;
+    if (instrumentation !== undefined)
+      instrumentation.work.evaluationCacheLookups += 1;
     const cached = compiled.#evaluationCache.get(input.row);
     if (
       cached !== undefined &&
@@ -2024,6 +2039,85 @@ class CompiledQueryPlan<TColumns>
     );
   }
 
+  /**
+   * Fused verdict + sort-key resolution for the ADOPTED identity-carry
+   * sweep: ONE evaluation-cache read answers both questions
+   * `filterVerdict` + `fillSortKeysFromPrevious` used to pay two reads for
+   * (the verdict lookup discarded its entry, then the fill looked the same
+   * key up again to hit its early return — one redundant get per survivor).
+   *
+   * Returns the row's sort keys when the row passes THIS plan's filters and
+   * `undefined` when it does not; a rejected row's keys are never read, so
+   * key resolution rides the verdict's single lookup for free.
+   *
+   * Precondition (CALLER-OWNED, exactly `adoptEvaluationCache`'s): this
+   * plan's cache was adopted from the plan whose lineage evaluated
+   * `input.row` — a filter-only change — so the cached `sortKeys` are the
+   * ones this plan's accessors would produce (same orderings, same
+   * accessors; see the adoption proof). The verdict is still recomputed
+   * under this plan whenever the memo's `verdictPlan` is not this plan —
+   * adopted entries always miss that guard, exactly as before the fusion.
+   */
+  static sortKeysIfPasses<TColumns, TRowId extends PretableRowId>(
+    plan: unknown,
+    input: CompiledRowInput<RowForColumns<TColumns>, TRowId>,
+    instrumentation?: SortKeyFillInstrumentation,
+  ): readonly CompiledSortKey<TColumns>[] | undefined {
+    if (!(plan instanceof CompiledQueryPlan)) {
+      throw new TypeError("Filter verdicts require a compiled query plan.");
+    }
+    const compiled = plan as CompiledQueryPlan<TColumns>;
+    if (instrumentation !== undefined)
+      instrumentation.work.evaluationCacheLookups += 1;
+    const cached = compiled.#evaluationCache.get(input.row);
+    const passes =
+      cached !== undefined &&
+      cached.metadata !== undefined &&
+      cached.filterPasses !== undefined &&
+      cached.verdictPlan === compiled &&
+      Object.is(cached.rowId, input.rowId) &&
+      cached.sourceOrder === input.sourceOrder
+        ? cached.filterPasses
+        : compiled.#filterVerdict((columnId) =>
+            compiled.#readColumnValue(
+              compiled.#byId.get(columnId)!,
+              input.row,
+              input.rowId,
+            ),
+          );
+    if (!passes) return undefined;
+    if (cached !== undefined) {
+      // The same UNGUARDED read the carry fill's early return performs:
+      // sort keys depend only on the row object and the (unchanged) sort
+      // columns, so an entry from anywhere in the adopted lineage answers.
+      return cached.sortKeys as readonly CompiledSortKey<TColumns>[];
+    }
+    // A row the adopted lineage never evaluated: resolve keys by accessor
+    // and seed a keys-only entry, mirroring the carry fill's miss arm with
+    // nothing to carry (`metadata` absent, so a later `evaluate` upgrades).
+    const sortKeys = Object.freeze(
+      compiled.#runtimeQuery.sort.map((entry) => {
+        const value = compiled.#readColumnValue(
+          compiled.#byId.get(entry.columnId)!,
+          input.row,
+          input.rowId,
+        );
+        if (instrumentation !== undefined)
+          instrumentation.work.sortKeyEvaluations += 1;
+        return Object.freeze({ columnId: entry.columnId, value });
+      }),
+    ) as readonly CompiledSortKey<TColumns>[];
+    compiled.#evaluationCache.set(input.row, {
+      rowId: input.rowId,
+      sourceOrder: input.sourceOrder,
+      metadata: undefined,
+      filterPasses: undefined,
+      verdictPlan: undefined,
+      sortKeys,
+    });
+    return sortKeys;
+  }
+
   /*
    * The single comparison loop behind `compareRecordRows`: per-ordering
    * `compareValues` over store-resolved keys, then the `sourceOrder`
@@ -2159,11 +2253,15 @@ class CompiledQueryPlan<TColumns>
     }
     const next = nextPlan as CompiledQueryPlan<TColumns>;
     const previous = previousPlan as CompiledQueryPlan<TColumns>;
+    if (instrumentation !== undefined)
+      instrumentation.work.evaluationCacheLookups += 1;
     const existing = next.#evaluationCache.get(input.row);
     if (existing !== undefined) {
       return existing.sortKeys as readonly CompiledSortKey<TColumns>[];
     }
 
+    if (instrumentation !== undefined)
+      instrumentation.work.evaluationCacheLookups += 1;
     const carried = previous.#evaluationCache.get(input.row)?.sortKeys as
       readonly CompiledSortKey<TColumns>[] | undefined;
     const sortKeys = Object.freeze(
@@ -2538,8 +2636,33 @@ export function adoptEvaluationCache<TColumns>(
 export function filterVerdict<TColumns, TRowId extends PretableRowId>(
   plan: CompiledQuery<TColumns>,
   input: CompiledRowInput<RowForColumns<TColumns>, TRowId>,
+  instrumentation?: EvaluationCacheLookupInstrumentation,
 ): boolean {
-  return CompiledQueryPlan.filterVerdict<TColumns, TRowId>(plan, input);
+  return CompiledQueryPlan.filterVerdict<TColumns, TRowId>(
+    plan,
+    input,
+    instrumentation,
+  );
+}
+
+/**
+ * Fused verdict + sort-key resolution under an ADOPTED evaluation cache —
+ * one cache read instead of `filterVerdict` + `fillSortKeysFromPrevious`'s
+ * two. Returns the keys when the row passes `plan`'s filters, `undefined`
+ * when it does not. Valid ONLY after `adoptEvaluationCache(plan, previous)`
+ * for the plan lineage that evaluated the row (a filter-only change); see
+ * `CompiledQueryPlan.sortKeysIfPasses` for the semantics proof.
+ */
+export function sortKeysIfPasses<TColumns, TRowId extends PretableRowId>(
+  plan: CompiledQuery<TColumns>,
+  input: CompiledRowInput<RowForColumns<TColumns>, TRowId>,
+  instrumentation?: SortKeyFillInstrumentation,
+): readonly CompiledSortKey<TColumns>[] | undefined {
+  return CompiledQueryPlan.sortKeysIfPasses<TColumns, TRowId>(
+    plan,
+    input,
+    instrumentation,
+  );
 }
 
 export function compileQuery<const TColumns>(

packages/row-model/src/diagnostics.ts

@@ -61,6 +61,14 @@ export interface LocalRowModelWorkDiagnostics {
    * plus table copies per commit rather than per-row.
    */
   readonly slotChunksTouched: number;
+  /**
+   * Evaluation-cache WeakMap reads issued by the flat identity-carry path
+   * (the cooperative sweep's verdict check and sort-key resolution,
+   * including replay inserts). The adopted-lane budget is ONE read per
+   * swept row; `work.test.ts` pins it. Other verdict/evaluate callers do
+   * not count here.
+   */
+  readonly evaluationCacheLookups: number;
   /** Sort-key entries carried from a previous plan's store, per (row, column). */
   readonly sortKeyCarries: number;
   /** Sort-key entries produced by running an accessor, per (row, column). */
@@ -140,6 +148,7 @@ function newInstrumentation(): LocalRowModelInstrumentation {
       bulkOrderVerificationsSkipped: 0,
       evaluationCacheAdoptions: 0,
       slotChunksTouched: 0,
+      evaluationCacheLookups: 0,
       sortKeyCarries: 0,
       sortKeyEvaluations: 0,
       snapshotOutputRowsRead: 0,
@@ -171,6 +180,7 @@ function resetWork(instrumentation: LocalRowModelInstrumentation): void {
     "bulkOrderVerificationsSkipped",
     "evaluationCacheAdoptions",
     "slotChunksTouched",
+    "evaluationCacheLookups",
     "sortKeyCarries",
     "sortKeyEvaluations",
     "snapshotOutputRowsRead",

packages/row-model/src/flat-cooperative-candidate.ts

@@ -1,6 +1,7 @@
 import {
   adoptEvaluationCache,
   fillSortKeysFromPrevious,
+  sortKeysIfPasses,
   filterVerdict,
   isFilterOnlyChange,
   type CompiledQuery,
@@ -92,7 +93,11 @@ export function createFlatCooperativeCandidate<
    * per-row `fillSortKeysFromPrevious` below carries what it can instead.
    * Pure perf lever either way: nothing below depends on the adoption.
    */
-  if (isFilterOnlyChange(options.captured.queryPlan, options.queryPlan)) {
+  const adopted = isFilterOnlyChange(
+    options.captured.queryPlan,
+    options.queryPlan,
+  );
+  if (adopted) {
     adoptEvaluationCache(options.queryPlan, options.captured.queryPlan);
     if (instrumentation !== undefined) {
       instrumentation.work.evaluationCacheAdoptions += 1;
@@ -253,7 +258,24 @@ export function createFlatCooperativeCandidate<
       // on this lane — that zero is the dense claim `work.test.ts` pins.
       instrumentation.work.transitionRows += 1;
     }
-    if (filterVerdict(state.queryPlan, record as never)) {
+    if (adopted) {
+      // Fused: the adopted cache answers verdict AND keys from ONE read —
+      // `work.test.ts` pins the one-lookup-per-swept-row budget, and the
+      // un-fused arm below stays pinned as the counter's control.
+      const keys = sortKeysIfPasses(
+        state.queryPlan,
+        record as never,
+        instrumentation,
+      ) as readonly CompiledSortKey<TColumns>[] | undefined;
+      if (keys !== undefined) {
+        state.transientFlatRows!.insertOrReplace(
+          Object.freeze({ record, keys }),
+        );
+        setMembershipBit(state.membership!, record.slot);
+      }
+      return;
+    }
+    if (filterVerdict(state.queryPlan, record as never, instrumentation)) {
       const keys = fillSortKeysFromPrevious(
         state.queryPlan,
         state.captured.queryPlan,