@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/data_adapters/BaseAdapter/stats.js

@@ -1,7 +1,7 @@
 import { firstValueFrom } from 'rxjs';
 import { toArray } from 'rxjs/operators';
-import { max, min, sum } from "../../util/index.js";
-import { rectifyStats } from "../../util/stats.js";
+import { max, min, sum } from '../../util/index.js';
+import { rectifyStats } from '../../util/stats.js';
 const DENSITY_SAMPLE_INITIAL_INTERVAL = 1000;
 const DENSITY_SAMPLE_MIN_FEATURES = 70;
 const DENSITY_SAMPLE_TIMEOUT_MS = 5000;
@@ -13,40 +13,105 @@ export function aggregateQuantitativeStats(stats) {
         scoreMin: min(stats.map(s => s.scoreMin)),
         scoreSum: sum(stats.map(s => s.scoreSum)),
         scoreSumSquares: sum(stats.map(s => s.scoreSumSquares)),
-        featureCount: sum(stats.map(s => s.featureCount)),
+        featureCount: sum(stats.map(s => s.featureCount ?? 0)),
         basesCovered: sum(stats.map(s => s.basesCovered)),
         ...(meanMins.length > 0 ? { scoreMeanMin: min(meanMins) } : {}),
         ...(meanMaxs.length > 0 ? { scoreMeanMax: max(meanMaxs) } : {}),
     });
 }
-export function sampleFeaturesForInterval(region, interval, getFeatures, opts) {
+// Where the probe samples, as a fraction into the region. The primary point
+// avoids the region edges, where coverage often tapers.
+const DENSITY_SAMPLE_POINT = 0.25;
+const DENSITY_CONFIRM_POINT = 0.7;
+// A sample window of `interval` bp centered `at` into the region. Clamped to the
+// region bounds so it never samples features outside the region being measured
+// (the left edge clamps to the region start, not to the chromosome origin).
+function sampleWindow(region, interval, at) {
     const { start, end } = region;
-    const sampleCenter = start * 0.75 + end * 0.25;
-    return firstValueFrom(getFeatures({
-        ...region,
-        start: Math.max(0, Math.round(sampleCenter - interval / 2)),
-        end: Math.min(Math.round(sampleCenter + interval / 2), end),
-    }, opts).pipe(toArray()));
+    const sampleCenter = start + (end - start) * at;
+    return {
+        start: Math.max(start, Math.round(sampleCenter - interval / 2)),
+        end: Math.min(end, Math.round(sampleCenter + interval / 2)),
+    };
 }
-export async function calculateFeatureDensityStats(region, getFeatures, opts) {
+// Cheap pre-fetch density estimate: sample a small window and grow it (doubling)
+// until enough features are seen to be meaningful, then report features-per-bp
+// over the bp actually sampled. Dense regions return after one tiny fetch;
+// sparse regions expand until the window covers the whole region, bounded by a
+// wall-clock timeout. Lets a display reject an unrenderably dense region before
+// downloading the whole region's features.
+//
+// `admit` is the caller's feature-admission predicate (config filters, type
+// gates, ...). When given, the reported density counts only admitted features,
+// so a caller that filters before drawing gates on the population it will
+// actually render rather than the raw one — without it, a filtered view gets
+// rejected on features it was never going to draw.
+//
+// Note the asymmetry, and keep it: the *window growth* below tests the raw
+// count while the *density* reports the admitted count. Growing on the admitted
+// count would make a selective filter double the window over and over until it
+// spanned the whole region — turning the cheap pre-fetch probe into a second
+// full download for exactly the views that need it most.
+export async function calculateFeatureDensityStats(region, getFeatures, { admit, gate, ...opts } = {}) {
     const refLen = region.end - region.start;
-    let interval = DENSITY_SAMPLE_INITIAL_INTERVAL;
-    let expansionTime = 0;
-    let lastTime = performance.now();
+    const t0 = performance.now();
+    let interval = Math.max(DENSITY_SAMPLE_INITIAL_INTERVAL, gate?.initialInterval ?? 0);
+    const sampleAt = async (at) => {
+        const { start, end } = sampleWindow(region, interval, at);
+        const features = await firstValueFrom(getFeatures({ ...region, start, end }, opts).pipe(toArray()));
+        return {
+            sampledBp: end - start,
+            raw: features.length,
+            admitted: admit ? features.filter(admit).length : features.length,
+        };
+    };
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     while (true) {
-        const features = await sampleFeaturesForInterval(region, interval, getFeatures, opts);
-        const featureCount = features.length;
-        if (featureCount >= DENSITY_SAMPLE_MIN_FEATURES || interval * 2 > refLen) {
-            return { featureDensity: featureCount / interval };
+        const { sampledBp, raw, admitted } = await sampleAt(DENSITY_SAMPLE_POINT);
+        // The verdict is already decided by a margin, so a precise density would
+        // only make it more decided. Tested on the admitted count, which is the
+        // population the caller judges — the raw count below governs window growth
+        // for the reason in the note above, and the two must not be swapped.
+        //
+        // A second point has to agree before the probe answers a verdict the old
+        // ladder could not have reached — and `raw` is exactly what separates the
+        // two. A window already holding DENSITY_SAMPLE_MIN_FEATURES is one the exit
+        // below would have answered from anyway, so there is nothing new to confirm
+        // and this falls through to it for the same number. Under that count the
+        // ladder would have kept widening, diluting a local cluster, and answering
+        // here instead is what lets a sparse track with a cluster at the fixed
+        // sample point read as dense and banner at that zoom until the user
+        // force-loads.
+        //
+        // So the confirmation is owed only by the case that is new, which is also
+        // the case that is cheap: every dense annotation track measured clears
+        // DENSITY_SAMPLE_MIN_FEATURES in its first window and pays nothing. A
+        // disagreement is not a verdict — the ladder simply carries on.
+        if (gate?.settled(admitted, sampledBp) &&
+            raw < DENSITY_SAMPLE_MIN_FEATURES) {
+            const other = await sampleAt(DENSITY_CONFIRM_POINT);
+            if (gate.settled(other.admitted, other.sampledBp)) {
+                // the lower of two agreeing readings, so the count the banner quotes is
+                // never the high one of a pair
+                return {
+                    featureDensity: Math.min(admitted / sampledBp, other.admitted / other.sampledBp),
+                };
+            }
         }
-        if (expansionTime > DENSITY_SAMPLE_TIMEOUT_MS) {
-            console.warn("Stats estimation reached timeout, or didn't get enough features");
+        // Enough features to be meaningful, or the window already spans the whole
+        // region (growing further can't sample more) — report density over the bp
+        // actually sampled, not the nominal interval.
+        if (raw >= DENSITY_SAMPLE_MIN_FEATURES || sampledBp >= refLen) {
+            return { featureDensity: admitted / sampledBp };
+        }
+        // Sparse region or slow adapter: sampling ran past the time budget without
+        // hitting the feature target. Report infinite density so the caller never
+        // gates on a timed-out estimate and lets the full fetch decide.
+        if (performance.now() - t0 > DENSITY_SAMPLE_TIMEOUT_MS) {
+            console.warn(`[calculateFeatureDensityStats] gave up sampling density after ${(performance.now() - t0).toFixed(0)}ms without reaching ${DENSITY_SAMPLE_MIN_FEATURES} features`);
             return { featureDensity: Number.POSITIVE_INFINITY };
         }
-        const currTime = performance.now();
-        expansionTime += currTime - lastTime;
-        lastTime = currTime;
         interval *= 2;
     }
 }
-export { blankStats } from "../../util/stats.js";
+export { blankStats } from '../../util/stats.js';

package/esm/data_adapters/BaseAdapter/types.d.ts

@@ -1,23 +1,21 @@
-import type { StopToken } from '../../util/stopToken.ts';
+import type { StatusCallback } from '../../util/progress.ts';
+export type { ZoomRange } from './zoomRange.ts';
+export type LodTier = 'fine' | 'coarse';
 export interface BaseOptions {
-    stopToken?: StopToken;
+    signal?: AbortSignal;
     bpPerPx?: number;
     sessionId?: string;
-    trackInstanceId?: string;
-    signal?: AbortSignal;
-    statusCallback?: (message: string) => void;
+    statusCallback?: StatusCallback;
+    notices?: string[];
     headers?: Record<string, string>;
+    assemblyName?: string;
+    lodMode?: LodTier;
+    haplotypes?: string[];
+    topLevelOnly?: boolean;
 }
 export type SearchType = 'full' | 'prefix' | 'exact';
 export interface BaseTextSearchArgs {
     queryString: string;
     searchType?: SearchType;
-    stopToken?: StopToken;
-    limit?: number;
-    pageNumber?: number;
-}
-export interface FeatureDensityStats {
-    featureDensity?: number;
-    fetchSizeLimit?: number;
-    bytes?: number;
+    signal?: AbortSignal;
 }

package/esm/data_adapters/BaseAdapter/types.js

@@ -1 +1,2 @@
 export {};
+// #endregion

package/esm/data_adapters/BaseAdapter/util.d.ts

@@ -5,8 +5,12 @@ import type { BaseSequenceAdapter } from './BaseSequenceAdapter.ts';
 import type { BaseTextSearchAdapter } from './BaseTextSearchAdapter.ts';
 import type { RegionsAdapter } from './RegionsAdapter.ts';
 export type AnyDataAdapter = BaseAdapter | BaseFeatureDataAdapter | BaseRefNameAliasAdapter | BaseTextSearchAdapter | RegionsAdapter | BaseSequenceAdapter;
-export declare function isSequenceAdapter(t: AnyDataAdapter): t is BaseSequenceAdapter;
+export interface RefNameSource {
+    getRefNames(opts?: Record<string, unknown>): Promise<string[]>;
+}
 export declare function isRegionsAdapter(t: AnyDataAdapter): t is RegionsAdapter;
 export declare function isFeatureAdapter(t: AnyDataAdapter): t is BaseFeatureDataAdapter;
+export declare function isRefNameSource(t: AnyDataAdapter): t is AnyDataAdapter & RefNameSource;
+export declare function isSequenceAdapter(t: AnyDataAdapter): t is BaseSequenceAdapter;
 export declare function isRefNameAliasAdapter(t: object): t is BaseRefNameAliasAdapter;
 export declare function isTextSearchAdapter(t: AnyDataAdapter): t is BaseTextSearchAdapter;

package/esm/data_adapters/BaseAdapter/util.js

@@ -1,12 +1,23 @@
-export function isSequenceAdapter(t) {
-    return 'getRegions' in t && 'getFeatures' in t;
-}
 export function isRegionsAdapter(t) {
     return 'getRegions' in t;
 }
 export function isFeatureAdapter(t) {
     return 'getFeatures' in t;
 }
+// An adapter that can report the refNames its file uses, which is all refName
+// renaming needs. Deliberately broader than isFeatureAdapter: an adapter can
+// serve a non-feature payload (precomputed LD pairs, say) and still need its
+// contig names reconciled with the assembly's. Gating refName lookup on
+// isFeatureAdapter instead meant such an adapter reported *zero* refNames, so
+// the refName map came back empty, so renaming silently did nothing and every
+// record was later dropped on an exact-match refName test - a blank track with
+// no error. See CoreGetRefNames.
+export function isRefNameSource(t) {
+    return typeof t.getRefNames === 'function';
+}
+export function isSequenceAdapter(t) {
+    return 'getSequence' in t;
+}
 export function isRefNameAliasAdapter(t) {
     return 'getRefNameAliases' in t;
 }

package/esm/data_adapters/BaseAdapter/zoomRange.d.ts

@@ -0,0 +1,10 @@
+/**
+ * #api
+ * The bp/px interval, `[minBpPerPx, maxBpPerPx)`, over which an adapter with
+ * zoom levels answers a fetch from the same level it answered `opts.bpPerPx`
+ * from. A display holding the answer refetches when the view leaves it.
+ */
+export interface ZoomRange {
+    minBpPerPx: number;
+    maxBpPerPx: number;
+}

package/esm/data_adapters/CytobandAdapter/CytobandAdapter.d.ts

@@ -1,6 +1,6 @@
 import { SimpleFeature } from '../../util/index.ts';
 import { BaseAdapter } from '../BaseAdapter/index.ts';
-import type { BaseOptions } from '../BaseAdapter/BaseOptions.ts';
+import type { BaseOptions } from '../BaseAdapter/types.ts';
 export default class CytobandAdapter extends BaseAdapter {
     getData(opts?: BaseOptions): Promise<SimpleFeature[]>;
 }

package/esm/data_adapters/CytobandAdapter/CytobandAdapter.js

@@ -1,13 +1,13 @@
-import { SimpleFeature, fetchAndMaybeUnzipText } from "../../util/index.js";
-import { openLocation } from "../../util/io/index.js";
-import { BaseAdapter } from "../BaseAdapter/index.js";
+import { SimpleFeature, fetchAndMaybeUnzipText } from '../../util/index.js';
+import { openLocation } from '../../util/io/index.js';
+import { BaseAdapter } from '../BaseAdapter/index.js';
 export default class CytobandAdapter extends BaseAdapter {
     async getData(opts) {
         const conf = this.getConf('cytobandLocation');
-        if (conf.uri === '' || conf.uri === '/path/to/cytoband.txt.gz') {
+        if (!conf) {
             return [];
         }
-        const text = await fetchAndMaybeUnzipText(openLocation(conf, this.pluginManager), opts);
+        const text = await fetchAndMaybeUnzipText(openLocation(conf, this.pluginManager), opts, 'Downloading cytobands');
         return text
             .split(/\n|\r\n|\r/)
             .filter(f => !!f.trim())

package/esm/data_adapters/CytobandAdapter/configSchema.d.ts

@@ -1,9 +1,37 @@
+/**
+ * #config CytobandAdapter
+ *
+ * #example
+ * Goes on an ASSEMBLY, under `cytobands` — not on a track. It draws the
+ * ideogram banding in the linear genome view's overview bar:
+ * ```js
+ * {
+ *   name: 'hg38',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'hg38-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/hg38.fa.gz',
+ *     },
+ *   },
+ *   cytobands: {
+ *     adapter: {
+ *       type: 'CytobandAdapter',
+ *       uri: 'https://example.com/hg38.cytoBand.txt.gz',
+ *     },
+ *   },
+ * }
+ * ```
+ */
 declare const configSchema: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-    cytobandLocation: {
-        type: string;
-        defaultValue: {
-            uri: string;
-        };
+    type: {
+        type: "string";
+    } & {
+        defaultValue: string;
     };
-}, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;
+    readonly cytobandLocation: {
+        type: "maybeFileLocation";
+    };
+}, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined, true, import("../../configuration/requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>;
 export default configSchema;

package/esm/data_adapters/CytobandAdapter/configSchema.js

@@ -1,24 +1,54 @@
-import { ConfigurationSchema } from "../../configuration/index.js";
-function x() { }
+import { ConfigurationSchema, expandUriShorthand, } from '../../configuration/index.js';
+/**
+ * #config CytobandAdapter
+ *
+ * #example
+ * Goes on an ASSEMBLY, under `cytobands` — not on a track. It draws the
+ * ideogram banding in the linear genome view's overview bar:
+ * ```js
+ * {
+ *   name: 'hg38',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'hg38-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/hg38.fa.gz',
+ *     },
+ *   },
+ *   cytobands: {
+ *     adapter: {
+ *       type: 'CytobandAdapter',
+ *       uri: 'https://example.com/hg38.cytoBand.txt.gz',
+ *     },
+ *   },
+ * }
+ * ```
+ */
 const configSchema = ConfigurationSchema('CytobandAdapter', {
+    /**
+     * #slot
+     * location of a UCSC-style `cytoBand.txt` (`chrom start end name
+     * gieStain`), which draws the ideogram banding in the view's overview bar.
+     * May be gzipped. Configured on an assembly, not on a track.
+     */
     cytobandLocation: {
-        type: 'fileLocation',
-        defaultValue: {
-            uri: '/path/to/cytoband.txt.gz',
-        },
+        type: 'maybeFileLocation',
     },
 }, {
     explicitlyTyped: true,
-    preProcessSnapshot: snap => {
-        return snap.uri
-            ? {
-                ...snap,
-                cytobandLocation: {
-                    uri: snap.uri,
-                    baseUri: snap.baseUri,
-                },
-            }
-            : snap;
-    },
+    /**
+     * #preProcessSnapshot
+     *
+     *
+     * preprocessor to allow minimal config:
+     * ```json
+     * {
+     *   "type": "CytobandAdapter",
+     *   "uri": "yourfile.bed"
+     * }
+     * ```
+     */
+    preProcessSnapshot: snap => expandUriShorthand(snap, 'cytobandLocation'),
 });
 export default configSchema;

package/esm/data_adapters/CytobandAdapter/index.js

@@ -1,5 +1,5 @@
-import configSchema from "./configSchema.js";
-import { AdapterType } from "../../pluggableElementTypes/index.js";
+import { AdapterType } from '../../pluggableElementTypes/index.js';
+import configSchema from './configSchema.js';
 export default function CytobandAdapterF(pluginManager) {
     pluginManager.addAdapterType(() => new AdapterType({
         name: 'CytobandAdapter',
@@ -7,6 +7,6 @@ export default function CytobandAdapterF(pluginManager) {
         adapterMetadata: {
             hiddenFromGUI: true,
         },
-        getAdapterClass: () => import("./CytobandAdapter.js").then(f => f.default),
+        getAdapterClass: () => import('./CytobandAdapter.js').then(f => f.default),
     }));
 }

package/esm/data_adapters/adapterSessionRefcount.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Counts how many live track models are using each rpcSessionId, so the
+ * worker-side dataAdapterCache can be told when the last one goes away.
+ *
+ * ## Why a refcount and not just "track closed"
+ *
+ * An rpcSessionId is derived from the *adapter config* (BaseTrackModel's
+ * `rpcSessionId` getter is `adapterConfigCacheKey(adapter)`), so it is shared by
+ * every track model with that config — the same track shown in two linear genome
+ * views is two model instances with one id, as is a pair of tracks configured
+ * alike. Freeing on any close would evict an adapter the other view is still
+ * querying. The count is incremented per track model and the free only fires at
+ * zero.
+ *
+ * Counting here rather than walking the state tree at teardown keeps it exact:
+ * during a session teardown the tree is already coming apart, and "is any other
+ * track still using this?" is not a question worth asking of a half-destroyed
+ * tree.
+ *
+ * ## Why a WeakMap keyed on the rpcManager
+ *
+ * The counts belong to one session. Keying them on the session's own RpcManager
+ * means a discarded session's counts are collected with it, with no reset call
+ * for anyone to forget. This is the case the adapter cache itself cannot use —
+ * see dataAdapterCache — because here the key is a main-thread object whose
+ * lifetime already matches, rather than a string that crossed a worker boundary.
+ */
+/**
+ * The slice of RpcManager this needs. Structural rather than the concrete class
+ * so that the partial stubs the model tests build satisfy it, and so that
+ * adapter-lifetime bookkeeping does not depend on the RPC transport.
+ */
+interface RpcCaller {
+    freeSession(sessionId: string): Promise<void>;
+}
+/** Record that a track model is using `sessionId`. Pair with release. */
+export declare function retainAdapterSession(rpcManager: RpcCaller | undefined, sessionId: string): void;
+/**
+ * Give up one claim on `sessionId`. When the last one goes, ask the worker to
+ * drop the adapters cached under it — which is the only thing that ever makes
+ * them collectable, since the cache is a strong reference rooted in module
+ * scope.
+ *
+ * The free lands on the same driver the track's queries ran on, because every
+ * call in the app runs on the one the session resolved — and, under a worker
+ * pool, on the same worker, without booting one for a session that never
+ * dispatched anything. See `BaseRpcDriver.freeSession`.
+ *
+ * Errors are swallowed on purpose. This runs on teardown, where a worker
+ * already terminated by a session switch is the expected case rather than a
+ * fault, and nothing downstream could act on the failure anyway.
+ *
+ * Closing and immediately reopening the same track can race: the free is in
+ * flight while the reopened track re-retains, and the eviction lands on the
+ * adapter the new track just claimed. It costs that track one re-setup and
+ * heals itself on the next query, because an evicted adapter is only ever a
+ * cold cache. Sequencing it away would mean generation counters on a cache,
+ * which is a poor trade for a mis-click.
+ */
+export declare function releaseAdapterSession(rpcManager: RpcCaller | undefined, sessionId: string): Promise<void>;
+export {};

package/esm/data_adapters/adapterSessionRefcount.js

@@ -0,0 +1,96 @@
+/**
+ * Counts how many live track models are using each rpcSessionId, so the
+ * worker-side dataAdapterCache can be told when the last one goes away.
+ *
+ * ## Why a refcount and not just "track closed"
+ *
+ * An rpcSessionId is derived from the *adapter config* (BaseTrackModel's
+ * `rpcSessionId` getter is `adapterConfigCacheKey(adapter)`), so it is shared by
+ * every track model with that config — the same track shown in two linear genome
+ * views is two model instances with one id, as is a pair of tracks configured
+ * alike. Freeing on any close would evict an adapter the other view is still
+ * querying. The count is incremented per track model and the free only fires at
+ * zero.
+ *
+ * Counting here rather than walking the state tree at teardown keeps it exact:
+ * during a session teardown the tree is already coming apart, and "is any other
+ * track still using this?" is not a question worth asking of a half-destroyed
+ * tree.
+ *
+ * ## Why a WeakMap keyed on the rpcManager
+ *
+ * The counts belong to one session. Keying them on the session's own RpcManager
+ * means a discarded session's counts are collected with it, with no reset call
+ * for anyone to forget. This is the case the adapter cache itself cannot use —
+ * see dataAdapterCache — because here the key is a main-thread object whose
+ * lifetime already matches, rather than a string that crossed a worker boundary.
+ */
+const refcounts = new WeakMap();
+/**
+ * Whether there is an rpcManager to key counts on and to send a free to. A
+ * session model assembled without one — which model unit tests do routinely —
+ * should not make opening a track throw over what is only a cache hint, so both
+ * entry points degrade to no-ops. It also has to be an object before it can be
+ * a WeakMap key at all.
+ */
+function isUsable(rpcManager) {
+    return typeof rpcManager?.freeSession === 'function';
+}
+function countsFor(rpcManager) {
+    let counts = refcounts.get(rpcManager);
+    if (!counts) {
+        counts = new Map();
+        refcounts.set(rpcManager, counts);
+    }
+    return counts;
+}
+/** Record that a track model is using `sessionId`. Pair with release. */
+export function retainAdapterSession(rpcManager, sessionId) {
+    if (!isUsable(rpcManager)) {
+        return;
+    }
+    const counts = countsFor(rpcManager);
+    counts.set(sessionId, (counts.get(sessionId) ?? 0) + 1);
+}
+/**
+ * Give up one claim on `sessionId`. When the last one goes, ask the worker to
+ * drop the adapters cached under it — which is the only thing that ever makes
+ * them collectable, since the cache is a strong reference rooted in module
+ * scope.
+ *
+ * The free lands on the same driver the track's queries ran on, because every
+ * call in the app runs on the one the session resolved — and, under a worker
+ * pool, on the same worker, without booting one for a session that never
+ * dispatched anything. See `BaseRpcDriver.freeSession`.
+ *
+ * Errors are swallowed on purpose. This runs on teardown, where a worker
+ * already terminated by a session switch is the expected case rather than a
+ * fault, and nothing downstream could act on the failure anyway.
+ *
+ * Closing and immediately reopening the same track can race: the free is in
+ * flight while the reopened track re-retains, and the eviction lands on the
+ * adapter the new track just claimed. It costs that track one re-setup and
+ * heals itself on the next query, because an evicted adapter is only ever a
+ * cold cache. Sequencing it away would mean generation counters on a cache,
+ * which is a poor trade for a mis-click.
+ */
+export async function releaseAdapterSession(rpcManager, sessionId) {
+    if (!isUsable(rpcManager)) {
+        return;
+    }
+    const counts = countsFor(rpcManager);
+    // a release with no matching retain floors at zero and frees, rather than
+    // going negative and silently suppressing the next real free
+    const remaining = (counts.get(sessionId) ?? 1) - 1;
+    if (remaining > 0) {
+        counts.set(sessionId, remaining);
+        return;
+    }
+    counts.delete(sessionId);
+    try {
+        await rpcManager.freeSession(sessionId);
+    }
+    catch {
+        // teardown; see above
+    }
+}

package/esm/data_adapters/dataAdapterCache.d.ts

@@ -3,12 +3,63 @@ import type { AnyConfigurationSchemaType } from '../configuration/index.ts';
 import type { AnyDataAdapter } from './BaseAdapter/index.ts';
 import type { SnapshotIn } from '@jbrowse/mobx-state-tree';
 type ConfigSnap = SnapshotIn<AnyConfigurationSchemaType>;
+export declare function adapterConfigCacheKey(conf?: Record<string, unknown>): string;
+/**
+ * #api
+ * The `adapterCapabilities` entry of an adapter that reads the reference
+ * sequence of the assembly it is displayed against: BAM and SAM for mismatches
+ * without an MD tag, CRAM to rebuild bases, GC content and the reference scans
+ * for everything they answer. Such an adapter is built with that reference and
+ * keyed on it as well as on its config, so one config shown on two genomes is
+ * two instances, each reading its own, and an instance never changes reference
+ * for its life. Every other adapter keys on its config alone: a synteny adapter
+ * is fetched from each of its assemblies and reads no reference.
+ */
+export declare const READS_REFERENCE = "readsReference";
 interface AdapterCacheEntry {
     dataAdapter: AnyDataAdapter;
     sessionIds: Set<string>;
 }
-export declare function getAdapter(pluginManager: PluginManager, sessionId: string, adapterConfigSnapshot: SnapshotIn<AnyConfigurationSchemaType>): Promise<AdapterCacheEntry>;
+/**
+ * instantiate a data adapter, or return a cached one with the same config.
+ * `sequenceAdapter` is the reference of the genome the request names; a
+ * {@link READS_REFERENCE} type is keyed on it and built with it, any other
+ * type ignores it
+ */
+export declare function getAdapter(pluginManager: PluginManager, sessionId: string, adapterConfigSnapshot: SnapshotIn<AnyConfigurationSchemaType>, sequenceAdapter?: Record<string, unknown>): Promise<AdapterCacheEntry>;
+/**
+ * this is a callback that is passed to adapters that allows them to get any
+ * sub-adapters that they need internally, staying with the same worker session
+ * ID
+ */
 export type getSubAdapterType = (adapterConfigSnap: ConfigSnap) => ReturnType<typeof getAdapter>;
-export declare function freeAdapterResources(args: Record<string, any>): Promise<void>;
+/**
+ * Drop this session's claim on every cached adapter, and evict the ones no
+ * other session still claims. Reached from the CoreFreeResources RPC when the
+ * last track using an adapter config closes.
+ *
+ * Deleting the key is the whole reclamation: the cache is the only strong
+ * reference to an adapter, so once it goes the instance and everything it holds
+ * — a whole parsed GFF3, a BAM chunk cache — become unreachable and are
+ * collected normally. There is nothing to free by hand.
+ *
+ * "Collected normally" is not the same as "collected now", and for the indexed
+ * adapters it is not even soon. @gmod/bam, @gmod/cram and @gmod/tabix each hold
+ * their parsed chunks in a SharedReadCache that sweeps itself on a setInterval,
+ * and a pending timer is a GC root — so the instance stays reachable through its
+ * own sweep timer until that sweep empties the cache and stops itself, three
+ * minutes later. Measured: closing a panned alignments track reclaims nothing at
+ * the time it happens, and the worker falls from 296 MB to 7 MB four minutes on.
+ * Deleting the key is still the only thing to do here; just don't read a heap
+ * immediately after a close and conclude this did nothing.
+ *
+ * The refcount is what makes this safe to call on any track close: an adapter
+ * pulled in as a sub-adapter carries its parent's sessionId (getSubAdapter
+ * passes it straight through), so a sequence adapter shared by two alignments
+ * tracks survives either one of them closing.
+ */
+export declare function freeAdapterResources(args: {
+    sessionId?: string;
+}): Promise<void>;
 export declare function clearAdapterCache(): void;
 export {};