MILAB-6651: pin cellLinker side assignment in the TS linker engine

[PaulNewling]

What this does

Adds characterisation tests for LinkerMap, mirroring tests added to pframes-rs. Test-only change.

They assert the behaviour that exists today, which is wrong. They must flip when linker sides become explicit, and that flip is the proof the fix worked.

Why LinkerMap needs its own tests

Two engines implement the same linker convention. Rust LinkerIndex plans queries inside pframes-rs. This TS LinkerMap collects columns at model time — sdk/model/src/render/util/column_collection.ts:520 and sdk/model/src/pframe_utils/axes.ts:77 — where only specs are available and pl-model-common deliberately carries no pframes-rs dependency.

Both derive component ordering independently: Rust from disjoint::DisjointSet::sets(), TS from its own index scan in getAxesGroups. Nothing couples them, and they have already drifted twice — Rust hard-errors on more than two components while TS silently skips, and only Rust honours excludeColumns. So each side asserts the expectation separately. A genuine shared fixture would need a generated cross-repo contract.

What the tests establish

pl7.app/sc/cellLinker is authored [sampleId, cellId <- sampleId, scClonotypeKey]. getAxesGroups returns groups ordered by smallest contained index, and fromColumns destructures const [left, right] = groups (linker_columns.ts:53), so the sample/cell component becomes the one-side. That is backwards: many cells map to one clonotype.

Two consequences follow, both asserted:

• A clonotype-keyed source reaches cell-level axes. Edges are stored many-side → one-side (linker_columns.ts:91), so inverted sides let a clonotype-keyed table traverse down to per-cell axes. This is how cell-level columns reach a clonotype-keyed p-frame.
• A cell-keyed source cannot reach the clonotype. Authoring the clonotype component first reverses both directions, which makes the intended cell → clonotype enrichment appear.

A fourth test walks all six authoring orders and separates the two things this issue turns on: group membership is authoring-order independent; group position is not. The axes group correctly however they are written down, and position alone decides which component is treated as the one-side. No structural rule can recover the intended direction from the spec — it must be declared or read from data.

Verification

vitest run in lib/model/common — 112 pass across 9 files. ts-builder formatter, linter, and type-check all clean.

Two notes for a reviewer

The trunk in these tests carries its whole parent tree. Linker map keys come from getArrayFromAxisTree, so a cell trunk's key is [cellId, sampleId]. Passing cellId alone yields the key [cellId] and misses on key shape rather than on reachability. An early draft of these tests passed for exactly that wrong reason.

Group contents are compared as sorted sets, deliberately. getAxesGroups documents "There are no order inside every group" (linker_columns.ts:271), so asserting a specific order within a group would pin something the source disclaims. Only order between groups is pinned.

Separately: this package's test script passes --coverage but instruments nothing — it reports 0% with 112 tests passing. Pre-existing, and not addressed here.

[notion-workspace]

[data/bulk-sc-VDJ] fix linker? duplicated clonotype id issue

[changeset-bot]

🦋 Changeset detected

Latest commit: c990c47

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 52.89%. Comparing base (eac18ff) to head (5f5f16f).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1768      +/-   ##
==========================================
- Coverage   52.90%   52.89%   -0.01%     
==========================================
  Files         370      370              
  Lines       19994    19994              
  Branches     4435     4435              
==========================================
- Hits        10578    10576       -2     
- Misses       8110     8112       +2     
  Partials     1306     1306              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.