tidaldb/tests/e2e/features/11-ranking-integrity.spec.ts

/**
 * Section 11 — ranking integrity on the deployed cluster.
 *
 * A tripwire pair, in the honest direction. `rank` is currently WRONG on every
 * corpus-wide ranked response from the cluster, and these checks pin that with
 * its root cause so the fix announces itself instead of the defect persisting
 * silently. Same shape as the inert-feature checks in
 * `09-operator-authority.spec.ts`.
 *
 * Root cause, localised: `scatter_merge`
 * (`tidal-server/src/cluster/node.rs:7471`) concatenates each shard group's
 * locally-ranked slice, sorts by score, truncates, and returns at `:7542`
 * WITHOUT re-stamping rank. Its sibling `merge_cross_shard` (`:7583`) does
 * re-stamp, at `:7609`, with a comment naming this exact hazard — but `:7621`
 * documents that full placement short-circuits past it, and this cluster is
 * full-placement RF3, so the guarded path never runs.
 *
 * The evidence that it is the MERGE and not the engine is two-sided:
 *  - standalone numbers ranks densely (`10-ranking-semantics.spec.ts`, measured
 *    1..60 with no gaps) via `tidal/src/query/executor/pipeline.rs:611`;
 *  - the cluster returns per-group ranks concatenated, while SCORES remain
 *    correctly ordered — so the merge's sort is fine and only the stamp is absent.
 *
 * Read-only. Nothing here writes to the deployed cluster.
 */

import { expect, test, type APIRequestContext } from '@playwright/test';
import { recordJson } from '../support/evidence.ts';
import { PUBLIC_BASE_URL, apiKey } from '../support/env.ts';

type RankedItem = { entity_id: number; score: number; rank: number };

/**
 * Enough rows that at least two shard groups must both contribute. With three
 * groups a limit of 1 or 2 can be answered from one group and would show no
 * duplicate at all.
 */
const LIMIT = 12;

/** What a correctly stamped response looks like: dense, ascending, from 1. */
const denseRanks = (count: number): number[] =>
  Array.from({ length: count }, (_unused, index) => index + 1);

async function ranked(
  request: APIRequestContext,
  path: string,
): Promise<{ items: RankedItem[]; ranks: number[]; scores: number[] }> {
  const response = await request.get(`${PUBLIC_BASE_URL}${path}`, {
    headers: { authorization: `Bearer ${apiKey()}` },
  });
  expect(response.status(), `${path} must answer before any conclusion is drawn`).toBe(200);
  const body = (await response.json()) as { items?: RankedItem[] };
  const items = body.items ?? [];
  expect(
    items.length,
    'an empty result cannot distinguish correct ranking from broken ranking',
  ).toBeGreaterThan(1);
  return {
    items,
    ranks: items.map((item) => item.rank),
    scores: items.map((item) => item.score),
  };
}

/** The order is right even though the stamp is wrong — the precise localisation. */
function expectScoresOrdered(scores: number[], surface: string): void {
  for (let index = 1; index < scores.length; index += 1) {
    expect(
      scores[index]!,
      `${surface} returned scores out of order at position ${index} ` +
        `(${scores[index - 1]} then ${scores[index]}). That is a DIFFERENT and worse ` +
        `defect than the rank stamp: it would mean the merge's sort is broken too.`,
    ).toBeLessThanOrEqual(scores[index - 1]!);
  }
}

const FIX_INSTRUCTION =
  'Good news: scatter_merge appears to be fixed. Delete this tripwire, keep the ' +
  'dense-rank assertion in 10-ranking-semantics.spec.ts, and close the defect.';

test.describe('section 11 — ranking integrity (cluster tripwires)', () => {
  test('cluster /feed rank is duplicated — pinned defect in scatter_merge', async ({
    request,
  }, testInfo) => {
    const { items, ranks, scores } = await ranked(
      request,
      `/feed?profile=for_you&limit=${LIMIT}`,
    );
    const duplicates = ranks.length - new Set(ranks).size;

    await recordJson(testInfo, 'cluster-feed-ranks', {
      surface: `/feed?profile=for_you&limit=${LIMIT}`,
      ranks,
      expectedIfFixed: denseRanks(ranks.length),
      duplicateCount: duplicates,
      scores,
      entityIds: items.map((item) => item.entity_id),
      rootCause: 'tidal-server/src/cluster/node.rs:7542 (scatter_merge returns without set_rank)',
    });

    expect(ranks, FIX_INSTRUCTION).not.toEqual(denseRanks(ranks.length));
    expect(
      duplicates,
      'expected duplicate ranks — the signature of per-group slices merged without ' +
        `a re-stamp. ${FIX_INSTRUCTION}`,
    ).toBeGreaterThan(0);

    // Ordering is correct; only the stamp is missing. If this ever fails, the
    // defect has become materially worse.
    expectScoresOrdered(scores, '/feed');
  });

  test('cluster /search rank is duplicated the same way, from the same merge', async ({
    request,
  }, testInfo) => {
    // A term known to be indexed on this corpus. The production corpus has no
    // titles for its 33k items, so an arbitrary word returns zero candidates and
    // would make this check vacuous.
    const { items, ranks, scores } = await ranked(
      request,
      `/search?query=verification&limit=${LIMIT}`,
    );
    const duplicates = ranks.length - new Set(ranks).size;

    await recordJson(testInfo, 'cluster-search-ranks', {
      surface: `/search?query=verification&limit=${LIMIT}`,
      ranks,
      expectedIfFixed: denseRanks(ranks.length),
      duplicateCount: duplicates,
      scores,
      entityIds: items.map((item) => item.entity_id),
    });

    // `/search` shares the same gateway merge, so the same defect surfaces here.
    // Asserting it on both surfaces is what shows the fault is in the merge
    // rather than in one query pipeline.
    expect(ranks, FIX_INSTRUCTION).not.toEqual(denseRanks(ranks.length));
    expect(
      duplicates,
      `expected duplicate ranks on /search too. ${FIX_INSTRUCTION}`,
    ).toBeGreaterThan(0);
    expectScoresOrdered(scores, '/search');
  });
});