From 75580f2b0b0013fade034edd8c87629d93127169 Mon Sep 17 00:00:00 2001
From: Aaron Lisman <lisman.aaron@gmail.com>
Date: Sat, 17 Oct 2026 16:10:29 +0000
Subject: [PATCH 1/7] Stored id sets: a cohort from a long list of ids, kept on
 the server

A sampleList/patientList clause may now name a stored id set
({"kind":"sampleList","set":"<id>"}) instead of carrying its ids. The list
is saved once (POST /api/id-sets, or "+ Add cohort" -> "From a list of
ids"), matched to the studies' own samples or patients first (what matched
nothing is reported), and the document, its ?doc= link and every request
carry only the set's id.

Why: an inline list is written into the SQL. On msk_chord_2024 sample ids
hit ClickHouse's 256 KB max_query_size between 12,000 and 13,000 ids, each
view re-inlined the list, and the readback echoed it: at 10,000 ids every id
appeared four times in an 839 KB response. The ?doc= URL broke first, at
roughly 350 sample ids (Node refuses headers past 16 KB).

How:
- db/migrations/0006_id_sets.sql: id_set (owner, sharing columns as for
  custom datasets, members gzipped per study, immutable by trigger, soft
  delete) and id_set_access_log. lib/id-set-store.ts is the only module that
  touches them; access goes through lib/access.ts. Group deletion unshares
  sets too.
- lib/id-sets.ts: the per-request context. The compiler names one ClickHouse
  external table per set and study (IN (SELECT id FROM _idset_...)), and
  lib/ch.ts uploads it only with a statement that names it, only to the
  patient-level connection holding that study.
- lib/id-sets-server.ts: every engine route passes its body as `uses` to
  withRequestCustomData, which reads the sets it names as the signed-in
  principal. MCP, scripts and signed-out requests do not read sets, and such
  a clause is refused by name. carriesPatientIds counts a set as ids.
  Answers that read a set bypass the shared result cache (hasIdSets()).
- Inline lists are refused by name past INLINE_ID_SQL_LIMIT (200 KB of ids
  per study), pointing at stored sets, instead of ClickHouse's syntax error.
- Sharing an analysis or cohort wider than a set it names warns, as for
  custom datasets, and offers to share the reader's own sets the same way.
- DSL 2.7 (no-op upgrade step) so a 2.6 engine refuses a document naming a
  set rather than reading it as an empty list. Docs regenerated;
  DATA-BOUNDARY.md and PERFORMANCE.md updated.

Verified against the live warehouse with runAnalysis (compare + clinical):
all 25,040 msk_chord_2024 samples in 4.9 s, 416 B document, 23 KB response
(inline: fails); 60,000 samples across msk_chord_2024 + genie_public in
7.3 s, 504 B document, 45 KB response. Saving the 60k set took 0.9 s.
Tests: test/id-sets.test.ts (compile, request context, boundary, inline
limit); idSetContract on PGlite and Postgres (round trip, access, immutable
members, delete and unshare take effect at once: both mutation-checked);
e2e paste -> save -> add, with the set refused signed out, for another user
and after deletion. Gate (GATE_PORT=4111 scripts/gate.sh) passes.

Deploying needs `npm run db:migrate` for 0006 on the configured Postgres.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvdfHurd9t63GK2ToazMti
---
 CLAUDE.md                             |  14 +-
 app/api/analysis/method/route.ts      |   2 +-
 app/api/analysis/notebook/route.ts    |   2 +-
 app/api/analysis/route.ts             |   2 +-
 app/api/cell-explorer/route.ts        |   2 +-
 app/api/custom-data/members/route.ts  |   2 +-
 app/api/explore/route.ts              |   7 +-
 app/api/id-sets/[id]/route.ts         |  25 ++++
 app/api/id-sets/[id]/sharing/route.ts |  13 ++
 app/api/id-sets/route.ts              |  27 ++++
 app/api/oncoprint/route.ts            |   2 +-
 app/api/partition/route.ts            |   2 +-
 app/api/table/route.ts                |   2 +-
 app/api/view-page/route.ts            |   2 +-
 app/lab/add-cohort-dialog.tsx         | 113 +++++++++++++++-
 app/lab/api.ts                        |  10 ++
 app/lab/page.tsx                      |   1 +
 app/lab/pills.tsx                     |   3 +
 app/lab/saved-tab.tsx                 |   9 +-
 app/lab/share-dialog.tsx              |  16 +--
 db/migrations/0006_id_sets.sql        |  76 +++++++++++
 docs/DATA-BOUNDARY.md                 |  23 +++-
 docs/PERFORMANCE.md                   |  25 ++++
 docs/dsl.md                           |  28 +++-
 e2e.cjs                               |  47 +++++++
 lib/artifacts.ts                      |  23 +++-
 lib/ch.ts                             |   7 +-
 lib/cohort2.ts                        |  54 ++++++--
 lib/custom-data-server.ts             |  17 ++-
 lib/doc-version.ts                    |  13 +-
 lib/dsl-reference.ts                  |  26 +++-
 lib/federation.ts                     |   5 +-
 lib/groups.ts                         |   4 +-
 lib/id-set-import.ts                  |  51 ++++++++
 lib/id-set-store.ts                   | 178 ++++++++++++++++++++++++++
 lib/id-sets-server.ts                 |  37 ++++++
 lib/id-sets.ts                        | 126 ++++++++++++++++++
 lib/next-cache.ts                     |   9 +-
 lib/types.ts                          |   9 +-
 test/custom-store.test.ts             |   3 +-
 test/id-sets.test.ts                  |  82 ++++++++++++
 test/postgres.db-test.ts              |   7 +-
 test/support/store-contracts.ts       |  61 +++++++++
 43 files changed, 1091 insertions(+), 76 deletions(-)
 create mode 100644 app/api/id-sets/[id]/route.ts
 create mode 100644 app/api/id-sets/[id]/sharing/route.ts
 create mode 100644 app/api/id-sets/route.ts
 create mode 100644 db/migrations/0006_id_sets.sql
 create mode 100644 lib/id-set-import.ts
 create mode 100644 lib/id-set-store.ts
 create mode 100644 lib/id-sets-server.ts
 create mode 100644 lib/id-sets.ts
 create mode 100644 test/id-sets.test.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index 5b076572..e9029c97 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -200,6 +200,17 @@ ClickHouse SQL; clients never send SQL. Live at https://cbiolab.vercel.app (UI a
   enabled only where the deployment signs people in, each dataset its saver's. A document pins
   what it uses as `uploads: [{as, dataset, version}]` (added by the page on run); requests send
   `customRefs` and the server loads the pinned, immutable version.
+- **Stored id sets** — a cohort given as a long list of ids (`sampleList`/`patientList` with
+  `"set": "<id>"` instead of `"ids"`). **`lib/id-set-store.ts`** is the only module touching its
+  tables (`db/migrations/0006_id_sets.sql`): owned and shared by `lib/access.ts`, members
+  immutable (trigger), soft delete, every read logged. `lib/id-set-import.ts` matches a pasted list
+  to the studies' cases before saving (`POST /api/id-sets`; UI: "+ Add cohort" → "From a list of
+  ids"). Every engine route passes its body as `uses` to `withRequestCustomData`, which reads the
+  sets it names (`lib/id-sets-server.ts`) into **`lib/id-sets.ts`**'s request context; the compiler
+  then names one ClickHouse external table per set and study, and `lib/ch.ts` uploads it only to
+  the patient-level connection holding that study. A set is not read without a signed-in request
+  (MCP, scripts), and an answer that reads one bypasses the result cache (`hasIdSets()`). Inline
+  lists are refused by name past `INLINE_ID_SQL_LIMIT` (`lib/cohort2.ts`).
 - **Signing in** (`lib/auth.ts`, the header's Sign in) guards custom data, saved
   cohorts/analyses (`/api/artifacts`) and campaign changes; exploring, analyses, `?doc=` links and
   MCP need none. A deployment has ONE way in: an OpenID Connect provider (`lib/oidc.ts`;
@@ -311,7 +322,8 @@ ClickHouse SQL; clients never send SQL. Live at https://cbiolab.vercel.app (UI a
   Read before claiming this project is "fast": on a cached single chart the portal is ~20x
   quicker (those measurements predate the result cache of invariant 11, which answers only
   exact repeats), and our advantage is data movement (36x less to the
-  browser), not speed. Also records the ~20,000-id ceiling on explicit patient lists.
+  browser), not speed. Also records the ceiling on inline id lists (~12,000 sample ids) and the
+  stored id sets that remove it.
 
 ## Invariants — do not break these
 
diff --git a/app/api/analysis/method/route.ts b/app/api/analysis/method/route.ts
index 0446c064..32430597 100644
--- a/app/api/analysis/method/route.ts
+++ b/app/api/analysis/method/route.ts
@@ -12,7 +12,7 @@ export const maxDuration = 60;
 export async function POST(req: Request) {
   try {
     const { customData, customRefs, ...doc } = parseBody(AnalysisRequest, await req.json());
-    const result = await withRequestCustomData(customData, () => cachedAnalysis(doc as unknown as AnalysisDoc, { oncoprint: "spec" }), { refs: customRefs, req });
+    const result = await withRequestCustomData(customData, () => cachedAnalysis(doc as unknown as AnalysisDoc, { oncoprint: "spec" }), { refs: customRefs, req, uses: doc });
     const view = result.views[0];
     if (!view || view.error) return Response.json({ error: view ? view.error : "the document has no view" }, { status: 422 });
     return Response.json({ python: view.method?.python ?? null });
diff --git a/app/api/analysis/notebook/route.ts b/app/api/analysis/notebook/route.ts
index ee1cc2a2..04c7f026 100644
--- a/app/api/analysis/notebook/route.ts
+++ b/app/api/analysis/notebook/route.ts
@@ -31,7 +31,7 @@ export async function POST(req: Request) {
         view, method: view.method, files, missing, doc, viewIndex: notebookView.index,
         origin: process.env.APP_BASE_URL || new URL(req.url).origin,
       });
-    }, { refs: customRefs, req });
+    }, { refs: customRefs, req, uses: doc });
     const name = slug(notebookView.kind + "-" + String((doc as { study?: string }).study || "")) + ".ipynb";
     return new Response(JSON.stringify(nb), {
       headers: { "Content-Type": "application/x-ipynb+json; charset=utf-8", "Content-Disposition": `attachment; filename="${name}"` },
diff --git a/app/api/analysis/route.ts b/app/api/analysis/route.ts
index 4217656a..05b28321 100644
--- a/app/api/analysis/route.ts
+++ b/app/api/analysis/route.ts
@@ -14,7 +14,7 @@ export async function POST(req: Request) {
     const url = new URL(req.url);
     // the web app draws its own oncoprints; ?oncoprint=spec skips rendering them here
     const mode = url.searchParams.get("oncoprint") === "spec" ? "spec" as const : "svg" as const;
-    const result = await withRequestCustomData(customData, () => cachedAnalysis(doc as unknown as AnalysisDoc, { oncoprint: mode }), { refs: customRefs, req });
+    const result = await withRequestCustomData(customData, () => cachedAnalysis(doc as unknown as AnalysisDoc, { oncoprint: mode }), { refs: customRefs, req, uses: doc });
     // ?figures=svg: every view drawn by the shared server renderer, for a client that cannot draw
     if (url.searchParams.get("figures") === "svg")
       return Response.json({ ...result, views: result.views.map((v) => v.svg || v.error ? v : { ...v, svg: viewToSvg(v) || undefined }) });
diff --git a/app/api/cell-explorer/route.ts b/app/api/cell-explorer/route.ts
index 9db91e1e..99a029c9 100644
--- a/app/api/cell-explorer/route.ts
+++ b/app/api/cell-explorer/route.ts
@@ -11,7 +11,7 @@ export async function POST(req: Request) {
     const body = parseBody(CellExplorerRequest, await req.json());
     if (body.mode === "import") return Response.json(await cohortFromCells(body));
     const { customData, customRefs, doc, cohort } = body;
-    return Response.json(await withRequestCustomData(customData, () => cohortCellsLink({ doc, cohort }), { refs: customRefs, req }));
+    return Response.json(await withRequestCustomData(customData, () => cohortCellsLink({ doc, cohort }), { refs: customRefs, req, uses: doc }));
   } catch (e) {
     return Response.json({ error: String((e as Error)?.message || e) }, { status: 400 });
   }
diff --git a/app/api/custom-data/members/route.ts b/app/api/custom-data/members/route.ts
index 39ee090e..8482eea6 100644
--- a/app/api/custom-data/members/route.ts
+++ b/app/api/custom-data/members/route.ts
@@ -10,7 +10,7 @@ export const maxDuration = 60;
 export async function POST(req: Request) {
   try {
     const { customData, customRefs, def, studies } = parseBody(MembersRequest, await req.json());
-    return Response.json({ studies: await withRequestCustomData(customData, () => cohortMembership(def, studies.map(String)), { refs: customRefs, req }) });
+    return Response.json({ studies: await withRequestCustomData(customData, () => cohortMembership(def, studies.map(String)), { refs: customRefs, req, uses: def }) });
   } catch (e) {
     return Response.json({ error: String((e as Error)?.message || e) }, { status: 400 });
   }
diff --git a/app/api/explore/route.ts b/app/api/explore/route.ts
index 09a7782b..bb48ff0b 100644
--- a/app/api/explore/route.ts
+++ b/app/api/explore/route.ts
@@ -10,6 +10,7 @@ import { studyProfiles, resolveStudy } from "../../../lib/analysis.ts";
 import { chQuery } from "../../../lib/ch.ts";
 import { withRequestCustomData } from "../../../lib/custom-data-server.ts";
 import { assertCustomDataPresent } from "../../../lib/custom-data.ts";
+import { idSetRefsIn } from "../../../lib/id-sets.ts";
 import type { DerivedRequest } from "../../../lib/types.ts";
 
 export const maxDuration = 60;
@@ -32,9 +33,9 @@ export async function POST(req: Request) {
 async function handle(req: Request) {
   try {
     const { customData, customRefs, ...body } = parseBody(ExploreRequest, await req.json());
-    // facets over uploaded data are the uploader's alone: answered directly, never cached
-    if ((Array.isArray(customData) && customData.length) || (Array.isArray(customRefs) && customRefs.length))
-      return Response.json(await withRequestCustomData(customData, () => ensureChContext(() => exploreFor(body)), { refs: customRefs, req }));
+    // facets over uploaded data or a stored id set are their reader's alone: answered directly, never cached
+    if ((Array.isArray(customData) && customData.length) || (Array.isArray(customRefs) && customRefs.length) || idSetRefsIn(body.draft).length)
+      return Response.json(await withRequestCustomData(customData, () => ensureChContext(() => exploreFor(body)), { refs: customRefs, req, uses: body.draft }));
     return Response.json(await throughCache(async () => exploreEntry(body, await dataVersion()), () => ensureChContext(() => exploreFor(body))));
   } catch (e) {
     // The reader superseded this request: not a failure, and there is nobody left to tell.
diff --git a/app/api/id-sets/[id]/route.ts b/app/api/id-sets/[id]/route.ts
new file mode 100644
index 00000000..5f107971
--- /dev/null
+++ b/app/api/id-sets/[id]/route.ts
@@ -0,0 +1,25 @@
+import { requirePrincipal, AccessError } from "../../../../lib/auth.ts";
+import { getIdSet, readIdSet, deleteIdSet } from "../../../../lib/id-set-store.ts";
+
+const fail = (e: unknown) => Response.json({ error: String((e as Error)?.message || e) }, { status: e instanceof AccessError ? e.status : 400 });
+
+/** One set's description; with `?ids=1`, its ids too, one "<study>:<id>" per line (that read is logged). */
+export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  try {
+    const { id } = await params;
+    const principal = requirePrincipal(req, "use stored id sets");
+    if (new URL(req.url).searchParams.get("ids") !== "1") return Response.json({ set: await getIdSet(principal, id) });
+    const { perStudy } = await readIdSet(principal, id);
+    const text = Object.entries(perStudy).flatMap(([study, ids]) => ids.map((x) => study + ":" + x)).join("\n") + "\n";
+    return new Response(text, { headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "private, no-store" } });
+  } catch (e) { return fail(e); }
+}
+
+/** Delete (its owner only): documents naming it are refused from then on, saying when it went. */
+export async function DELETE(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  try {
+    const { id } = await params;
+    await deleteIdSet(requirePrincipal(req, "use stored id sets"), id);
+    return Response.json({ deleted: true });
+  } catch (e) { return fail(e); }
+}
diff --git a/app/api/id-sets/[id]/sharing/route.ts b/app/api/id-sets/[id]/sharing/route.ts
new file mode 100644
index 00000000..11b1b199
--- /dev/null
+++ b/app/api/id-sets/[id]/sharing/route.ts
@@ -0,0 +1,13 @@
+import { requirePrincipal, AccessError } from "../../../../../lib/auth.ts";
+import { shareIdSet } from "../../../../../lib/id-set-store.ts";
+
+// Who a stored id set is shared with (its owner only; lib/access.ts). Body as for
+// /api/artifacts/[id]/sharing. Its ids are patient-level: nothing shares them but this.
+export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  try {
+    const { id } = await params;
+    return Response.json({ set: await shareIdSet(requirePrincipal(req, "use stored id sets"), id, await req.json().catch(() => null)) });
+  } catch (e) {
+    return Response.json({ error: String((e as Error)?.message || e) }, { status: e instanceof AccessError ? e.status : 400 });
+  }
+}
diff --git a/app/api/id-sets/route.ts b/app/api/id-sets/route.ts
new file mode 100644
index 00000000..d01cf9bf
--- /dev/null
+++ b/app/api/id-sets/route.ts
@@ -0,0 +1,27 @@
+import { connection } from "next/server";
+import { requirePrincipal, AccessError } from "../../../lib/auth.ts";
+import { listIdSets } from "../../../lib/id-set-store.ts";
+import { createIdSet } from "../../../lib/id-set-import.ts";
+
+export const maxDuration = 60;
+
+const fail = (e: unknown) => Response.json({ error: String((e as Error)?.message || e) }, { status: e instanceof AccessError ? e.status : 400 });
+
+/** The stored id sets this reader may use, without their ids. */
+export async function GET(req: Request) {
+  // rendered per request: without it the build prerenders whatever the login check answers then
+  await connection();
+  try { return Response.json({ sets: await listIdSets(requirePrincipal(req, "use stored id sets")) }); }
+  catch (e) { return fail(e); }
+}
+
+/**
+ * Save a list of ids as a stored set: `{ name, level, studies, ids }`. The ids are matched to the
+ * studies' own samples or patients first; the answer is the set and what did not match.
+ */
+export async function POST(req: Request) {
+  try {
+    const principal = requirePrincipal(req, "save stored id sets");
+    return Response.json(await createIdSet(principal, await req.json()), { status: 201 });
+  } catch (e) { return fail(e); }
+}
diff --git a/app/api/oncoprint/route.ts b/app/api/oncoprint/route.ts
index 81011ec6..5fcb35cb 100644
--- a/app/api/oncoprint/route.ts
+++ b/app/api/oncoprint/route.ts
@@ -19,7 +19,7 @@ export async function POST(req: Request) {
     const sp = new URL(req.url).searchParams;
     // a provenance request is answered with the queries that built the (cached) contract
     const provenance = sp.get("provenance") === "1";
-    const contract = await withRequestCustomData(customData, () => cachedContract(spec, { provenance }), { refs: customRefs, req });
+    const contract = await withRequestCustomData(customData, () => cachedContract(spec, { provenance }), { refs: customRefs, req, uses: spec });
     const engineMs = Date.now() - t0;
     const fmt = sp.get("format");
     if (fmt === "svg" || fmt === "tsv") {
diff --git a/app/api/partition/route.ts b/app/api/partition/route.ts
index 18ec0837..4e58cd56 100644
--- a/app/api/partition/route.ts
+++ b/app/api/partition/route.ts
@@ -9,7 +9,7 @@ export const maxDuration = 60;
 export async function POST(req: Request) {
   try {
     const { customData, customRefs, ...body } = parseBody(PartitionRequest, await req.json());
-    return Response.json(await withRequestCustomData(customData, () => proposePartition(body as unknown as Parameters<typeof proposePartition>[0]), { refs: customRefs, req }));
+    return Response.json(await withRequestCustomData(customData, () => proposePartition(body as unknown as Parameters<typeof proposePartition>[0]), { refs: customRefs, req, uses: body }));
   } catch (e) {
     return Response.json({ error: String((e as Error)?.message || e) }, { status: 400 });
   }
diff --git a/app/api/table/route.ts b/app/api/table/route.ts
index e5d4ed2d..7f688082 100644
--- a/app/api/table/route.ts
+++ b/app/api/table/route.ts
@@ -33,7 +33,7 @@ export async function POST(req: Request) {
   } catch (e) {
     return new Response("cannot download: " + String((e as Error)?.message || e) + "\n", { status: 400, headers: { "content-type": "text/plain; charset=utf-8" } });
   }
-  const run = <T,>(fn: () => Promise<T>) => withRequestCustomData(body.customData, fn, { refs: body.customRefs, req });
+  const run = <T,>(fn: () => Promise<T>) => withRequestCustomData(body.customData, fn, { refs: body.customRefs, req, uses: body });
   const table = typeof body.table === "string" ? body.table : undefined;
   const first = await run(() => runAnalysis(doc, { table })).catch((e) => ({ views: [{ kind: "", cohorts: [], error: String((e as Error)?.message || e) } as ViewResult] }));
   const v = first.views[0];
diff --git a/app/api/view-page/route.ts b/app/api/view-page/route.ts
index 67372b9b..1a76f893 100644
--- a/app/api/view-page/route.ts
+++ b/app/api/view-page/route.ts
@@ -23,7 +23,7 @@ export async function POST(req: Request) {
     const view = Array.isArray(doc.views) ? doc.views[vi] : null;
     if (!view || !PAGED_KINDS.includes(view.kind)) throw new Error("view " + body.view + " is not a table view (" + PAGED_KINDS.join(", ") + ")");
     const one = { ...doc, views: [view] };
-    const run = (opts: Parameters<typeof runAnalysis>[1]) => withRequestCustomData(customData, () => runAnalysis(one, opts), { refs: customRefs, req });
+    const run = (opts: Parameters<typeof runAnalysis>[1]) => withRequestCustomData(customData, () => runAnalysis(one, opts), { refs: customRefs, req, uses: one });
     const pick = (r: Awaited<ReturnType<typeof runAnalysis>>) => {
       const v = r.views[0];
       const t = pagedTable(v, body.table);
diff --git a/app/lab/add-cohort-dialog.tsx b/app/lab/add-cohort-dialog.tsx
index 9934a526..14775762 100644
--- a/app/lab/add-cohort-dialog.tsx
+++ b/app/lab/add-cohort-dialog.tsx
@@ -1,7 +1,7 @@
 "use client";
-// "+ Add cohort" on a view: one dialog with the three places a cohort comes from — the analysis's
-// own cohorts, the library (the login's saved cohorts and the built-in examples), and Explore,
-// where a new one is built and comes back to this view.
+// "+ Add cohort" on a view: one dialog with the places a cohort comes from — the analysis's own
+// cohorts, the library (the login's saved cohorts and the built-in examples), Explore, where a new
+// one is built and comes back to this view, and a pasted list of ids, saved as a stored id set.
 import { useEffect, useState } from "react";
 import { Plus } from "lucide-react";
 import type { CohortDef } from "../../lib/types.ts";
@@ -13,6 +13,7 @@ import { Dialog, DialogContent, DialogHeader, DialogTitle } from "../_ui/dialog"
 import { Input } from "../_ui/input";
 import { Tabs, TabsList, TabsTrigger } from "../_ui/tabs";
 import { TB } from "../_ui/toolbar.ts";
+import { cn } from "../../lib/cn";
 import { Textarea } from "../_ui/textarea";
 import { api } from "./api.ts";
 import type { CellExplorerDataset } from "../../lib/cell-explorer.ts";
@@ -36,13 +37,15 @@ export interface LibraryState {
   examples: { name: string; desc: string; def: CohortDef }[];
 }
 
-type Source = "analysis" | "library" | "explore" | "cells";
+type Source = "analysis" | "library" | "explore" | "list" | "cells";
 
-export function AddCohortDialog({ target, analysis, library, onAdd, onExplore, onLogin, onClose, cells }: {
+export function AddCohortDialog({ target, analysis, library, studies, onAdd, onExplore, onLogin, onClose, cells }: {
   target: AddCohortTarget | null;
   /** the analysis's cohorts in its order (the colour each has in its summary), with their sizes once known */
   analysis: { name: string; def: CohortDef; count: number | null; views: string[] }[];
   library: LibraryState;
+  /** the studies the analysis uses: a pasted bare id is looked up in each */
+  studies: string[];
   /** add a cohort to the view: an analysis cohort by name, or a library one with its definition */
   onAdd: (name: string, def?: CohortDef) => void;
   onExplore: () => void;
@@ -110,6 +113,7 @@ export function AddCohortDialog({ target, analysis, library, onAdd, onExplore, o
             <TabsTrigger value="analysis" className="px-3 text-md">In this analysis <span className="text-muted-foreground">{available.length}</span></TabsTrigger>
             <TabsTrigger value="library" className="px-3 text-md">Library</TabsTrigger>
             <TabsTrigger value="explore" className="px-3 text-md">Build in Explore</TabsTrigger>
+            <TabsTrigger value="list" className="px-3 text-md">From a list of ids</TabsTrigger>
             {cells && <TabsTrigger value="cells" className="px-3 text-md">From Cell Explorer</TabsTrigger>}
           </TabsList>
         </Tabs>
@@ -160,6 +164,8 @@ export function AddCohortDialog({ target, analysis, library, onAdd, onExplore, o
             <Button disabled={full} title={full ? addTitle("") : undefined} onClick={onExplore}>Open Explore</Button>
           </div>
         )}
+        {source === "list" && <ListSource studies={studies} saved={library.saved} full={full} replaces={replaces} addTitle={addTitle}
+          nameFor={libraryName} onAdd={onAdd} onLogin={onLogin} />}
         {source === "cells" && cells && <CellsSource cells={cells} full={full} replaces={replaces} addTitle={addTitle}
           nameFor={libraryName} onAdd={onAdd} />}
       </DialogContent>}
@@ -225,3 +231,100 @@ function CellsSource({ cells, full, replaces, addTitle, nameFor, onAdd }: {
     </div>
   );
 }
+
+/** One id per line, or separated by commas, semicolons, tabs or spaces. */
+const splitIds = (text: string): string[] => text.split(/[\s,;]+/).map((x) => x.trim()).filter(Boolean);
+
+interface SavedSet {
+  set: { id: string; name: string; level: "sample" | "patient"; studies: string[]; count: number };
+  unmatched: number; unmatchedExamples: string[]; duplicates: number; multiStudy: number;
+  refused: { study: string; reason: string }[];
+}
+
+/**
+ * A cohort from a pasted list of sample or patient ids. The list is matched to the studies' own
+ * cases and saved on the server as a stored id set (lib/id-set-store.ts); the cohort names the
+ * set by its id, so the document and its link stay small however long the list is. Needs a
+ * sign-in, since the set is its saver's. The text stays in this component while it is typed.
+ */
+function ListSource({ studies, saved, full, replaces, addTitle, nameFor, onAdd, onLogin }: {
+  studies: string[]; saved: LibraryState["saved"]; full: boolean; replaces: boolean; addTitle: (what: string) => string;
+  nameFor: (name: string, def: CohortDef) => string; onAdd: (name: string, def?: CohortDef) => void; onLogin: () => void;
+}) {
+  const [text, setText] = useState("");
+  const [level, setLevel] = useState<"sample" | "patient">("sample");
+  const [name, setName] = useState("from a list");
+  const [busy, setBusy] = useState(false);
+  const [err, setErr] = useState<string | null>(null);
+  const [done, setDone] = useState<SavedSet | null>(null);
+  if (saved === "off") return <p className="note">A list of ids is kept on the server as a stored id set, which needs a sign-in, and this deployment has none.</p>;
+  if (saved === "locked") return <p className="note"><Button variant="link" size="inline" className="text-md" onClick={onLogin}>Sign in</Button> to add a cohort from a list of ids: the list is kept on the server as your stored id set.</p>;
+  const ids = splitIds(text);
+  const save = async () => {
+    setBusy(true); setErr(null); setDone(null);
+    try {
+      const res = await api.idSets.create({ name: name.trim() || "from a list", level, studies, ids });
+      const j = await res.json();
+      if (!res.ok || j.error) throw new Error(j.error || res.statusText);
+      setDone(j);
+    } catch (e) { setErr(String((e as Error)?.message || e)); }
+    finally { setBusy(false); }
+  };
+  const def: CohortDef | null = done ? {
+    all: [{ kind: done.set.level === "sample" ? "sampleList" : "patientList", set: done.set.id, label: done.set.name, n: done.set.count }],
+    ...(done.set.studies.length > 1 ? { studies: done.set.studies } : done.set.studies[0] !== studies[0] ? { study: done.set.studies[0] } : {}),
+  } : null;
+  const as = def ? nameFor(done!.set.name, def) : name.trim();
+  const noun = level === "sample" ? "sample" : "patient";
+  return (
+    <div className="acd-list-ids flex flex-col gap-2.5">
+      <p className="note mt-0">
+        Paste {noun} ids, one per line or separated by commas or spaces, as <code>study:id</code> or bare ids, which are looked
+        up in {studies.length ? studies.join(", ") : "the analysis's study"}. The ids are matched to the {noun}s there and kept on
+        the server as a stored id set; the cohort names the set, so the analysis and its links stay small however long the list is.
+      </p>
+      <div className="viewtb">
+        <div className="tbz">
+          <span className="tbl">ids are</span>
+          <Tabs value={level} onValueChange={(v) => { setLevel(v as "sample" | "patient"); setDone(null); }}>
+            <TabsList className="h-ctl">
+              <TabsTrigger value="sample" className="px-2.5 text-md">samples</TabsTrigger>
+              <TabsTrigger value="patient" className="px-2.5 text-md">patients</TabsTrigger>
+            </TabsList>
+          </Tabs>
+        </div>
+      </div>
+      <Textarea aria-label={noun + " ids"} rows={6} className="font-mono text-md md:text-md" value={text}
+        placeholder={level === "sample" ? "P-0000012-T01-IM3\nP-0000015-T01-IM3\n…" : "P-0000012\nP-0000015\n…"}
+        onChange={(e) => { setText(e.target.value); setDone(null); }} />
+      <div className="viewtb">
+        <div className="tbz">
+          <label className="tbfield">name <Input aria-label="set name" className="h-ctl w-56 text-md md:text-md" value={name}
+            onChange={(e) => { setName(e.target.value); setDone(null); }} /></label>
+          <Button variant="outline" size="sm" className={cn(TB, "idsetsave")} disabled={busy || !ids.length || !studies.length}
+            title={!studies.length ? "the analysis names no study to match the ids in" : !ids.length ? "paste some ids first" : undefined}
+            onClick={() => void save()}>
+            {busy && <span className="spinner" />}Match and save {ids.length ? ids.length.toLocaleString() + " id" + (ids.length === 1 ? "" : "s") : ""}</Button>
+        </div>
+      </div>
+      {err && <p className="error m-0">{err}</p>}
+      {done && def && <>
+        <p className="note m-0 idsetresult">
+          Saved “{done.set.name}”: <strong>{done.set.count.toLocaleString()}</strong> {noun}{done.set.count === 1 ? "" : "s"}
+          {done.set.studies.length > 1 ? " across " + done.set.studies.length + " studies" : " in " + done.set.studies[0]}
+          {done.unmatched > 0 && <> · <span className="text-destructive">{done.unmatched.toLocaleString()} matched no {noun}</span>: {done.unmatchedExamples.slice(0, 5).join(", ")}{done.unmatched > 5 ? ", …" : ""}</>}
+          {done.duplicates > 0 && <> · {done.duplicates.toLocaleString()} given more than once</>}
+          {done.multiStudy > 0 && <> · {done.multiStudy.toLocaleString()} found in more than one study, kept in each</>}
+          {done.refused.length > 0 && <> · not matched in {done.refused.map((r) => r.study + " (" + r.reason + ")").join(", ")}</>}
+        </p>
+        <div className="viewtb">
+          <div className="tbz">
+            <Button variant="outline" size="sm" className={TB} disabled={full} title={addTitle("“" + as + "”")}
+              onClick={() => onAdd(as, def)}>{replaces ? "Use" : <><Plus />Add</>}</Button>
+          </div>
+        </div>
+        {as !== done.set.name && <p className="meta m-0">added as “{as}”, since this analysis already has a different “{done.set.name}”</p>}
+      </>}
+    </div>
+  );
+}
diff --git a/app/lab/api.ts b/app/lab/api.ts
index 72077144..a821188d 100644
--- a/app/lab/api.ts
+++ b/app/lab/api.ts
@@ -84,6 +84,16 @@ export const api = {
     share: (id: string, sharing: Sharing) => send("PUT", "/api/artifacts/" + id + "/sharing", sharing),
   },
 
+  /** Stored id sets (lib/id-set-store.ts): cohorts given as long lists of ids, kept on the server and named by id. */
+  idSets: {
+    list: (opts: Opts = {}) => fetch("/api/id-sets", { signal: opts.signal }),
+    /** match `ids` ("<study>:<id>" or bare, looked up in every study given) and save the matches; answers what did not match */
+    create: (body: { name: string; level: "sample" | "patient"; studies: string[]; ids: string[] }) => post("/api/id-sets", body),
+    remove: (id: string) => fetch("/api/id-sets/" + id, { method: "DELETE" }),
+    /** who it is shared with (its owner only) */
+    share: (id: string, sharing: Sharing) => send("PUT", "/api/id-sets/" + id + "/sharing", sharing),
+  },
+
   /** Groups (lib/groups.ts): the reader's, and managing one. */
   groups: {
     list: (opts: Opts = {}) => fetch("/api/groups", { signal: opts.signal }),
diff --git a/app/lab/page.tsx b/app/lab/page.tsx
index e9ded45a..c7ec4a80 100644
--- a/app/lab/page.tsx
+++ b/app/lab/page.tsx
@@ -489,6 +489,7 @@ export default function AnalysisPage() {
           examples: EXAMPLES,
         }}
         onAdd={(name, def) => { if (chooser) addCohortToView(chooser, name, def); }}
+        studies={analysisStudies()}
         onExplore={() => { if (!chooser) return; const t = chooser; setChooser(null); openAddCohort(t); }}
         onLogin={requestLogin}
         cells={cellExplorerFor(doc.study || study)}
diff --git a/app/lab/pills.tsx b/app/lab/pills.tsx
index 7a1a08e3..7b807fb4 100644
--- a/app/lab/pills.tsx
+++ b/app/lab/pills.tsx
@@ -95,6 +95,9 @@ function leafText(leaf: any) {
   if (k === "genomicData") return `${leaf.gene} ${leaf.profileType} ` + (leaf.range ? Object.entries(leaf.range).map(([a, b]) => ({ gt: ">", gte: "≥", lt: "<", lte: "≤" }[a] || a) + b).join(" ") : "");
   if (k === "genericAssay") return `${leaf.entity} ` + JSON.stringify(leaf.range || leaf.values);
   if (k === "sampleList" || k === "patientList") {
+    // a stored set: its name and size as the page wrote them beside the reference (never compiled)
+    if (typeof leaf.set === "string")
+      return (leaf.label ? "“" + leaf.label + "”" : "stored set") + (typeof leaf.n === "number" ? ` · ${leaf.n.toLocaleString()} listed` : "");
     const ids = leaf.ids || [];
     const studies = new Set(ids.map((s: string) => String(s).split(":")[0]).filter(Boolean));
     return `${ids.length} listed` + (studies.size > 1 ? ` (${studies.size} studies)` : "");
diff --git a/app/lab/saved-tab.tsx b/app/lab/saved-tab.tsx
index 8427db39..631b4c2c 100644
--- a/app/lab/saved-tab.tsx
+++ b/app/lab/saved-tab.tsx
@@ -7,6 +7,7 @@ import CohortPills, { type OnCustomData } from "./pills";
 import { ShareDialog, sharingLabel } from "./share-dialog.tsx";
 import { useGroups } from "./use-groups.ts";
 import { shareServerDataset } from "./custom-data-client.ts";
+import { api } from "./api.ts";
 import type { ArtifactKind } from "../../lib/artifacts.ts";
 import type { Sharing } from "../../lib/access.ts";
 import { Waiting } from "../_oncoprint/OncoprintCard.tsx";
@@ -210,7 +211,13 @@ export function SavedTab({
     {sharing && <ShareDialog kind={sharing.kind === "workspace" ? "analysis" : "cohort"} name={sharing.name} sharing={sharing.sharing}
       groups={groups.groups} groupsError={groups.error}
       onSave={(s) => saved.share(sharing.kind, sharing.id, s)}
-      onShareDatasets={async (ids, s) => { for (const id of ids) await shareServerDataset(id, s); }}
+      onShareDatasets={async (items, s) => {
+        for (const w of items) {
+          if (w.kind !== "idSet") { await shareServerDataset(w.id, s); continue; }
+          const res = await api.idSets.share(w.id, s);
+          if (!res.ok) throw new Error((await res.json().catch(() => null))?.error || res.statusText);
+        }
+      }}
       onClose={() => setSharing(null)} />}
   </div>;
 }
diff --git a/app/lab/share-dialog.tsx b/app/lab/share-dialog.tsx
index 98dbf3b0..b0c18ab6 100644
--- a/app/lab/share-dialog.tsx
+++ b/app/lab/share-dialog.tsx
@@ -38,8 +38,8 @@ export function ShareDialog({ kind, name, sharing, groups, groupsError, onSave,
   groupsError: string | null;
   /** saves the sharing; for an analysis, answers the datasets its audience could not read */
   onSave: (s: Sharing) => Promise<DatasetWarning[] | void>;
-  /** share the reader's own datasets in `warnings` the way this analysis now is */
-  onShareDatasets?: (ids: string[], s: Sharing) => Promise<void>;
+  /** share the reader's own datasets and id sets in `warnings` the way this analysis now is */
+  onShareDatasets?: (items: DatasetWarning[], s: Sharing) => Promise<void>;
   onClose: () => void;
 }) {
   const [visibility, setVisibility] = useState<Visibility>(sharing.visibility);
@@ -67,7 +67,7 @@ export function ShareDialog({ kind, name, sharing, groups, groupsError, onSave,
   const shareDatasets = async () => {
     if (!onShareDatasets || !warnings || !savedAs) return;
     setBusy(true); setErr(null);
-    try { await onShareDatasets(warnings.filter((w) => w.yours).map((w) => w.id), { ...savedAs, groupCanEdit: false }); onClose(); }
+    try { await onShareDatasets(warnings.filter((w) => w.yours), { ...savedAs, groupCanEdit: false }); onClose(); }
     catch (e) { setErr(String((e as Error)?.message || e)); }
     finally { setBusy(false); }
   };
@@ -84,18 +84,18 @@ export function ShareDialog({ kind, name, sharing, groups, groupsError, onSave,
       <DialogContent data-tw aria-describedby={undefined} className="sharedialog gap-0 sm:max-w-md">
         {warnings ? (
           <form onSubmit={(e) => { e.preventDefault(); void shareDatasets(); }} className="flex flex-col gap-3">
-            <DialogHeader><DialogTitle className="text-base">Shared — but some of its custom data is not</DialogTitle></DialogHeader>
-            <p className={cn(META, "m-0")}>Some people who can now see “{name}” cannot read custom data it uses, so its views that use it will not run for them:</p>
+            <DialogHeader><DialogTitle className="text-base">Shared — but some of the data it uses is not</DialogTitle></DialogHeader>
+            <p className={cn(META, "m-0")}>Some people who can now see “{name}” cannot read custom data or stored id sets it uses, so what uses them will not run for them:</p>
             <ul className="sharewarn m-0 grid gap-1 pl-4 text-sm">
-              {warnings.map((w) => <li key={w.id}><strong>{w.name}</strong> <code>custom:{w.slug}</code> — shared with {sharingLabel({ visibility: w.visibility, groupId: null, groupCanEdit: false, groupName: w.groupName })}
+              {warnings.map((w) => <li key={w.id}><strong>{w.name}</strong> {w.kind === "idSet" ? "(stored id set)" : <code>custom:{w.slug}</code>} — shared with {sharingLabel({ visibility: w.visibility, groupId: null, groupCanEdit: false, groupName: w.groupName })}
                 {w.yours ? "" : " (not yours: ask its owner to share it)"}</li>)}
             </ul>
-            {warnings.some((w) => w.yours) && <p className="note m-0">Custom data holds patient-level values: whoever you share it with can read every row.</p>}
+            {warnings.some((w) => w.yours) && <p className="note m-0">Custom data and id sets hold patient-level data: whoever you share them with can read every row and id.</p>}
             {err && <p className="error m-0">{err}</p>}
             <DialogFooter className="mt-1 items-center">
               <Button type="button" variant="ghost" onClick={onClose}>Leave it</Button>
               {warnings.some((w) => w.yours) && <Button type="submit" disabled={busy}>
-                {busy ? "sharing…" : "Share my datasets the same way"}</Button>}
+                {busy ? "sharing…" : "Share mine the same way"}</Button>}
             </DialogFooter>
           </form>
         ) : (
diff --git a/db/migrations/0006_id_sets.sql b/db/migrations/0006_id_sets.sql
new file mode 100644
index 00000000..ce04287e
--- /dev/null
+++ b/db/migrations/0006_id_sets.sql
@@ -0,0 +1,76 @@
+-- Stored id sets: a cohort given as a list of sample or patient ids, kept on the server so a
+-- document names it by id (`{"kind":"sampleList","set":"<uuid>"}`) instead of carrying every id
+-- in its JSON, its ?doc= link and every request (lib/id-set-store.ts, lib/id-sets.ts).
+--
+-- LIKE custom_dataset, these tables hold patient and sample identifiers. They are reached only
+-- through lib/id-set-store.ts, which checks access on every read and write and logs every read;
+-- never query them from anywhere else.
+--
+-- A set's members never change once written (a trigger refuses it): a document that names a set
+-- always means the same samples. A different list is a new set. Its name and sharing may change.
+--
+-- Applied by `npm run db:migrate` (lib/migrate.ts), after 0005. Re-runnable.
+
+create table if not exists id_set (
+  id uuid primary key default gen_random_uuid(),
+  name text not null check (length(btrim(name)) between 1 and 200),
+  owner_id uuid not null references app_user (id),
+  level text not null check (level in ('patient', 'sample')),
+  studies text[] not null,
+  -- how many ids it holds, and per study (jsonb {study: n})
+  id_count integer not null,
+  per_study jsonb not null,
+  -- the members as gzipped JSON ({study: [bare id, ...]}): read whole, never queried
+  ids_gz bytea not null,
+  sha256 text not null,
+  -- how the list was matched when it was saved: ids given, unmatched, duplicates
+  source jsonb not null,
+  visibility text not null default 'private',
+  group_id uuid references user_group (id),
+  group_can_edit boolean not null default false,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  -- soft delete: a document naming a deleted set is refused with this date, rather than its
+  -- cohort silently becoming empty
+  deleted_at timestamptz,
+  constraint id_set_sharing check (
+    visibility in ('private', 'group', 'public')
+    and (group_id is not null) = (visibility = 'group' or group_can_edit)
+    and (not group_can_edit or visibility <> 'private'))
+);
+create index if not exists id_set_owner_idx on id_set (owner_id, created_at desc);
+create index if not exists id_set_group_idx on id_set (group_id) where group_id is not null;
+
+create or replace function id_set_members_immutable() returns trigger as $$
+begin
+  if tg_op = 'DELETE' then
+    raise exception 'id sets are never deleted: they are soft-deleted (deleted_at), so a document naming one is refused rather than reading nothing';
+  end if;
+  if new.level is distinct from old.level or new.studies is distinct from old.studies
+     or new.id_count is distinct from old.id_count or new.per_study is distinct from old.per_study
+     or new.ids_gz is distinct from old.ids_gz or new.sha256 is distinct from old.sha256
+     or new.owner_id is distinct from old.owner_id or new.created_at is distinct from old.created_at then
+    raise exception 'an id set''s members are immutable: save a new set instead';
+  end if;
+  return new;
+end;
+$$ language plpgsql;
+
+drop trigger if exists id_set_immutable on id_set;
+create trigger id_set_immutable
+  before update or delete on id_set
+  for each row execute function id_set_members_immutable();
+
+drop trigger if exists id_set_set_updated_at on id_set;
+create trigger id_set_set_updated_at
+  before update on id_set
+  for each row execute function set_updated_at();
+
+-- Every read of members and every write, by whom.
+create table if not exists id_set_access_log (
+  at timestamptz not null default now(),
+  principal text not null,
+  action text not null check (action in ('read', 'create', 'delete')),
+  set_id uuid not null
+);
+create index if not exists id_set_access_log_set_idx on id_set_access_log (set_id, at desc);
diff --git a/docs/DATA-BOUNDARY.md b/docs/DATA-BOUNDARY.md
index 6225ab7d..403bba63 100644
--- a/docs/DATA-BOUNDARY.md
+++ b/docs/DATA-BOUNDARY.md
@@ -42,7 +42,8 @@ arithmetic is identical whether a participant is a local connection or a remote
 peer, so the transport cannot change a result.
 
 **3. `carriesPatientIds()` guards the one clause that carries identifiers.** A
-`patients` leaf embeds explicit ids into compiled SQL. It is refused for
+`sampleList`/`patientList` leaf embeds explicit ids into compiled SQL, or names a
+stored set whose ids travel beside it. It is refused for
 aggregate-only participants — checked in the resolver, again in the remote
 client *before any network call*, and independently by the peer's own MCP tool,
 which does not trust the caller to have checked.
@@ -284,6 +285,26 @@ suite fail. A test that cannot fail is decoration.
   (filtered by study in SQL), since that instance already holds patient-level
   data for the study they belong to.
 
+- **Stored id sets are patient-level too, and follow the same rules.** A long
+  `sampleList`/`patientList` is saved on the server (`lib/id-set-store.ts`,
+  `db/migrations/0006`) and named by a document as `"set": "<id>"`, so the ids
+  are in neither the document, its `?doc=` link nor the request. A route reads
+  the sets its body names as the request's signed-in principal
+  (`withRequestIdSets` in `lib/id-sets-server.ts`, reached through
+  `withRequestCustomData`), and each study's ids go only to the connection of
+  the patient-level instance holding that study: `lib/ch.ts` uploads a set's
+  table (`idSetExternalsFor` in `lib/id-sets.ts`) only with a statement that
+  names it, and refuses any other connection. `carriesPatientIds()` counts a
+  `set` as identifiers, so such a cohort is refused for an aggregate-only or
+  remote participant before any request is made. Sets are owned and shared by
+  `lib/access.ts`, their members are immutable (a trigger), deletion is a soft
+  delete that a document naming the set reports, every read and write is logged
+  (`id_set_access_log`), and answers that read one are never written to the
+  shared result cache (`hasIdSets()`). Without a signed-in request (MCP, a script,
+  a signed-out link) a set is not read at all, and the clause is refused by name.
+  Covered by `test/id-sets.test.ts` and `idSetContract` in
+  `test/support/store-contracts.ts`.
+
 ## If you are about to weaken this
 
 Don't. If a feature seems to require patient-level data from an aggregate-only
diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md
index a25fdae8..20d50036 100644
--- a/docs/PERFORMANCE.md
+++ b/docs/PERFORMANCE.md
@@ -191,6 +191,31 @@ Fixes, in increasing order of goodness:
 3. Stop inlining: stream ids into a temporary table and join. Removes the wall
    properly and makes request size independent of cohort size.
 
+**Since measured again, and fixed with stored id sets.** Sample ids are longer than patient
+ids, so the wall comes sooner for them: on `msk_chord_2024` (a compare and a clinical view),
+12,000 sample ids ran and 13,000 failed with the same `max_query_size` error. Each view also
+re-inlined the whole list, and the readback carried it back to the browser in every compiled
+query: at 10,000 ids every id appeared four times in an 839 KB response. And the page keeps the
+document in the URL (`?doc=`), which Node refuses past 16 KB of headers (431) — a reload or a
+shared link broke at roughly 350 sample ids, long before ClickHouse did.
+
+The fix is option 3 above, with the ids kept on the server: a list is saved once as a stored
+id set (`lib/id-set-store.ts`) and a cohort names it, `{"kind":"sampleList","set":"<id>"}`. The
+request reads the set from Postgres once (cached in memory; a set never changes) and each
+statement that reads it carries it as a ClickHouse external table. Same documents, measured
+with `runAnalysis` against the live warehouse:
+
+| set | document | response | time | result |
+|---|---|---|---|---|
+| 10,000 msk_chord_2024 samples | 416 B | 23 KB | 2.2 s | ok |
+| all 25,040 msk_chord_2024 samples | 416 B | 23 KB | 4.9 s | ok (inline: fails) |
+| 60,000 samples, msk_chord_2024 + genie_public | 504 B | 45 KB | 7.3 s | ok |
+
+Saving the 60,000-id set (matching every id to the studies' samples, then storing it) took
+0.9 s. An inline list is still accepted up to `INLINE_ID_SQL_LIMIT` (200 KB of ids per study,
+about 10,000 sample ids) and refused by name past it, pointing at a stored set, instead of
+failing with ClickHouse's syntax error.
+
 One further constraint: a `patients` leaf is refused for aggregate-only
 participants (see [DATA-BOUNDARY.md](DATA-BOUNDARY.md)), so a list-defined
 cohort is **inherently non-federatable** — it cannot cross an instance boundary
diff --git a/docs/dsl.md b/docs/dsl.md
index d19df3bf..11bac1e5 100644
--- a/docs/dsl.md
+++ b/docs/dsl.md
@@ -1,6 +1,6 @@
 <!-- GENERATED FILE — do not edit. Source: lib/dsl-reference.ts; regenerate with `npm run docs:gen`. -->
 
-# cbio-lab DSL (v2.6)
+# cbio-lab DSL (v2.7)
 
 One declarative JSON object — the **Analysis document** — describes everything cbio-lab does:
 which patients form each cohort, and which views compare them. The server compiles it to
@@ -11,7 +11,7 @@ SQL each cohort compiled to.
 ## Analysis document
 
 ```
-{ "dsl":     "2.6",                         // the document's version; see "Versions" below
+{ "dsl":     "2.7",                         // the document's version; see "Versions" below
   "study":   "<default study id>",            // validated against cancer_study
   "cohorts": { "<name>": cohortDef, ... },    // max 16 — the store every view's "cohorts" names from
   "views":   [ view, ... ],                   // max 6; each lists its own "cohorts": ["<name>", ...]
@@ -87,13 +87,15 @@ Up to 16 authored cohorts and 48 cohorts in all, children included. Expanded bef
 each child `extends` its parent and runs in the parent's studies. (Not to be confused with the
 `{"kind":"split"}` leaf below, which selects the engine's fixed discovery or validation half.)
 
-**Versions.** A document carries `"dsl": "2.6"`. One written for an older version is
+**Versions.** A document carries `"dsl": "2.7"`. One written for an older version is
 upgraded when it is read — the result's `upgraded` says from which version and what changed
 (2.2 → 2.3 moved top-level `partitions` onto the cohorts they split as `splits`, and renamed
 their children from `"<partition> / <arm>"` to `"<cohort> / <partition> / <arm>"`, views
 included; 2.3 → 2.4 ended "a split replaces what it splits" — a view that drew a split cohort's arms
 under 2.3 is given those arms by name, so it draws the same thing; 2.4 → 2.5 ended "a view with no
-`cohorts` draws every cohort" — such a view is given every authored cohort by name) — and saving it writes the new
+`cohorts` draws every cohort" — such a view is given every authored cohort by name; 2.5 → 2.6 renamed
+the oncoprint's study track "Study of origin"; 2.6 → 2.7 let a list clause name a stored id set, and
+changes nothing an older document says) — and saving it writes the new
 version. One with no `dsl` is read the same way, so
 leaving it out is harmless. One written for a NEWER version than the server reads is refused,
 rather than silently ignoring what it does not understand.
@@ -106,8 +108,8 @@ rather than silently ignoring what it does not understand.
 | `clinical` | `{"kind":"clinical","attribute":A, ...predicate, "per"?:"sample"}` | clinical attribute; predicate is `values:[≤50]` (OR), `range:{gt,gte,lt,lte}` (numeric via toFloat64OrNull), or `op`(`= != > >= < <=`)+`value`; `per:"sample"` = patient matches if ANY sample matches. `op`+`percentile` (0-1) resolves `value` LIVE from a percentile of the attribute's distribution instead of a literal number — e.g. `{"op":">=","percentile":0.8}` = "at or above the 80th percentile" ("top 20%"). `percentileOf`:"<cohort name>" scopes the reference population to another cohort in this document (e.g. "top 20% TMB **within NSCLC**", not the whole study); both the leaf's own cohort and, if given, `percentileOf`'s cohort must resolve to a single study, and `percentileOf` may not itself use `percentile` (no chaining). Resolved once, live, before compilation — the readback shows the resolved number and what it was a percentile of. **Custom data:** an attribute the reader uploaded is named `custom:<dataset>/<COLUMN>` (e.g. `custom:brain-mets/MET_SITE`) and works here and in every view exactly like the study's own — oncoprint `clinical` tracks, `splitBy.attribute`, `clinical` views, plot axes. Uploads are stored on the server, readable once logged in, and pinned by version in the document's `uploads`; a document naming a dataset the request cannot read is refused, never answered as if no patient had a value. Patient-level studies only |
 | `derived` | `{"kind":"derived","metric":"followupMonths"|"historyMonths"|"alteredGenes"|"lines"|"treatmentSpan","range":{gte?,gt?,lte?,lt?},"eventType"?,"lineGap"?:90,"lineClasses"?}` | filters on a value computed from the **shape** of the data rather than a study's vocabulary. Event-type names and attribute keys are study-specific — this database spells one concept `Treatment` in 87 studies and `TREATMENT` in 10, and the key MSK-CHORD calls `SUBTYPE` exists in only 27 of 131 timeline studies — so these read dates and gene symbols instead and mean the same thing everywhere. `followupMonths`: how far the timeline runs past its own day 0. `historyMonths`: how much predates it. `alteredGenes`: distinct genes altered (panel size bounds it, so not comparable across studies with different panels). `lines` and `treatmentSpan` are the deliberate exception — they need `eventType` (which timeline event stands for "a therapy" here; Explore proposes one from the study's own catalog), because there is no vocabulary-free way to ask "how many lines of treatment". `lines`: the number of treatment lines, by the one line definition the `sequence` view and "Treatment line (derived)" share (systemic-therapy records of that event type, a `lineGap`-day gap; `lineClasses` `"all"` or a class list widens it). `treatmentSpan`: months from the first to the last record of that event type |
 | `event` | `{"kind":"event","a":sel,"b"?:sel,"rel":rel,"priorGuard"?:bool,"lineGap"?:90}` | timeline sub-DSL (below) |
-| `sampleList` | `{"kind":"sampleList","ids":["<study>:<id>", ...]}` | explicit, cross-study list of sample ids — up to ~22,000 total (measured ClickHouse query-size ceiling; not enforced as a hard cap yet) |
-| `patientList` | `{"kind":"patientList","ids":["<study>:<id>", ...]}` | explicit, cross-study list of patient ids, same shape and ceiling |
+| `sampleList` | `{"kind":"sampleList","ids":["<study>:<id>", ...]}` or `{"kind":"sampleList","set":"<id set>"}` | explicit, cross-study list of sample ids: inline in `ids` (up to about 200 KB of ids per study, roughly 10,000 — refused by name past that), or a **stored id set** named by `set`, of any size up to 250,000 (see below) |
+| `patientList` | `{"kind":"patientList","ids":["<study>:<id>", ...]}` or `{"kind":"patientList","set":"<id set>"}` | explicit, cross-study list of patient ids, same two forms and limits |
 | `profiled` | `{"kind":"profiled","type":"MUTATION"\|"CNA"\|"SV"}` | patient has a sample on a gene panel for that data type — combine with `not` to separate wild-type from not-profiled |
 | `caseList` | `{"kind":"caseList","id":"sequenced"}` | portal sample list; bare ids get the study prefix |
 | `genomicData` | `{"kind":"genomicData","gene":G,"profileType":P,"range"\|"values"}` | continuous per-gene values (cna, mrna z-scores, …); unknown profiles error listing what the study has |
@@ -126,6 +128,20 @@ kind of clause that can **never** leave for a remote or aggregate-only participa
 cohort is refused before any request is made, the same guarantee `docs/DATA-BOUNDARY.md`
 describes for every other identifier-bearing path.
 
+**Stored id sets.** A long list is saved once on the server — `POST /api/id-sets` with
+`{name, level:"sample"|"patient", studies, ids}`, or "+ Add cohort" → "From a list of ids" — and
+named by its id: `{"kind":"sampleList","set":"<id>"}`. The ids are matched to the studies' own
+samples or patients when the set is saved (the answer says how many matched nothing); a set's
+members never change, so a document naming one always means the same cases, and a different list
+is a new set. The set travels to ClickHouse as an external table beside each statement that reads
+it, never as SQL text, so its size does not touch the 256 KB statement limit an inline list
+meets, and the document, its `?doc=` link and every request carry only the id. `label` and `n`
+beside `set` are its name and size as the page wrote them, shown on the cohort's pill and never
+compiled. A set is its saver's and shared as saved cohorts are; reading one needs a signed-in request
+through the web app, so a document naming a set is refused, saying why, over MCP or without a
+sign-in — those carry their ids inline. Like an inline list, it never reaches a remote or
+aggregate-only participant.
+
 ### OQL subset
 
 `q` is 1–30 entries separated by `;`, each `GENE` (any alteration) or `GENE: spec spec ...`.
diff --git a/e2e.cjs b/e2e.cjs
index 379ec7ae..bc523a4c 100644
--- a/e2e.cjs
+++ b/e2e.cjs
@@ -1449,6 +1449,53 @@ async function main() {
       steps.copied && steps.untouched && steps.updated, JSON.stringify(steps));
     await ctx.close();
   }
+  // A pasted list of ids becomes a stored id set: matched to the study's cases (what matched nothing
+  // is said), saved on the server, and named by the cohort — the document carries the set's id,
+  // never the ids. Reading the set needs its reader to be signed in and allowed.
+  if (LOGIN) {
+    const ctx = await browser.newContext({ viewport: { width: 1400, height: 1000 } });
+    const sp = await ctx.newPage();
+    let steps = {};
+    try {
+      await signIn(ctx);
+      const ex = await (await ctx.request.get(BASE + "/api/custom-data/example?study=msk_chord_2024")).json();
+      const patients = ex.patients || [];
+      const docOf = async () => JSON.parse(await sp.locator("#docjson").inputValue());
+      await sp.goto(BASE + "/lab?tab=analysis&doc=" + Buffer.from(JSON.stringify({ dsl: "2.7", study: "msk_chord_2024", cohorts: {}, views: [] })).toString("base64url"), { waitUntil: "domcontentloaded" });
+      await sp.locator(".addview button:has-text('Survival')").click();
+      await sp.locator(".emptyview .emptyview-body button").first().click();
+      await sp.getByRole("tab", { name: "From a list of ids" }).click();
+      await sp.locator(".addcohortdialog").getByRole("tab", { name: "patients" }).click();
+      await sp.locator(".addcohortdialog textarea").fill([...patients, "NOT-A-PATIENT-1"].join("\n"));
+      await sp.locator(".addcohortdialog input[aria-label='set name']").fill("e2e list");
+      await sp.locator(".addcohortdialog .idsetsave").click();
+      await sp.waitForSelector(".addcohortdialog .idsetresult", { timeout: 60000 });
+      const said = (await sp.locator(".addcohortdialog .idsetresult").innerText()).replace(/\s+/g, " ");
+      steps.matched = patients.length > 0 && said.includes(patients.length + " patient") && /1 matched no patient/.test(said);
+      await sp.locator(".addcohortdialog").getByRole("button", { name: /Add|Use/ }).last().click();
+      await sp.waitForSelector(".cohortbox .cohortbox-head strong", { timeout: 120000 });
+      const def = (await docOf()).cohorts["e2e list"];
+      const leaf = def?.all?.[0] || {};
+      steps.named = leaf.kind === "patientList" && /^[0-9a-f-]{36}$/.test(leaf.set || "") && !leaf.ids && leaf.n === patients.length;
+      steps.counted = (await sp.locator(".cohortbox-head").first().innerText()).replace(/\s+/g, "").includes(String(patients.length));
+      steps.noIds = !(await sp.locator("#docjson").inputValue()).includes(patients[0]);
+      const doc = { dsl: "2.7", study: "msk_chord_2024", cohorts: { L: def }, views: [] };
+      const anon = await browser.newContext();
+      const r1 = await anon.request.post(BASE + "/api/analysis", { data: doc });
+      steps.signedOut = r1.status() >= 400 && /sign in/i.test((await r1.json()).error || "");
+      const other = await browser.newContext();
+      await signIn(other, "other." + LOGIN);
+      const r2 = await other.request.post(BASE + "/api/analysis", { data: doc });
+      steps.otherUser = r2.status() >= 400 && /no stored id set/.test((await r2.json()).error || "");
+      await anon.close(); await other.close();
+      await ctx.request.delete(BASE + "/api/id-sets/" + leaf.set);
+      const r3 = await ctx.request.post(BASE + "/api/analysis", { data: doc });
+      steps.deleted = r3.status() >= 400 && /was deleted on/.test((await r3.json()).error || "");
+    } catch (e) { steps.error = String(e.message || e).slice(0, 160); }
+    ok("a pasted list of ids is matched, saved as a stored id set and named by the cohort; only its signed-in owner can read it",
+      steps.matched && steps.named && steps.counted && steps.noIds && steps.signedOut && steps.otherUser && steps.deleted, JSON.stringify(steps));
+    await ctx.close();
+  }
   // A cohort with something to save — never saved, or re-split since — offers "save" in its gear
   // menu; saving makes the analysis's copy name the saved cohort as its source, and the item goes.
   if (LOGIN) {
diff --git a/lib/artifacts.ts b/lib/artifacts.ts
index 0929b032..7e1d4339 100644
--- a/lib/artifacts.ts
+++ b/lib/artifacts.ts
@@ -17,6 +17,8 @@
 // version, so migrate() is the identity function — but the column and the
 // call site exist now, while adding them costs nothing, rather than being
 // retrofitted under pressure the day the DSL makes a breaking change.
+import { idSetRefsIn } from "./id-sets.ts";
+import { idSetSharingGaps } from "./id-set-store.ts";
 import { dbQuery } from "./db.ts";
 import { AccessError } from "./auth.ts";
 import { groupsOf, readableWhere, canRead, canWrite, canShare, rightsOf, sharingOf, validateSharing, covers,
@@ -43,7 +45,8 @@ export interface SavedArtifact {
 }
 
 /** A custom dataset an analysis uses that some of the people it is shared with cannot read. */
-export interface DatasetWarning { id: string; slug: string; name: string; visibility: Visibility; groupName: string | null; yours: boolean }
+/** A custom dataset (`kind` "dataset", named by `slug`) or a stored id set ("idSet") an item uses that its audience cannot all read. */
+export interface DatasetWarning { id: string; kind: "dataset" | "idSet"; slug: string; name: string; visibility: Visibility; groupName: string | null; yours: boolean }
 
 const KINDS: ArtifactKind[] = ["cohort", "workspace"];
 export function isArtifactKind(k: unknown): k is ArtifactKind {
@@ -166,15 +169,21 @@ export async function shareArtifact(principal: string, id: string, sharing: unkn
   return { artifact, warnings: await datasetWarnings(artifact) };
 }
 
-/** The datasets an analysis pins (`uploads`) that its audience could not all read. */
+/** The datasets an analysis pins (`uploads`) and the stored id sets an item names that its audience could not all read. */
 export async function datasetWarnings(a: SavedArtifact): Promise<DatasetWarning[]> {
+  if (a.sharing.visibility === "private") return [];
   const pins = (a.definition as { uploads?: { dataset?: unknown }[] })?.uploads;
   const ids = [...new Set((Array.isArray(pins) ? pins : []).map((p) => p?.dataset).filter((d): d is string => typeof d === "string" && UUID.test(d)))];
-  if (!ids.length || a.sharing.visibility === "private") return [];
-  const ds = await dbQuery<Shareable & { id: string; slug: string; name: string; group_name: string | null }>(
-    "select d.*, g.name as group_name from custom_dataset d left join user_group g on g.id = d.group_id where d.id = any($1::uuid[])", [ids]);
-  return ds.filter((d) => !covers(sharingOf(d), a.sharing)).map((d) => ({
-    id: d.id, slug: d.slug, name: d.name, visibility: d.visibility, groupName: d.group_name, yours: d.owner_id === a.owner.id,
+  let sets: string[] = [];
+  try { sets = idSetRefsIn(a.definition); } catch { /* a malformed reference names no set to warn about */ }
+  const ds = ids.length ? await dbQuery<Shareable & { id: string; slug: string; name: string; group_name: string | null }>(
+    "select d.*, g.name as group_name from custom_dataset d left join user_group g on g.id = d.group_id where d.id = any($1::uuid[])", [ids]) : [];
+  const gaps = [
+    ...ds.map((d) => ({ ...d, kind: "dataset" as const })),
+    ...(await idSetSharingGaps(sets)).map((d) => ({ ...d, slug: "", kind: "idSet" as const })),
+  ];
+  return gaps.filter((d) => !covers(sharingOf(d), a.sharing)).map((d) => ({
+    id: d.id, kind: d.kind, slug: d.slug, name: d.name, visibility: d.visibility, groupName: d.group_name, yours: d.owner_id === a.owner.id,
   }));
 }
 
diff --git a/lib/ch.ts b/lib/ch.ts
index fe881080..14149843 100644
--- a/lib/ch.ts
+++ b/lib/ch.ts
@@ -14,6 +14,7 @@ import { loopbackConnId, servingAsLoopbackPeer } from "./loopback-peer.ts";
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { ChResult, ChRow } from "./types.ts";
 import { customExternalsFor } from "./custom-data.ts";
+import { idSetExternalsFor } from "./id-sets.ts";
 
 export interface ChConn {
   id: string;
@@ -220,9 +221,11 @@ async function post(sql: string, conn: ChConn, format: string): Promise<string>
     throw new Error("ClickHouse instance '" + conn.id + "' is missing configuration (url/password/db)");
   const ctx = ctxStore.getStore();
   const query = sql + "\nFORMAT " + format;
-  // uploaded custom data rides along only with a statement that names it (lib/custom-data.ts)
+  // uploaded custom data and stored id sets ride along only with a statement that names them
+  // (lib/custom-data.ts, lib/id-sets.ts)
   const externals = [...externalsFor(query),
-    ...customExternalsFor(query, conn.id).map((e) => ({ name: e.name, structure: e.structure, blob: new Blob([e.data]) }))];
+    ...[...customExternalsFor(query, conn.id), ...idSetExternalsFor(query, conn.id)]
+      .map((e) => ({ name: e.name, structure: e.structure, blob: new Blob([e.data]) }))];
   // Tell ClickHouse to stop a query whose client has gone away. Without it an abandoned
   // request keeps its share of the database until it finishes, which is most of what an
   // abandoned request costs.
diff --git a/lib/cohort2.ts b/lib/cohort2.ts
index 7c669aac..1c278363 100644
--- a/lib/cohort2.ts
+++ b/lib/cohort2.ts
@@ -19,6 +19,7 @@ import { oqlLeafSql } from "./oql.ts";
 import { clinicalValueFoldSql, foldedEqualsSql } from "./event-names.ts";
 import { linesCtes, DEFAULT_LINE_GAP } from "./treatment-lines.ts";
 import { clinicalTable } from "./custom-data.ts";
+import { idSetTable, idSetIfLoaded, ID_SET_UUID } from "./id-sets.ts";
 import type {
   CohortDef, Clause, Leaf, CompileCtx, ClinicalLeaf, ClinicalRange,
   ProfiledLeaf, CaseListLeaf, GenomicDataLeaf, GenericAssayLeaf,
@@ -353,8 +354,7 @@ function idsForStudy(raw: string[] | undefined, study: string): string[] {
     const i = s.indexOf(":");
     return i > 0 && i < s.length - 1 ? { study: s.slice(0, i), id: s.slice(i + 1) } : null;
   }).filter((p): p is { study: string; id: string } => !!p && p.study === study && /^[A-Za-z0-9._-]{1,64}$/.test(p.id))
-    .map(p => p.id)
-    .slice(0, 50000);
+    .map(p => p.id);
 }
 
 function requireQualifiedIds(raw: string[] | undefined, kind: string): void {
@@ -362,24 +362,51 @@ function requireQualifiedIds(raw: string[] | undefined, kind: string): void {
   if (!any) throw new Error(kind + ' clause needs ids as "<study>:<id>" — none of the given ids parsed');
 }
 
-function sampleListLeafSql(leaf: SampleListLeaf, ctx: Ctx): string {
-  requireQualifiedIds(leaf.ids, "sampleList");
+/**
+ * The most SQL text an inline list may compile to. ClickHouse refuses a statement over its
+ * 256 KB max_query_size, and the list shares the statement with the rest of the query; past this a
+ * list is refused here, by name, rather than by a syntax error from the database. A stored set
+ * (`set`) has no such limit: its ids travel as an external table.
+ */
+export const INLINE_ID_SQL_LIMIT = 200_000;
+
+/** `<pid expression> IN (…)` for a list leaf: its stored set's table, or its inline ids. Null when it names nobody in `study`. */
+function listMembership(leaf: SampleListLeaf | PatientListLeaf, ctx: Ctx, col: string): string | null {
+  const { kind } = leaf;
+  if (leaf.set !== undefined && leaf.ids !== undefined) throw new Error(kind + " clause takes ids or a stored set, not both");
+  const level = kind === "sampleList" ? "sample" : "patient";
+  if (leaf.set !== undefined) {
+    if (typeof leaf.set !== "string" || !ID_SET_UUID.test(leaf.set)) throw new Error(kind + " clause: set must be a stored id set's id (a uuid)");
+    const table = idSetTable(leaf.set, ctx.study, level);
+    return table && PID(col, ctx.study) + " IN (SELECT id FROM " + table + ")";
+  }
+  requireQualifiedIds(leaf.ids, kind);
   const ids = idsForStudy(leaf.ids, ctx.study);
+  if (!ids.length) return null;
+  const sql = ids.map(sq).join(",");
+  if (sql.length > INLINE_ID_SQL_LIMIT)
+    throw new Error("this " + kind + " has " + ids.length.toLocaleString("en-US") + " " + level + " ids for " + ctx.study +
+      ", too many to write into one query (" + Math.round(sql.length / 1000) + " KB of the " + INLINE_ID_SQL_LIMIT / 1000 +
+      " KB a list may take): save it as a stored id set and name it with \"set\" instead");
+  return PID(col, ctx.study) + " IN (" + sql + ")";
+}
+
+function sampleListLeafSql(leaf: SampleListLeaf, ctx: Ctx): string {
+  const member = listMembership(leaf, ctx, "sample_unique_id");
   // No ids for THIS study is a normal, expected shape for a cross-study list
   // (most of it belongs to other studies in the fan-out) — it contributes
   // zero patients here, not an error.
-  if (!ids.length) return "SELECT " + PID("patient_unique_id", ctx.study) + " AS pid FROM " + dbOf(ctx) + ".sample_derived WHERE 1=0";
+  if (!member) return "SELECT " + PID("patient_unique_id", ctx.study) + " AS pid FROM " + dbOf(ctx) + ".sample_derived WHERE 1=0";
   return "SELECT DISTINCT " + PID("patient_unique_id", ctx.study) + " AS pid\n" +
     "  FROM " + dbOf(ctx) + ".sample_derived\n" +
     "  WHERE cancer_study_identifier = " + sq(ctx.study) + "\n" +
-    "    AND " + PID("sample_unique_id", ctx.study) + " IN (" + ids.map(sq).join(",") + ")";
+    "    AND " + member;
 }
 
 function patientListLeafSql(leaf: PatientListLeaf, ctx: Ctx): string {
-  requireQualifiedIds(leaf.ids, "patientList");
-  const ids = idsForStudy(leaf.ids, ctx.study);
-  if (!ids.length) return "SELECT " + PID("patient_unique_id", ctx.study) + " AS pid FROM " + dbOf(ctx) + ".sample_derived WHERE 1=0";
-  return basePatientsSql(ctx.study, dbOf(ctx)) + "\n    AND " + PID("patient_unique_id", ctx.study) + " IN (" + ids.map(sq).join(",") + ")";
+  const member = listMembership(leaf, ctx, "patient_unique_id");
+  if (!member) return "SELECT " + PID("patient_unique_id", ctx.study) + " AS pid FROM " + dbOf(ctx) + ".sample_derived WHERE 1=0";
+  return basePatientsSql(ctx.study, dbOf(ctx)) + "\n    AND " + member;
 }
 
 // The salt is part of what every held-out result means: changing it reshuffles every
@@ -497,8 +524,13 @@ function leafText(leaf: any): string {
   if (leaf.kind === "genericAssay") return leaf.entity + " " + JSON.stringify(leaf.range || leaf.values);
   if (leaf.kind === "proteinPosition") return leaf.gene + " protein position " + JSON.stringify(leaf.range || {});
   if (leaf.kind === "sampleList" || leaf.kind === "patientList") {
-    const ids: string[] = leaf.ids || [];
     const noun = leaf.kind === "sampleList" ? "sample" : "patient";
+    if (typeof leaf.set === "string") {
+      const s = idSetIfLoaded(leaf.set);
+      if (!s) return "in stored " + noun + " set " + leaf.set;
+      return "in stored " + noun + " set “" + s.name + "” (" + s.count.toLocaleString("en-US") + " " + noun + (s.count === 1 ? "" : "s") + ")";
+    }
+    const ids: string[] = leaf.ids || [];
     const studies = new Set(ids.map((s) => String(s).split(":")[0]).filter(Boolean));
     return "in a list of " + ids.length + " " + noun + (ids.length === 1 ? "" : "s") +
       (studies.size > 1 ? " across " + studies.size + " studies" : "");
diff --git a/lib/custom-data-server.ts b/lib/custom-data-server.ts
index 17bac7e1..5862087e 100644
--- a/lib/custom-data-server.ts
+++ b/lib/custom-data-server.ts
@@ -5,6 +5,7 @@
 import { validateCustomData, withCustomData, tsvField, type CustomCtx, type CustomDataset } from "./custom-data.ts";
 import { requirePrincipal } from "./auth.ts";
 import { loadVersionForRequest } from "./custom-store.ts";
+import { withRequestIdSets } from "./id-sets-server.ts";
 import { chQueryRows, registerChExternal, withChContext, type ChConn } from "./ch.ts";
 import { sq } from "./compiler.ts";
 import { studyRouting, instanceForStudy, patientLevelConn, resolverFor, isPatientLevel } from "./federation.ts";
@@ -40,9 +41,14 @@ export async function customContext(raw: unknown, server?: ServerRefs): Promise<
   return { datasets, allowedConns, allowedDbs };
 }
 
-/** Run `fn` with the request's custom data in effect (a no-op when it carries none). */
+/**
+ * Run `fn` with the request's custom data in effect (a no-op when it carries none), and the stored
+ * id sets `server.uses` names (lib/id-sets-server.ts).
+ */
 export async function withRequestCustomData<T>(raw: unknown, fn: () => Promise<T>, server?: ServerRefs): Promise<T> {
-  return withCustomData(await customContext(raw, server), fn);
+  const ctx = await customContext(raw, server);
+  const run = () => withCustomData(ctx, fn);
+  return server && server.uses !== undefined ? withRequestIdSets(server.uses, server.req, run) : run();
 }
 
 /**
@@ -50,7 +56,12 @@ export async function withRequestCustomData<T>(raw: unknown, fn: () => Promise<T
  * each `{ as, dataset, version }` — the name the document uses, the stored dataset, and the
  * version it is pinned to. Read as the request's principal (lib/auth.ts).
  */
-export interface ServerRefs { refs: unknown; req: Request }
+export interface ServerRefs {
+  refs: unknown;
+  req: Request;
+  /** the document, definition or spec the request serves: the stored id sets it names are read for it */
+  uses?: unknown;
+}
 export const MAX_REFS = 10;
 
 async function loadServerRefs({ refs, req }: ServerRefs): Promise<CustomDataset[]> {
diff --git a/lib/doc-version.ts b/lib/doc-version.ts
index e80cea0a..601cfe92 100644
--- a/lib/doc-version.ts
+++ b/lib/doc-version.ts
@@ -14,7 +14,7 @@
 
 import { flattenSplits, viewDrawProblem } from "./partition-arms.ts";
 
-export const DOC_VERSION = "2.6";
+export const DOC_VERSION = "2.7";
 
 /** what upgrading a document did, reported in the result so a reader is told, not left to notice */
 export interface DocUpgrade {
@@ -193,12 +193,21 @@ function studyTrackRenamed(doc: AnyDoc, changes: string[]): AnyDoc {
   return { ...doc, views };
 }
 
+/**
+ * 2.6 → 2.7: a `sampleList` / `patientList` clause may name a stored id set (`set`) instead of
+ * listing its ids. Nothing an older document says changes meaning, so there is nothing to rewrite;
+ * the version exists so a 2.6 engine refuses a document naming a set rather than reading the
+ * clause as an empty list.
+ */
+const idSetsNamed = (doc: AnyDoc): AnyDoc => doc;
+
 /** each step upgrades from the version before `to`; unversioned documents start at the first */
 const STEPS: { to: string; run: (doc: AnyDoc, changes: string[]) => AnyDoc }[] = [
   { to: "2.3", run: partitionsToSplits },
   { to: "2.4", run: splitsNoLongerReplace },
   { to: "2.5", run: viewsNameTheirCohorts },
-  { to: "2.6", run: studyTrackRenamed }
+  { to: "2.6", run: studyTrackRenamed },
+  { to: "2.7", run: idSetsNamed }
 ];
 
 /**
diff --git a/lib/dsl-reference.ts b/lib/dsl-reference.ts
index bd386cf2..bddcb752 100644
--- a/lib/dsl-reference.ts
+++ b/lib/dsl-reference.ts
@@ -1340,7 +1340,9 @@ upgraded when it is read — the result's \`upgraded\` says from which version a
 their children from \`"<partition> / <arm>"\` to \`"<cohort> / <partition> / <arm>"\`, views
 included; 2.3 → 2.4 ended "a split replaces what it splits" — a view that drew a split cohort's arms
 under 2.3 is given those arms by name, so it draws the same thing; 2.4 → 2.5 ended "a view with no
-\`cohorts\` draws every cohort" — such a view is given every authored cohort by name) — and saving it writes the new
+\`cohorts\` draws every cohort" — such a view is given every authored cohort by name; 2.5 → 2.6 renamed
+the oncoprint's study track "Study of origin"; 2.6 → 2.7 let a list clause name a stored id set, and
+changes nothing an older document says) — and saving it writes the new
 version. One with no \`dsl\` is read the same way, so
 leaving it out is harmless. One written for a NEWER version than the server reads is refused,
 rather than silently ignoring what it does not understand.
@@ -1353,8 +1355,8 @@ rather than silently ignoring what it does not understand.
 | \`clinical\` | \`{"kind":"clinical","attribute":A, ...predicate, "per"?:"sample"}\` | clinical attribute; predicate is \`values:[≤50]\` (OR), \`range:{gt,gte,lt,lte}\` (numeric via toFloat64OrNull), or \`op\`(\`= != > >= < <=\`)+\`value\`; \`per:"sample"\` = patient matches if ANY sample matches. \`op\`+\`percentile\` (0-1) resolves \`value\` LIVE from a percentile of the attribute's distribution instead of a literal number — e.g. \`{"op":">=","percentile":0.8}\` = "at or above the 80th percentile" ("top 20%"). \`percentileOf\`:"\<cohort name\>" scopes the reference population to another cohort in this document (e.g. "top 20% TMB **within NSCLC**", not the whole study); both the leaf's own cohort and, if given, \`percentileOf\`'s cohort must resolve to a single study, and \`percentileOf\` may not itself use \`percentile\` (no chaining). Resolved once, live, before compilation — the readback shows the resolved number and what it was a percentile of. **Custom data:** an attribute the reader uploaded is named \`custom:<dataset>/<COLUMN>\` (e.g. \`custom:brain-mets/MET_SITE\`) and works here and in every view exactly like the study's own — oncoprint \`clinical\` tracks, \`splitBy.attribute\`, \`clinical\` views, plot axes. Uploads are stored on the server, readable once logged in, and pinned by version in the document's \`uploads\`; a document naming a dataset the request cannot read is refused, never answered as if no patient had a value. Patient-level studies only |
 | \`derived\` | \`{"kind":"derived","metric":"followupMonths"|"historyMonths"|"alteredGenes"|"lines"|"treatmentSpan","range":{gte?,gt?,lte?,lt?},"eventType"?,"lineGap"?:90,"lineClasses"?}\` | filters on a value computed from the **shape** of the data rather than a study's vocabulary. Event-type names and attribute keys are study-specific \u2014 this database spells one concept \`Treatment\` in 87 studies and \`TREATMENT\` in 10, and the key MSK-CHORD calls \`SUBTYPE\` exists in only 27 of 131 timeline studies \u2014 so these read dates and gene symbols instead and mean the same thing everywhere. \`followupMonths\`: how far the timeline runs past its own day 0. \`historyMonths\`: how much predates it. \`alteredGenes\`: distinct genes altered (panel size bounds it, so not comparable across studies with different panels). \`lines\` and \`treatmentSpan\` are the deliberate exception \u2014 they need \`eventType\` (which timeline event stands for "a therapy" here; Explore proposes one from the study's own catalog), because there is no vocabulary-free way to ask "how many lines of treatment". \`lines\`: the number of treatment lines, by the one line definition the \`sequence\` view and "Treatment line (derived)" share (systemic-therapy records of that event type, a \`lineGap\`-day gap; \`lineClasses\` \`"all"\` or a class list widens it). \`treatmentSpan\`: months from the first to the last record of that event type |
 | \`event\` | \`{"kind":"event","a":sel,"b"?:sel,"rel":rel,"priorGuard"?:bool,"lineGap"?:90}\` | timeline sub-DSL (below) |
-| \`sampleList\` | \`{"kind":"sampleList","ids":["<study>:<id>", ...]}\` | explicit, cross-study list of sample ids — up to ~22,000 total (measured ClickHouse query-size ceiling; not enforced as a hard cap yet) |
-| \`patientList\` | \`{"kind":"patientList","ids":["<study>:<id>", ...]}\` | explicit, cross-study list of patient ids, same shape and ceiling |
+| \`sampleList\` | \`{"kind":"sampleList","ids":["<study>:<id>", ...]}\` or \`{"kind":"sampleList","set":"<id set>"}\` | explicit, cross-study list of sample ids: inline in \`ids\` (up to about 200 KB of ids per study, roughly 10,000 — refused by name past that), or a **stored id set** named by \`set\`, of any size up to 250,000 (see below) |
+| \`patientList\` | \`{"kind":"patientList","ids":["<study>:<id>", ...]}\` or \`{"kind":"patientList","set":"<id set>"}\` | explicit, cross-study list of patient ids, same two forms and limits |
 | \`profiled\` | \`{"kind":"profiled","type":"MUTATION"\\|"CNA"\\|"SV"}\` | patient has a sample on a gene panel for that data type — combine with \`not\` to separate wild-type from not-profiled |
 | \`caseList\` | \`{"kind":"caseList","id":"sequenced"}\` | portal sample list; bare ids get the study prefix |
 | \`genomicData\` | \`{"kind":"genomicData","gene":G,"profileType":P,"range"\\|"values"}\` | continuous per-gene values (cna, mrna z-scores, …); unknown profiles error listing what the study has |
@@ -1373,6 +1375,20 @@ kind of clause that can **never** leave for a remote or aggregate-only participa
 cohort is refused before any request is made, the same guarantee \`docs/DATA-BOUNDARY.md\`
 describes for every other identifier-bearing path.
 
+**Stored id sets.** A long list is saved once on the server — \`POST /api/id-sets\` with
+\`{name, level:"sample"|"patient", studies, ids}\`, or "+ Add cohort" → "From a list of ids" — and
+named by its id: \`{"kind":"sampleList","set":"<id>"}\`. The ids are matched to the studies' own
+samples or patients when the set is saved (the answer says how many matched nothing); a set's
+members never change, so a document naming one always means the same cases, and a different list
+is a new set. The set travels to ClickHouse as an external table beside each statement that reads
+it, never as SQL text, so its size does not touch the 256 KB statement limit an inline list
+meets, and the document, its \`?doc=\` link and every request carry only the id. \`label\` and \`n\`
+beside \`set\` are its name and size as the page wrote them, shown on the cohort's pill and never
+compiled. A set is its saver's and shared as saved cohorts are; reading one needs a signed-in request
+through the web app, so a document naming a set is refused, saying why, over MCP or without a
+sign-in — those carry their ids inline. Like an inline list, it never reaches a remote or
+aggregate-only participant.
+
 ### OQL subset
 
 \`q\` is 1–30 entries separated by \`;\`, each \`GENE\` (any alteration) or \`GENE: spec spec ...\`.
@@ -1938,7 +1954,9 @@ Leaf kinds:
   (~20% of patients had prior treatment elsewhere, ~20% undetermined).
 - {"kind":"sampleList"|"patientList","ids":["<study>:<id>",...]} — explicit, cross-study list; ids
   are "<study>:<bare-id>" (colon, matching the legacy portal's convention — not the database's
-  internal underscore, since a bare id may contain one).
+  internal underscore, since a bare id may contain one). A list the page saved on the server is
+  {"kind":"sampleList"|"patientList","set":"<id>","label":"…","n":N}: keep such a clause as it is
+  (copy it whole when reusing the cohort) — its ids are not in the document.
 - {"kind":"clinical",...} also supports "values":[...] (OR across values), "range":{"gte":60,"lt":80}
   (numeric), and "per":"sample" (patient matches if ANY sample matches — say so when used).
   "op"+"percentile" (0-1, e.g. {"op":">=","percentile":0.8}) resolves "value" live from a
diff --git a/lib/federation.ts b/lib/federation.ts
index 54ebbe3a..f6bb2af2 100644
--- a/lib/federation.ts
+++ b/lib/federation.ts
@@ -1196,7 +1196,8 @@ export function sequenceKeysSql(cohortSql: string, study: string, db: string, ev
 
 /**
  * Does this definition carry explicit sample or patient identifiers? A
- * `sampleList`/`patientList` leaf embeds ids directly into the compiled SQL,
+ * `sampleList`/`patientList` leaf embeds ids directly into the compiled SQL
+ * (or, naming a stored set, uploads them beside it),
  * so sending one to an instance that is not entitled to patient-level data
  * would push identifiers across exactly the boundary this design exists to
  * respect — and the ids are study-qualified anyway, so they could never
@@ -1214,6 +1215,8 @@ export function carriesPatientIds(def: CohortDef | null | undefined): boolean {
     if (Array.isArray(x)) return x.some(walk);
     const o = x as { kind?: unknown; ids?: unknown };
     if ((o.kind === "sampleList" || o.kind === "patientList") && Array.isArray(o.ids) && o.ids.length > 0) return true;
+    // a stored set is the same list kept on the server: the instance would be asked for its ids
+    if ((o.kind === "sampleList" || o.kind === "patientList") && (o as { set?: unknown }).set !== undefined) return true;
     return Object.values(x).some(walk);
   };
   return walk(def);
diff --git a/lib/groups.ts b/lib/groups.ts
index 2954ec2c..297ec327 100644
--- a/lib/groups.ts
+++ b/lib/groups.ts
@@ -78,8 +78,8 @@ export async function deleteGroup(principal: string, id: string): Promise<void>
   const unshare = (t: string) =>
     "update " + t + " set visibility = case when visibility = 'group' then 'private' else visibility end," +
     " group_id = null, group_can_edit = false where group_id = $1";
-  await dbQuery("with a as (" + unshare("saved_artifacts") + " returning 1), d as (" + unshare("custom_dataset") + " returning 1)" +
-    " delete from user_group where id = $1", [id]);
+  await dbQuery("with a as (" + unshare("saved_artifacts") + " returning 1), d as (" + unshare("custom_dataset") + " returning 1)," +
+    " s as (" + unshare("id_set") + " returning 1) delete from user_group where id = $1", [id]);
 }
 
 /** Add someone by email (signed in yet or not); an existing member keeps their role unless one is given. */
diff --git a/lib/id-set-import.ts b/lib/id-set-import.ts
new file mode 100644
index 00000000..b4aa59e8
--- /dev/null
+++ b/lib/id-set-import.ts
@@ -0,0 +1,51 @@
+// Saving a list of sample or patient ids as a stored id set (lib/id-set-store.ts): matched to the
+// studies' own cases first, so a set never names a case that is not there, and what did not match
+// is reported rather than silently left out.
+import { saveIdSet, ID_SET_MAX, type IdSetMeta } from "./id-set-store.ts";
+import { resolveCaseIds } from "./custom-data-server.ts";
+import type { IdSetLevel } from "./id-sets.ts";
+
+/** What saving a list did: the set, and what of the list did not match. */
+export interface IdSetCreated {
+  set: IdSetMeta;
+  unmatched: number;
+  /** the first few ids that matched nothing, to show */
+  unmatchedExamples: string[];
+  /** ids given more than once */
+  duplicates: number;
+  /** bare ids found in more than one of the studies: each is kept in every one */
+  multiStudy: number;
+  /** studies not matched against, and why */
+  refused: { study: string; reason: string }[];
+}
+
+/**
+ * Save a list of sample or patient ids as a stored set. Each id is "<study>:<id>" or a bare id,
+ * looked up in every study given; only ids that name a case of a patient-level study are kept,
+ * and what did not match is reported, never silently dropped from the count.
+ */
+export async function createIdSet(principal: string, input: unknown): Promise<IdSetCreated> {
+  const b = (input && typeof input === "object" ? input : {}) as { name?: unknown; level?: unknown; studies?: unknown; ids?: unknown };
+  const level = b.level === "sample" ? "sample" : b.level === "patient" ? "patient" : null;
+  if (!level) throw new Error("level must be 'patient' or 'sample'");
+  if (!Array.isArray(b.studies) || !b.studies.length || b.studies.some((s) => typeof s !== "string"))
+    throw new Error("studies must name at least one study");
+  if (!Array.isArray(b.ids) || !b.ids.length) throw new Error("ids must list at least one id");
+  if (b.ids.length > ID_SET_MAX)
+    throw new Error("a stored id set holds at most " + ID_SET_MAX.toLocaleString("en-US") + " ids; this list has " + b.ids.length.toLocaleString("en-US"));
+  const ids = b.ids.map((x) => String(x ?? "").trim()).filter(Boolean);
+  const studies = [...new Set(b.studies as string[])];
+  const r = await resolveCaseIds(studies, level, ids);
+  const perStudy: Record<string, string[]> = {};
+  const unmatchedExamples: string[] = [];
+  r.matches.forEach((hits, i) => {
+    if (!hits.length && unmatchedExamples.length < 20) unmatchedExamples.push(ids[i]);
+    for (const h of hits) (perStudy[h.study] ??= []).push(level === "sample" ? h.sample! : h.patient);
+  });
+  const duplicates = ids.length - new Set(ids).size;
+  const set = await saveIdSet(principal, {
+    name: String(b.name ?? ""), level: level as IdSetLevel, perStudy,
+    source: { idsIn: ids.length, unmatched: r.unmatched, duplicates, multiStudy: r.multiStudy }
+  });
+  return { set, unmatched: r.unmatched, unmatchedExamples, duplicates, multiStudy: r.multiStudy, refused: r.refused };
+}
diff --git a/lib/id-set-store.ts b/lib/id-set-store.ts
new file mode 100644
index 00000000..a40ae508
--- /dev/null
+++ b/lib/id-set-store.ts
@@ -0,0 +1,178 @@
+// Stored id sets (db/migrations/0006_id_sets.sql): a cohort given as a list of sample or patient
+// ids, kept on the server and named by documents by its id. The ONLY module that touches those
+// tables.
+//
+// - Every read and write passes lib/access.ts's canRead / canShare: its owner, and its group or
+//   everyone signed in as its sharing says. A principal is a signed-in user's id (lib/auth.ts).
+// - A set's members never change once written (a trigger enforces it too), so a document naming a
+//   set always means the same samples, and a request may keep a set it has read.
+// - Members are stored as gzipped JSON ({study: [bare id, ...]}), matched against the studies'
+//   own ids before they are stored (lib/id-sets-server.ts), so a set never names a case that is
+//   not there.
+// - Every read of members and every write is logged with its principal.
+import { createHash, randomUUID } from "node:crypto";
+import { gzipSync, gunzipSync } from "node:zlib";
+import { dbQuery } from "./db.ts";
+import { AccessError } from "./auth.ts";
+import { groupsOf, readableWhere, canRead, canShare, rightsOf, sharingOf, validateSharing, type Rights, type Shareable, type Sharing } from "./access.ts";
+import type { IdSetLevel, LoadedIdSet } from "./id-sets.ts";
+
+/** how the list was matched when it was saved */
+export interface IdSetSource { idsIn: number; unmatched: number; duplicates: number; multiStudy: number }
+
+export interface IdSetMeta {
+  id: string; name: string; owner: string; ownerEmail: string; level: IdSetLevel;
+  studies: string[]; count: number; perStudy: Record<string, number>; sha256: string; source: IdSetSource;
+  createdAt: string; updatedAt: string; deletedAt: string | null;
+  sharing: Sharing & { groupName: string | null };
+  /** what the asking user may do with it */
+  rights: Rights;
+}
+
+interface SetRow extends Shareable {
+  id: string; name: string; level: IdSetLevel; studies: string[]; id_count: number; per_study: Record<string, number>;
+  sha256: string; source: IdSetSource; created_at: string; updated_at: string; deleted_at: string | null;
+  owner_email: string; group_name: string | null;
+}
+
+/** The most ids one set holds: what one upload may hold (lib/custom-data-server.ts RESOLVE_LIMIT). */
+export const ID_SET_MAX = 250_000;
+
+const ROW = "select s.id, s.name, s.owner_id, s.level, s.studies, s.id_count, s.per_study, s.sha256, s.source, s.visibility, s.group_id," +
+  " s.group_can_edit, s.created_at, s.updated_at, s.deleted_at, u.email as owner_email, g.name as group_name from id_set s" +
+  " left join app_user u on u.id = s.owner_id left join user_group g on g.id = s.group_id";
+
+/** Postgres hands back timestamps as Date; the API speaks ISO text. */
+const iso = (x: unknown): string => x instanceof Date ? x.toISOString() : String(x);
+
+const metaOf = (r: SetRow, principal: string, groups: Set<string>): IdSetMeta => ({
+  id: r.id, name: r.name, owner: r.owner_id ?? "", ownerEmail: r.owner_email ?? "", level: r.level,
+  studies: r.studies, count: r.id_count, perStudy: r.per_study, sha256: r.sha256, source: r.source,
+  createdAt: iso(r.created_at), updatedAt: iso(r.updated_at), deletedAt: r.deleted_at ? iso(r.deleted_at) : null,
+  sharing: { ...sharingOf(r), groupName: r.group_name }, rights: rightsOf(principal, r, groups)
+});
+
+const log = (principal: string, action: "read" | "create" | "delete", id: string) =>
+  dbQuery("insert into id_set_access_log (principal, action, set_id) values ($1, $2, $3)", [principal, action, id]);
+
+const one = async (id: string): Promise<SetRow | null> =>
+  /^[0-9a-f-]{36}$/.test(id) ? (await dbQuery<SetRow>(ROW + " where s.id = $1", [id]))[0] ?? null : null;
+
+async function readable(principal: string, id: string): Promise<{ r: SetRow; groups: Set<string> }> {
+  const r = await one(id);
+  const groups = await groupsOf(principal);
+  if (!r || !canRead(principal, r, groups)) throw new AccessError("no stored id set " + id + " that you may read", 404);
+  return { r, groups };
+}
+
+/** Every live set this principal may read, newest first, without members. */
+export async function listIdSets(principal: string): Promise<IdSetMeta[]> {
+  const [rows, groups] = await Promise.all([
+    dbQuery<SetRow>(ROW + " where s.deleted_at is null and " + readableWhere("s", 1) + " order by s.created_at desc limit 1000", [principal]),
+    groupsOf(principal)]);
+  return rows.map((r) => metaOf(r, principal, groups));
+}
+
+/** One set's description, without members. A deleted one is described too, saying when it went. */
+export async function getIdSet(principal: string, id: string): Promise<IdSetMeta> {
+  const { r, groups } = await readable(principal, id);
+  return metaOf(r, principal, groups);
+}
+
+/** One set's members, per study. Refuses a deleted set; logged. */
+export async function readIdSet(principal: string, id: string): Promise<{ meta: IdSetMeta; perStudy: Record<string, string[]> }> {
+  const { r, groups } = await readable(principal, id);
+  if (r.deleted_at) throw new AccessError("stored id set “" + r.name + "” was deleted on " + iso(r.deleted_at).slice(0, 10), 410);
+  const [{ ids_gz }] = await dbQuery<{ ids_gz: Buffer }>("select ids_gz from id_set where id = $1", [r.id]);
+  await log(principal, "read", r.id);
+  return { meta: metaOf(r, principal, groups), perStudy: JSON.parse(gunzipSync(Buffer.from(ids_gz)).toString("utf8")) };
+}
+
+/**
+ * Save a set: members already matched to the studies' own ids (lib/id-sets-server.ts), as bare
+ * ids per study. Empty studies are dropped; a set with no members at all is refused.
+ */
+export async function saveIdSet(principal: string, input: { name: string; level: IdSetLevel; perStudy: Record<string, string[]>; source: IdSetSource }): Promise<IdSetMeta> {
+  const name = String(input.name ?? "").trim().slice(0, 200);
+  if (!name) throw new Error("a stored id set needs a name");
+  if (input.level !== "patient" && input.level !== "sample") throw new Error("level must be 'patient' or 'sample'");
+  const perStudy: Record<string, string[]> = {};
+  for (const study of Object.keys(input.perStudy).sort()) {
+    const ids = [...new Set(input.perStudy[study].map(String))].sort();
+    if (ids.length) perStudy[study] = ids;
+  }
+  const studies = Object.keys(perStudy);
+  const count = studies.reduce((n, s) => n + perStudy[s].length, 0);
+  if (!count) throw new Error("none of the ids matched a " + input.level + " of the studies given; nothing to save");
+  if (count > ID_SET_MAX) throw new Error("a stored id set holds at most " + ID_SET_MAX.toLocaleString("en-US") + " ids; this one has " + count.toLocaleString("en-US"));
+  const json = JSON.stringify(perStudy);
+  const id = randomUUID();
+  await dbQuery(
+    "insert into id_set (id, name, owner_id, level, studies, id_count, per_study, ids_gz, sha256, source)" +
+    " values ($1::uuid, $2, $3::uuid, $4, $5::text[], $6::int, $7::jsonb, $8::bytea, $9, $10::jsonb)",
+    [id, name, principal, input.level, studies, count, JSON.stringify(Object.fromEntries(studies.map((s) => [s, perStudy[s].length]))),
+      gzipSync(json, { level: 6 }), createHash("sha256").update(json).digest("hex"), JSON.stringify(input.source)]);
+  await log(principal, "create", id);
+  return metaOf((await one(id))!, principal, await groupsOf(principal));
+}
+
+/** Delete (its owner only): a document naming it is refused from then on, saying so. */
+export async function deleteIdSet(principal: string, id: string): Promise<void> {
+  const { r } = await readable(principal, id);
+  if (!canShare(principal, r)) throw new AccessError("only its owner can delete “" + r.name + "”", 403);
+  await dbQuery("update id_set set deleted_at = now() where id = $1 and deleted_at is null", [r.id]);
+  forget(r.id);
+  await log(principal, "delete", r.id);
+}
+
+/** Change how a set is shared (its owner only). It holds patient-level ids: never shared but by this. */
+export async function shareIdSet(principal: string, id: string, sharing: unknown): Promise<IdSetMeta> {
+  const { r, groups } = await readable(principal, id);
+  if (!canShare(principal, r)) throw new AccessError("only its owner can change who “" + r.name + "” is shared with", 403);
+  if (r.deleted_at) throw new AccessError("stored id set “" + r.name + "” was deleted", 410);
+  const s = validateSharing(sharing, groups);
+  await dbQuery("update id_set set visibility = $2, group_id = $3, group_can_edit = $4 where id = $1", [r.id, s.visibility, s.groupId, s.groupCanEdit]);
+  forget(r.id);
+  return metaOf((await one(r.id))!, principal, groups);
+}
+
+/** The sets an analysis names that some of its audience could not read (lib/artifacts.ts). */
+export async function idSetSharingGaps(ids: string[]): Promise<(Shareable & { id: string; name: string; group_name: string | null })[]> {
+  return ids.length ? dbQuery("select s.id, s.name, s.owner_id, s.visibility, s.group_id, s.group_can_edit, g.name as group_name" +
+    " from id_set s left join user_group g on g.id = s.group_id where s.id = any($1::uuid[])", [ids]) : [];
+}
+
+// ---------------------------------------------------------------------------
+// Per-request loading, for the request boundary (lib/id-sets-server.ts)
+// ---------------------------------------------------------------------------
+
+/** Members never change, so a set can be kept once read; bounded by count. */
+const CACHE_MAX = 16;
+const cache = new Map<string, LoadedIdSet>();
+/** An access decision is re-checked at most this often per principal and set. */
+const ACCESS_TTL_MS = 60_000;
+const accessSeen = new Map<string, number>();
+
+/** Drop what this process remembers of a set, so its next read checks access again: on delete and on a sharing change. */
+function forget(id: string): void {
+  cache.delete(id);
+  for (const k of accessSeen.keys()) if (k.endsWith("\t" + id)) accessSeen.delete(k);
+}
+
+/**
+ * A set's members for one engine request. Access is re-checked, and the read logged, at most once
+ * a minute per principal and set; the members come from memory once read, which is safe only
+ * because they never change. Deleting or re-sharing a set forgets it at once in this process;
+ * another replica sees the change within that minute.
+ */
+export async function loadIdSetForRequest(principal: string, id: string): Promise<LoadedIdSet> {
+  const who = principal + "\t" + id, now = Date.now();
+  const hit = cache.get(id);
+  if (hit && (accessSeen.get(who) ?? 0) > now - ACCESS_TTL_MS) return hit;
+  const r = await readIdSet(principal, id);   // checks access, refuses a deleted set, logs
+  accessSeen.set(who, now);
+  const entry: LoadedIdSet = hit ?? { id: r.meta.id, name: r.meta.name, level: r.meta.level, count: r.meta.count, perStudy: r.perStudy };
+  cache.delete(id); cache.set(id, entry);
+  while (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value!);
+  return entry;
+}
diff --git a/lib/id-sets-server.ts b/lib/id-sets-server.ts
new file mode 100644
index 00000000..36861d63
--- /dev/null
+++ b/lib/id-sets-server.ts
@@ -0,0 +1,37 @@
+// The request boundary for stored id sets: reading the sets a request names, as its signed-in
+// reader, and deciding which connections may receive their ids. Every engine route reaches it
+// through withRequestCustomData (lib/custom-data-server.ts), which is given the body it serves.
+//
+// Kept apart from lib/id-sets.ts because it needs the store and the federation routing, and
+// lib/id-sets.ts is imported by lib/ch.ts, which federation itself imports.
+import { idSetRefsIn, withIdSets } from "./id-sets.ts";
+import { loadIdSetForRequest } from "./id-set-store.ts";
+import { requirePrincipal } from "./auth.ts";
+import { studyRouting, instanceForStudy } from "./federation.ts";
+import { peerForStudy } from "./federation-remote.ts";
+
+/** The most stored sets one request may name. */
+export const MAX_SETS_PER_REQUEST = 16;
+
+/**
+ * Run `fn` with every stored set `body` names read for it (a no-op when it names none). A set
+ * names patient-level ids, so its studies' tables may go only to the patient-level instance that
+ * holds each study; a study held anywhere else gets none, and a cohort that would need it there
+ * is refused by carriesPatientIds before any query is made.
+ */
+export async function withRequestIdSets<T>(body: unknown, req: Request, fn: () => Promise<T>): Promise<T> {
+  const refs = idSetRefsIn(body);
+  if (!refs.length) return fn();
+  if (refs.length > MAX_SETS_PER_REQUEST)
+    throw new Error("a request names at most " + MAX_SETS_PER_REQUEST + " stored id sets; this one names " + refs.length);
+  const principal = requirePrincipal(req, "use stored id sets");
+  const sets = await Promise.all(refs.map((id) => loadIdSetForRequest(principal, id)));
+  const routing = await studyRouting();
+  const studyConn = new Map<string, string>();
+  for (const study of new Set(sets.flatMap((s) => Object.keys(s.perStudy)))) {
+    if (!routing.has(study) || await peerForStudy(study)) continue;
+    const inst = await instanceForStudy(study);
+    if (inst.mode === "patient-level") studyConn.set(study, inst.conn.id);
+  }
+  return withIdSets(sets, studyConn, fn);
+}
diff --git a/lib/id-sets.ts b/lib/id-sets.ts
new file mode 100644
index 00000000..a66ffcf6
--- /dev/null
+++ b/lib/id-sets.ts
@@ -0,0 +1,126 @@
+// Stored id sets in a request: a `sampleList`/`patientList` leaf that names a stored set
+// (`{"kind":"sampleList","set":"<uuid>"}`) instead of carrying its ids.
+//
+// The request boundary (lib/id-sets-server.ts) reads each set the request names, as its signed-in
+// reader, and puts it here for the length of the request. The cohort compiler (lib/cohort2.ts)
+// then names one ClickHouse external table per set and study:
+//
+//   ... AND <id> IN (SELECT id FROM _idset_<set>_<study hash>)
+//
+// and lib/ch.ts uploads that table with any statement that names it and with no other. So a set
+// of any size costs one short line of SQL, never a statement past ClickHouse's max_query_size
+// (an inlined list hits it near 12,000 sample ids), and the document and its ?doc= link carry
+// a uuid instead of the list.
+//
+// Patient-data boundary (docs/DATA-BOUNDARY.md): the ids are patient-level. Each study's table
+// goes only to the connection of the patient-level instance holding that study, decided at the
+// request boundary; lib/ch.ts refuses to upload it anywhere else.
+//
+// Pure apart from the AsyncLocalStorage: no I/O, safe to import from lib/ch.ts and lib/cohort2.ts.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+
+export type IdSetLevel = "patient" | "sample";
+
+/** A set as one request reads it: its members per study, as bare ids. */
+export interface LoadedIdSet {
+  id: string;
+  name: string;
+  level: IdSetLevel;
+  count: number;
+  perStudy: Record<string, string[]>;
+}
+
+interface IdSetCtx {
+  sets: Map<string, LoadedIdSet>;
+  /** study -> the connection id of the patient-level instance holding it */
+  studyConn: Map<string, string>;
+  /** external table name -> what it uploads, and where it may go */
+  tables: Map<string, { set: string; study: string; data?: string }>;
+}
+const store = new AsyncLocalStorage<IdSetCtx>();
+
+export const ID_SET_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export const ID_SET_STRUCTURE = "id String";
+
+/** The external table holding one set's ids for one study. Stable, so its SQL can be read and cached by name. */
+export function idSetTableName(set: string, study: string): string {
+  return "_idset_" + set.replace(/-/g, "") + "_" + createHash("sha256").update(study).digest("hex").slice(0, 10);
+}
+
+/** Run `fn` with these sets readable by the compiler. */
+export function withIdSets<T>(sets: LoadedIdSet[], studyConn: Map<string, string>, fn: () => Promise<T>): Promise<T> {
+  if (!sets.length) return fn();
+  const tables = new Map<string, { set: string; study: string }>();
+  for (const s of sets) for (const study of Object.keys(s.perStudy)) tables.set(idSetTableName(s.id, study), { set: s.id, study });
+  return store.run({ sets: new Map(sets.map((s) => [s.id, s])), studyConn, tables }, fn);
+}
+
+/**
+ * True when this request reads a stored set. Such an answer is not written to the shared result
+ * cache (lib/next-cache.ts): a cached computation runs outside the request, where the set's table
+ * is not there to upload, and reading a set must be checked against its reader every time.
+ */
+export function hasIdSets(): boolean {
+  return !!store.getStore()?.sets.size;
+}
+
+/** The set a request read, or a specific refusal saying why it is not there. */
+export function loadedIdSet(set: string): LoadedIdSet {
+  const s = store.getStore()?.sets.get(set);
+  if (!s) throw new Error("this cohort names stored id set " + set + ", which this request did not read: a stored set is read for a signed-in " +
+    "request through the web app's API (log in, or check you may read it). MCP clients and links without a sign-in carry their ids inline.");
+  return s;
+}
+
+/** The set if this request read it: for a readback, which must not fail where compiling would. */
+export function idSetIfLoaded(set: string): LoadedIdSet | null {
+  return store.getStore()?.sets.get(set) ?? null;
+}
+
+/**
+ * The table a compiled statement reads one set's ids for `study` from, or null when the set holds
+ * no ids for that study (most of a cross-study set belongs to the other studies of the fan-out).
+ */
+export function idSetTable(set: string, study: string, level: IdSetLevel): string | null {
+  const s = loadedIdSet(set);
+  if (s.level !== level)
+    throw new Error("stored id set “" + s.name + "” holds " + s.level + " ids; name it in a " + s.level + "List clause, not a " + level + "List");
+  return s.perStudy[study]?.length ? idSetTableName(set, study) : null;
+}
+
+const tsv = (s: string) => s.replace(/\\/g, "\\\\").replace(/\t/g, "\\t").replace(/\n/g, "\\n").replace(/\r/g, "\\r");
+
+/** The id-set tables a statement names, for lib/ch.ts. Refuses a connection not entitled to them. */
+export function idSetExternalsFor(query: string, connId: string): { name: string; structure: string; data: string }[] {
+  const s = store.getStore();
+  if (!s || !query.includes("_idset_")) return [];
+  const out: { name: string; structure: string; data: string }[] = [];
+  for (const [name, t] of s.tables) {
+    if (!new RegExp("(^|[^A-Za-z0-9_])" + name + "([^A-Za-z0-9_]|$)").test(query)) continue;
+    if (s.studyConn.get(t.study) !== connId)
+      throw new Error("stored id set " + t.set + " holds patient-level ids for " + t.study + ", which cannot be sent to instance '" + connId + "'");
+    t.data ??= s.sets.get(t.set)!.perStudy[t.study].map(tsv).join("\n") + "\n";
+    out.push({ name, structure: ID_SET_STRUCTURE, data: t.data });
+  }
+  return out;
+}
+
+/** Every stored set a document, definition or request body names, in first-seen order. */
+export function idSetRefsIn(x: unknown): string[] {
+  const out = new Set<string>();
+  const seen = new Set<object>();
+  const walk = (v: unknown): void => {
+    if (!v || typeof v !== "object" || seen.has(v)) return;
+    seen.add(v);
+    if (Array.isArray(v)) { v.forEach(walk); return; }
+    const o = v as { kind?: unknown; set?: unknown };
+    if ((o.kind === "sampleList" || o.kind === "patientList") && o.set !== undefined) {
+      if (typeof o.set !== "string" || !ID_SET_UUID.test(o.set)) throw new Error(o.kind + " clause: set must be a stored id set's id (a uuid), got " + JSON.stringify(o.set));
+      out.add(o.set);
+    }
+    Object.values(v).forEach(walk);
+  };
+  walk(x);
+  return [...out];
+}
diff --git a/lib/next-cache.ts b/lib/next-cache.ts
index 84ff249c..10d018d7 100644
--- a/lib/next-cache.ts
+++ b/lib/next-cache.ts
@@ -38,6 +38,7 @@ import { oncokbPin } from "./annotation.ts";
 import { runAnalysis } from "./analysis.ts";
 import { buildContract } from "./oncoprint.ts";
 import { hasCustomData } from "./custom-data.ts";
+import { hasIdSets } from "./id-sets.ts";
 import { riskFitDirect, type RiskFit, type RiskFitArgs } from "./views/riskmodel.ts";
 import type { AnalysisDoc, AnalysisResult, Contract, OncoprintSpec } from "./types.ts";
 
@@ -108,7 +109,7 @@ async function countDirect(conn: ChConn, sql: string): Promise<number> {
 }
 export async function cachedCount(conn: ChConn, sql: string): Promise<number> {
   // a statement over uploaded data belongs to its uploader, never to the shared cache
-  if (hasCustomData()) return countDirect(conn, sql);
+  if (hasCustomData() || hasIdSets()) return countDirect(conn, sql);
   return throughCache(async () => countEntry(conn.id, sql, await dataVersion()), () => countDirect(conn, sql));
 }
 
@@ -135,7 +136,7 @@ async function riskFitEntry(args: RiskFitArgs, _version: string): Promise<string
 export async function cachedRiskFit(a: RiskFitArgs & { patients: number }): Promise<RiskFit> {
   const { patients, ...args } = a;
   // a fit over uploaded data belongs to its uploader, never to the shared cache
-  if (hasCustomData() || patients > RISK_FIT_CACHE_MAX_PATIENTS) return riskFitDirect(args);
+  if (hasCustomData() || hasIdSets() || patients > RISK_FIT_CACHE_MAX_PATIENTS) return riskFitDirect(args);
   return throughCache(async () => riskFitEntry(args, await dataVersion()), () => riskFitDirect(args));
 }
 
@@ -150,7 +151,7 @@ async function analysisEntry(doc: AnalysisDoc, oncoprint: "svg" | "spec", _versi
 export async function cachedAnalysis(doc: AnalysisDoc, opts: { oncoprint?: "svg" | "spec" } = {}): Promise<AnalysisResult> {
   const oncoprint = opts.oncoprint ?? "svg";
   // an answer that depends on uploaded data belongs to its uploader, never to the shared cache
-  if (hasCustomData()) return runAnalysis(doc, { oncoprint });
+  if (hasCustomData() || hasIdSets()) return runAnalysis(doc, { oncoprint });
   return throughCache(async () => analysisEntry(doc, oncoprint, await dataVersion()), () => runAnalysis(doc, { oncoprint, ...ROUTE_OPTS }));
 }
 
@@ -166,6 +167,6 @@ async function contractEntry(spec: OncoprintSpec, provenance: boolean, _version:
 export async function cachedContract(spec: OncoprintSpec, opts: { provenance?: boolean } = {}): Promise<Contract> {
   const provenance = !!opts.provenance;
   const direct = () => buildContract(spec, provenance ? { log: [], provenance } : {});
-  if (hasCustomData()) return direct();
+  if (hasCustomData() || hasIdSets()) return direct();
   return throughCache(async () => contractEntry(spec, provenance, await dataVersion()), direct);
 }
diff --git a/lib/types.ts b/lib/types.ts
index ba95ebd8..8ed2980c 100644
--- a/lib/types.ts
+++ b/lib/types.ts
@@ -57,9 +57,14 @@ export interface ClinicalLeaf {
  * an error, so one list can span as many studies as it likes. Never sent to
  * a remote or aggregate-only participant: see carriesPatientIds in
  * lib/federation.ts.
+ *
+ * `set` instead of `ids` names a stored id set (lib/id-set-store.ts) by its id: the same list,
+ * kept on the server, so the document carries a uuid however many ids the set holds. `label` and
+ * `n` are its name and size as the page wrote them, for the cohort's pill; never compiled — the
+ * readback names the set from the store.
  */
-export interface SampleListLeaf { kind: "sampleList"; ids: string[] }
-export interface PatientListLeaf { kind: "patientList"; ids: string[] }
+export interface SampleListLeaf { kind: "sampleList"; ids?: string[]; set?: string; label?: string; n?: number }
+export interface PatientListLeaf { kind: "patientList"; ids?: string[]; set?: string; label?: string; n?: number }
 /**
  * A fixed, engine-owned half of the study's patients: a salted hash of the study-qualified
  * patient id decides the half, so the partition is reproducible, identical for every caller,
diff --git a/test/custom-store.test.ts b/test/custom-store.test.ts
index 6053e799..2ea4b989 100644
--- a/test/custom-store.test.ts
+++ b/test/custom-store.test.ts
@@ -8,7 +8,7 @@ import assert from "node:assert/strict";
 
 delete process.env.SUPABASE_DB_URL;
 delete process.env.DATABASE_URL;
-const { customStoreContract, artifactContract, userContract, sharingContract } = await import("./support/store-contracts.ts");
+const { customStoreContract, artifactContract, userContract, sharingContract, idSetContract } = await import("./support/store-contracts.ts");
 
 test("with no database configured, the stores run on lib/db.ts's in-process Postgres", async () => {
   const { databaseUrl, dbQuery } = await import("../lib/db.ts");
@@ -20,4 +20,5 @@ customStoreContract("in-process fallback");
 artifactContract("in-process fallback");
 userContract("in-process fallback");
 sharingContract("in-process fallback");
+idSetContract("in-process fallback");
 export {};
diff --git a/test/id-sets.test.ts b/test/id-sets.test.ts
new file mode 100644
index 00000000..2df0f36d
--- /dev/null
+++ b/test/id-sets.test.ts
@@ -0,0 +1,82 @@
+// Stored id sets in the engine (lib/id-sets.ts, lib/cohort2.ts): a list clause naming a set
+// compiles to an external table instead of an inlined list, only for a request that read the set,
+// and its ids go only to the connection entitled to them. The store itself is
+// test/support/store-contracts.ts (idSetContract).
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { compileCohortDef, describeCohortDef, INLINE_ID_SQL_LIMIT } from "../lib/cohort2.ts";
+import { withIdSets, idSetExternalsFor, idSetTableName, idSetRefsIn, hasIdSets, type LoadedIdSet } from "../lib/id-sets.ts";
+import { carriesPatientIds } from "../lib/federation.ts";
+
+const SET = "0b7f9c1e-2f4a-4c3b-9d8e-1a2b3c4d5e6f";
+const set: LoadedIdSet = { id: SET, name: "responders", level: "sample", count: 3, perStudy: { s1: ["S-1", "S-2"], s2: ["T-9"] } };
+const leaf = { kind: "sampleList" as const, set: SET };
+const ctx = { study: "s1", db: "db" };
+const conns = new Map([["s1", "a"], ["s2", "b"]]);
+const inSets = <T>(fn: () => Promise<T>) => withIdSets([set], conns, fn);
+
+describe("a list clause naming a stored set", () => {
+  test("compiles to the set's table for that study, never to its ids", async () => {
+    const sql = await inSets(async () => compileCohortDef({ all: [leaf] }, ctx));
+    assert.match(sql, new RegExp("IN \\(SELECT id FROM " + idSetTableName(SET, "s1") + "\\)"));
+    assert.doesNotMatch(sql, /S-1|S-2|T-9/);
+  });
+  test("names a different table per study, and nobody in a study the set has no ids for", async () => {
+    assert.notEqual(idSetTableName(SET, "s1"), idSetTableName(SET, "s2"));
+    const sql = await inSets(async () => compileCohortDef({ all: [leaf] }, { study: "s3", db: "db" }));
+    assert.match(sql, /WHERE 1=0/);
+  });
+  test("is refused, saying why, in a request that did not read the set (MCP, a script, a signed-out link)", () => {
+    assert.throws(() => compileCohortDef({ all: [leaf] }, ctx), /names stored id set .* which this request did not read/);
+  });
+  test("is refused when the set holds the other kind of id", async () => {
+    await assert.rejects(inSets(async () => compileCohortDef({ all: [{ kind: "patientList", set: SET }] }, ctx)),
+      /holds sample ids; name it in a sampleList clause/);
+  });
+  test("takes ids or a set, not both, and a set must be an id", async () => {
+    await assert.rejects(inSets(async () => compileCohortDef({ all: [{ ...leaf, ids: ["s1:S-1"] }] }, ctx)), /ids or a stored set, not both/);
+    assert.throws(() => idSetRefsIn({ all: [{ kind: "sampleList", set: "responders" }] }), /must be a stored id set's id/);
+  });
+  test("reads back by the set's name and size, and by its id when the set was not read", async () => {
+    assert.equal(await inSets(async () => describeCohortDef({ all: [leaf] })), "in stored sample set “responders” (3 samples)");
+    assert.equal(describeCohortDef({ all: [leaf] }), "in stored sample set " + SET);
+  });
+  test("is found wherever a body nests it, once", () => {
+    assert.deepEqual(idSetRefsIn({ cohorts: { A: { all: [leaf] }, B: { all: [{ not: { any: [leaf] } }] } } }), [SET]);
+    assert.deepEqual(idSetRefsIn({ cohorts: { A: { all: [{ kind: "sampleList", ids: ["s1:S-1"] }] } } }), []);
+  });
+  test("keeps the answer out of the shared cache", async () => {
+    assert.equal(hasIdSets(), false);
+    assert.equal(await inSets(async () => hasIdSets()), true);
+  });
+});
+
+describe("a stored set's ids go only where they may", () => {
+  test("a statement naming a study's table uploads that study's ids, and no other table", async () => {
+    const t1 = idSetTableName(SET, "s1");
+    const ext = await inSets(async () => idSetExternalsFor("SELECT 1 WHERE x IN (SELECT id FROM " + t1 + ")", "a"));
+    assert.deepEqual(ext.map((e) => [e.name, e.data]), [[t1, "S-1\nS-2\n"]]);
+    assert.deepEqual(await inSets(async () => idSetExternalsFor("SELECT 1", "a")), []);
+  });
+  test("is refused on a connection other than the patient-level one holding the study", async () => {
+    const t2 = idSetTableName(SET, "s2");
+    await assert.rejects(inSets(async () => idSetExternalsFor("SELECT id FROM " + t2, "a")), /cannot be sent to instance 'a'/);
+    const noConn = withIdSets([set], new Map([["s1", "a"]]), async () => idSetExternalsFor("SELECT id FROM " + t2, "b"));
+    await assert.rejects(noConn, /cannot be sent to instance 'b'/);
+  });
+  test("carriesPatientIds counts a set as ids, so it never reaches an aggregate-only or remote participant", () => {
+    assert.equal(carriesPatientIds({ all: [leaf] }), true);
+    assert.equal(carriesPatientIds({ all: [{ not: { any: [{ kind: "patientList", set: SET }] } } as any] }), true);
+  });
+});
+
+describe("an inline list too long for one statement", () => {
+  test("is refused by name, pointing at a stored set, rather than by ClickHouse's max_query_size", () => {
+    const n = Math.ceil(INLINE_ID_SQL_LIMIT / 10);   // each id is 17 bytes of SQL quoted
+    const ids = Array.from({ length: n }, (_, i) => "s1:P-" + String(i).padStart(12, "0"));
+    assert.throws(() => compileCohortDef({ all: [{ kind: "sampleList", ids }] }, ctx), /too many to write into one query .* save it as a stored id set/);
+  });
+  test("a list under the limit still compiles inline, as before", () => {
+    assert.match(compileCohortDef({ all: [{ kind: "sampleList", ids: ["s1:S-1"] }] }, ctx), /IN \('S-1'\)/);
+  });
+});
diff --git a/test/postgres.db-test.ts b/test/postgres.db-test.ts
index c033ea01..994d6bcf 100644
--- a/test/postgres.db-test.ts
+++ b/test/postgres.db-test.ts
@@ -9,7 +9,7 @@ import { PGlite as PGliteDb } from "@electric-sql/pglite";
 import { pgcrypto } from "@electric-sql/pglite/contrib/pgcrypto";
 import { startPostgres, reapplyMigrations, migrationFiles, target } from "./support/postgres.ts";
 import { migrate, migrationSql } from "../lib/migrate.ts";
-import { customStoreContract, artifactContract, userContract, sharingContract } from "./support/store-contracts.ts";
+import { customStoreContract, artifactContract, userContract, sharingContract, idSetContract } from "./support/store-contracts.ts";
 import { saveDataset } from "../lib/custom-store.ts";
 import { userForEmail } from "../lib/users.ts";
 
@@ -17,13 +17,13 @@ const db: PGlite = await startPostgres();
 
 describe("migrations", () => {
   test("apply in order to an empty database, and again without harm", async () => {
-    assert.deepEqual(migrationFiles(), ["0001_saved_artifacts.sql", "0002_campaigns.sql", "0003_custom_datasets.sql", "0004_users.sql", "0005_sharing.sql"]);
+    assert.deepEqual(migrationFiles(), ["0001_saved_artifacts.sql", "0002_campaigns.sql", "0003_custom_datasets.sql", "0004_users.sql", "0005_sharing.sql", "0006_id_sets.sql"]);
     const tables = async () => (await db.query<{ t: string }>(
       "select table_name as t from information_schema.tables where table_schema = 'public' order by 1")).rows.map((r) => r.t);
     const before = await tables();
     await reapplyMigrations(db);
     assert.deepEqual(await tables(), before);
-    for (const t of ["app_user", "user_identity", "saved_artifacts", "campaigns", "campaign_hypotheses", "custom_dataset", "custom_dataset_version", "custom_data_access_log", "user_group", "group_member"])
+    for (const t of ["app_user", "user_identity", "saved_artifacts", "campaigns", "campaign_hypotheses", "custom_dataset", "custom_dataset_version", "custom_data_access_log", "user_group", "group_member", "id_set", "id_set_access_log"])
       assert.ok(before.includes(t), t + " exists");
   });
 
@@ -63,6 +63,7 @@ customStoreContract("Postgres");
 artifactContract("Postgres");
 userContract("Postgres");
 sharingContract("Postgres");
+idSetContract("Postgres");
 
 describe("a stored dataset version is immutable in the database", () => {
   test("an update or delete of a version row is refused by its trigger", async () => {
diff --git a/test/support/store-contracts.ts b/test/support/store-contracts.ts
index 1d31ed1a..d3eccee0 100644
--- a/test/support/store-contracts.ts
+++ b/test/support/store-contracts.ts
@@ -7,6 +7,7 @@ import { listArtifacts, getArtifact, createArtifact, updateArtifact, deleteArtif
 import { createGroup, addMember, getGroup, listGroups, removeMember, setRole, deleteGroup } from "../../lib/groups.ts";
 import { userForEmail, signIn, claimLegacy } from "../../lib/users.ts";
 import { dbQuery } from "../../lib/db.ts";
+import { saveIdSet, listIdSets, getIdSet, readIdSet, deleteIdSet, shareIdSet, loadIdSetForRequest } from "../../lib/id-set-store.ts";
 
 const ds = (id: string, value = "Brain") => ({
   id, name: id + " (test)", level: "patient", columns: [{ name: "MET_SITE", datatype: "STRING" }],
@@ -78,6 +79,66 @@ export function customStoreContract(backend: string): void {
   });
 }
 
+/** Stored id sets (lib/id-set-store.ts): read back exactly, never changed, owner-scoped, a deleted one says so. */
+export function idSetContract(backend: string): void {
+  describe("id set store (" + backend + ")", () => {
+    before(users);
+    const input = (name: string) => ({ name, level: "sample" as const, perStudy: { s2: ["T-1"], s1: ["S-2", "S-1", "S-1"] },
+      source: { idsIn: 5, unmatched: 1, duplicates: 1, multiStudy: 0 } });
+
+    test("a saved set lists without ids and reads back its distinct ids per study", async () => {
+      const meta = await saveIdSet(P, input("responders"));
+      assert.equal(meta.count, 3);
+      assert.deepEqual(meta.studies, ["s1", "s2"]);
+      assert.deepEqual(meta.perStudy, { s1: 2, s2: 1 });
+      assert.equal(meta.source.unmatched, 1);
+      const listed = await listIdSets(P);
+      assert.ok(listed.some((x) => x.id === meta.id));
+      assert.ok(!("ids" in listed[0]) && !("perStudy" in listed[0] && Array.isArray((listed[0].perStudy as any).s1)));
+      assert.deepEqual((await readIdSet(P, meta.id)).perStudy, { s1: ["S-1", "S-2"], s2: ["T-1"] });
+      const loaded = await loadIdSetForRequest(P, meta.id);
+      assert.deepEqual([loaded.name, loaded.level, loaded.count], ["responders", "sample", 3]);
+    });
+
+    test("a set with no ids, or no name, is refused rather than stored", async () => {
+      await assert.rejects(saveIdSet(P, { ...input("empty"), perStudy: { s1: [] } }), /none of the ids matched/);
+      await assert.rejects(saveIdSet(P, input("  ")), /needs a name/);
+    });
+
+    test("another principal can read nothing it was not granted, until it is shared", async () => {
+      const meta = await saveIdSet(P, input("private"));
+      assert.ok(!(await listIdSets(OTHER)).some((x) => x.id === meta.id));
+      await assert.rejects(readIdSet(OTHER, meta.id), /no stored id set .* that you may read/);
+      await assert.rejects(loadIdSetForRequest(OTHER, meta.id), /no stored id set .* that you may read/);
+      await assert.rejects(shareIdSet(OTHER, meta.id, { visibility: "public" }), /no stored id set/);
+      await shareIdSet(P, meta.id, { visibility: "public" });
+      assert.deepEqual((await readIdSet(OTHER, meta.id)).perStudy.s2, ["T-1"]);
+      await assert.rejects(deleteIdSet(OTHER, meta.id), /only its owner can delete/);
+      await loadIdSetForRequest(OTHER, meta.id);
+      await shareIdSet(P, meta.id, { visibility: "private" });
+      await assert.rejects(loadIdSetForRequest(OTHER, meta.id), /no stored id set/, "unsharing takes effect at once, not after the access check's minute");
+    });
+
+    test("a deleted set disappears from the list, and reading it says when it went", async () => {
+      const meta = await saveIdSet(P, input("gone"));
+      await loadIdSetForRequest(P, meta.id);   // read once, so it is remembered
+      await deleteIdSet(P, meta.id);
+      await assert.rejects(loadIdSetForRequest(P, meta.id), /was deleted on/, "a set read just before its deletion is not served after it");
+      assert.ok(!(await listIdSets(P)).some((x) => x.id === meta.id));
+      assert.ok((await getIdSet(P, meta.id)).deletedAt);
+      await assert.rejects(readIdSet(P, meta.id), /was deleted on \d{4}-\d{2}-\d{2}/);
+    });
+
+    test("its members cannot be changed or the row deleted, though its sharing can", async () => {
+      const meta = await saveIdSet(P, input("frozen"));
+      await assert.rejects(dbQuery("update id_set set id_count = 99 where id = $1", [meta.id]), /members are immutable/);
+      await assert.rejects(dbQuery("update id_set set ids_gz = ''::bytea where id = $1", [meta.id]), /members are immutable/);
+      await assert.rejects(dbQuery("delete from id_set where id = $1", [meta.id]), /never deleted/);
+      await dbQuery("update id_set set name = 'renamed' where id = $1", [meta.id]);
+    });
+  });
+}
+
 /** Saved cohorts and analyses (lib/artifacts.ts): owner-scoped, read back as written, ISO timestamps. */
 export function artifactContract(backend: string): void {
   describe("saved cohorts and analyses (" + backend + ")", () => {

From a24266a56053c5b247229008336e67482259ad38 Mon Sep 17 00:00:00 2001
From: Aaron Lisman <lisman.aaron@gmail.com>
Date: Sat, 17 Oct 2026 19:07:51 +0000
Subject: [PATCH 2/7] Web app: every id list it makes or saves is a stored id
 set

Where the reader is signed in, the page no longer puts inline id lists into
documents it saves or builds:

- app/lab/id-sets-client.ts: storeCohortLists / storeDocLists replace every
  inline sampleList/patientList (its "<study>:<id>" ids, the only ones an
  inline list ever matched) with a stored set, {kind, set, label, n}. A list
  that matches no case, or names only studies where patient ids may not go,
  stays inline: it selects nobody there either way.
- Lists entering the document: an oncoprint drag-selection and a Cell
  Explorer import become cohorts naming a set (the paste tab already did).
  Signed out, they stay inline as before.
- Saves: the page's persist / persistSpaces / saveShared wrap every save path
  (save to library, save analysis, save over a shared analysis, the
  assistant's save, Explore's save as cohort) so what is saved names sets,
  and the open document is given the same sets, so a re-save stores nothing
  new. saveCohortToLibrary takes the saved definition into the copy, so the
  cohort then has nothing left to save.
- db/migrations/0001's comment no longer says identifiers never live in
  Postgres: definitions are rules, and a list a definition names is a stored
  id set. DSL reference and CLAUDE.md say the same.

Inline lists remain valid DSL for MCP clients, scripts and signed-out
readers. Analyses saved earlier with inline lists convert on their next save.

Verified: new e2e check (save a cohort carrying an inline list -> the saved
definition and the analysis's copy name one new set, nothing left to save,
same count); the oncoprint drag check now asserts the stored set's size
equals the selection and the compiler's count (3,556 = 3,556 = 3,556).
Gate (GATE_PORT=4111 scripts/gate.sh) passes: 255 e2e checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvdfHurd9t63GK2ToazMti
---
 CLAUDE.md                              |  7 ++-
 app/lab/add-cohort-dialog.tsx          | 23 +++++++---
 app/lab/id-sets-client.ts              | 61 ++++++++++++++++++++++++++
 app/lab/page.tsx                       | 21 +++++++--
 app/lab/use-cohort-edits.ts            | 15 ++++---
 db/migrations/0001_saved_artifacts.sql | 11 ++---
 docs/dsl.md                            |  4 +-
 e2e.cjs                                | 51 +++++++++++++++++++--
 lib/dsl-reference.ts                   |  4 +-
 9 files changed, 172 insertions(+), 25 deletions(-)
 create mode 100644 app/lab/id-sets-client.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index e9029c97..d22c7a54 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -210,7 +210,12 @@ ClickHouse SQL; clients never send SQL. Live at https://cbiolab.vercel.app (UI a
   then names one ClickHouse external table per set and study, and `lib/ch.ts` uploads it only to
   the patient-level connection holding that study. A set is not read without a signed-in request
   (MCP, scripts), and an answer that reads one bypasses the result cache (`hasIdSets()`). Inline
-  lists are refused by name past `INLINE_ID_SQL_LIMIT` (`lib/cohort2.ts`).
+  lists are refused by name past `INLINE_ID_SQL_LIMIT` (`lib/cohort2.ts`). In the web app every
+  list becomes a set where the reader is signed in (`app/lab/id-sets-client.ts`): oncoprint
+  selections and Cell Explorer imports as they enter the document, and any list still inline when a
+  cohort or analysis is saved (the page's `persist`/`persistSpaces` wrappers, which give the open
+  document the same sets so a re-save stores nothing new). Inline lists stay valid DSL for MCP,
+  scripts and signed-out readers.
 - **Signing in** (`lib/auth.ts`, the header's Sign in) guards custom data, saved
   cohorts/analyses (`/api/artifacts`) and campaign changes; exploring, analyses, `?doc=` links and
   MCP need none. A deployment has ONE way in: an OpenID Connect provider (`lib/oidc.ts`;
diff --git a/app/lab/add-cohort-dialog.tsx b/app/lab/add-cohort-dialog.tsx
index 14775762..e6283da7 100644
--- a/app/lab/add-cohort-dialog.tsx
+++ b/app/lab/add-cohort-dialog.tsx
@@ -39,13 +39,15 @@ export interface LibraryState {
 
 type Source = "analysis" | "library" | "explore" | "list" | "cells";
 
-export function AddCohortDialog({ target, analysis, library, studies, onAdd, onExplore, onLogin, onClose, cells }: {
+export function AddCohortDialog({ target, analysis, library, studies, storeLists, onAdd, onExplore, onLogin, onClose, cells }: {
   target: AddCohortTarget | null;
   /** the analysis's cohorts in its order (the colour each has in its summary), with their sizes once known */
   analysis: { name: string; def: CohortDef; count: number | null; views: string[] }[];
   library: LibraryState;
   /** the studies the analysis uses: a pasted bare id is looked up in each */
   studies: string[];
+  /** a cohort's inline id lists stored as id sets, where the reader is signed in (id-sets-client.ts) */
+  storeLists: (def: CohortDef, name: string) => Promise<CohortDef>;
   /** add a cohort to the view: an analysis cohort by name, or a library one with its definition */
   onAdd: (name: string, def?: CohortDef) => void;
   onExplore: () => void;
@@ -167,7 +169,7 @@ export function AddCohortDialog({ target, analysis, library, studies, onAdd, onE
         {source === "list" && <ListSource studies={studies} saved={library.saved} full={full} replaces={replaces} addTitle={addTitle}
           nameFor={libraryName} onAdd={onAdd} onLogin={onLogin} />}
         {source === "cells" && cells && <CellsSource cells={cells} full={full} replaces={replaces} addTitle={addTitle}
-          nameFor={libraryName} onAdd={onAdd} />}
+          nameFor={libraryName} storeLists={storeLists} onAdd={onAdd} />}
       </DialogContent>}
     </Dialog>
   );
@@ -178,9 +180,10 @@ export function AddCohortDialog({ target, analysis, library, studies, onAdd, onE
  * matched to the study's patients on the server (lib/cell-explorer-server.ts). The text stays in
  * this component while it is typed.
  */
-function CellsSource({ cells, full, replaces, addTitle, nameFor, onAdd }: {
+function CellsSource({ cells, full, replaces, addTitle, nameFor, storeLists, onAdd }: {
   cells: CellExplorerDataset; full: boolean; replaces: boolean; addTitle: (what: string) => string;
-  nameFor: (name: string, def: CohortDef) => string; onAdd: (name: string, def?: CohortDef) => void;
+  nameFor: (name: string, def: CohortDef) => string; storeLists: (def: CohortDef, name: string) => Promise<CohortDef>;
+  onAdd: (name: string, def?: CohortDef) => void;
 }) {
   const [text, setText] = useState("");
   const [name, setName] = useState("from Cell Explorer");
@@ -197,6 +200,14 @@ function CellsSource({ cells, full, replaces, addTitle, nameFor, onAdd }: {
     finally { setBusy(false); }
   };
   const as = found ? nameFor(name.trim() || "from Cell Explorer", found.def) : name.trim();
+  // the donors' patients are a list: stored as an id set before they enter the analysis
+  const add = async () => {
+    if (!found) return;
+    setBusy(true); setErr(null);
+    try { onAdd(as, await storeLists(found.def, as)); }
+    catch (e) { setErr(String((e as Error)?.message || e)); }
+    finally { setBusy(false); }
+  };
   return (
     <div className="acd-cells flex flex-col gap-2.5">
       <p className="note mt-0">
@@ -222,8 +233,8 @@ function CellsSource({ cells, full, replaces, addTitle, nameFor, onAdd }: {
         <div className="viewtb">
           <div className="tbz">
             <label className="tbfield">name <Input aria-label="cohort name" className="h-ctl w-56 text-md md:text-md" value={name} onChange={(e) => setName(e.target.value)} /></label>
-            <Button variant="outline" size="sm" className={TB} disabled={full} title={addTitle("“" + as + "”")}
-              onClick={() => onAdd(as, found.def)}>{replaces ? "Use" : <><Plus />Add</>}</Button>
+            <Button variant="outline" size="sm" className={TB} disabled={full || busy} title={addTitle("“" + as + "”")}
+              onClick={() => void add()}>{busy && <span className="spinner" />}{replaces ? "Use" : <><Plus />Add</>}</Button>
           </div>
         </div>
         {as !== (name.trim() || "from Cell Explorer") && <p className="meta m-0">added as “{as}”, since this analysis already has a different “{name.trim()}”</p>}
diff --git a/app/lab/id-sets-client.ts b/app/lab/id-sets-client.ts
new file mode 100644
index 00000000..e4f752d8
--- /dev/null
+++ b/app/lab/id-sets-client.ts
@@ -0,0 +1,61 @@
+// Inline id lists in the page's documents become stored id sets (lib/id-set-store.ts) wherever the
+// reader is signed in: a cohort picked on an oncoprint, donors from Cell Explorer, and every list
+// still inline when a cohort or an analysis is saved. The document then names the set
+// (`{"kind":"sampleList","set":"<id>"}`), so it, its ?doc= link and every request stay small
+// however long the list is. Inline lists remain valid DSL for MCP clients, scripts and signed-out
+// readers, who cannot read a set.
+import type { AnalysisDoc, CohortDef } from "../../lib/types.ts";
+import { api } from "./api.ts";
+
+type ListKind = "sampleList" | "patientList";
+interface InlineList { kind: ListKind; ids: string[] }
+
+const isInline = (x: unknown): x is InlineList => {
+  const o = x as { kind?: unknown; ids?: unknown; set?: unknown } | null;
+  return !!o && (o.kind === "sampleList" || o.kind === "patientList") && Array.isArray(o.ids) && o.ids.length > 0 && o.set === undefined;
+};
+
+/** Save one inline list as a set; the clause naming it, or the list unchanged when none of its ids names a case. */
+async function store(leaf: InlineList, name: string): Promise<object> {
+  // only "<study>:<id>" ids select anyone inline (lib/cohort2.ts), so only those are stored
+  const ids = leaf.ids.map(String).filter((s) => { const i = s.indexOf(":"); return i > 0 && i < s.length - 1; });
+  if (!ids.length) return leaf;
+  const studies = [...new Set(ids.map((s) => s.slice(0, s.indexOf(":"))))];
+  const level = leaf.kind === "sampleList" ? "sample" : "patient";
+  const res = await api.idSets.create({ name, level, studies, ids });
+  const j = await res.json().catch(() => ({ error: res.statusText }));
+  if (!res.ok || j.error) {
+    // a list naming no case here selects nobody here either way (none matched, or its studies are
+    // held where patient ids may not go): nothing to store, and nothing lost by keeping it
+    if (/none of the ids matched|cannot be matched against/.test(j.error || "")) return leaf;
+    throw new Error("could not store the list of " + leaf.ids.length.toLocaleString() + " ids in “" + name + "”: " + (j.error || res.statusText));
+  }
+  const { kind: _k, ids: _ids, ...rest } = leaf as InlineList & Record<string, unknown>;
+  return { ...rest, kind: leaf.kind, set: j.set.id, label: j.set.name, n: j.set.count };
+}
+
+/** `x` with every inline list under it stored, each named `name`; the same object when it has none. */
+async function storeUnder<T>(x: T, name: string): Promise<T> {
+  if (!x || typeof x !== "object") return x;
+  if (isInline(x)) return (await store(x, name)) as T;
+  if (Array.isArray(x)) {
+    const out = await Promise.all(x.map((v) => storeUnder(v, name)));
+    return out.every((v, i) => v === x[i]) ? x : (out as T);
+  }
+  const entries = Object.entries(x as Record<string, unknown>);
+  const out = await Promise.all(entries.map(async ([k, v]) => [k, await storeUnder(v, name)] as const));
+  return out.every(([, v], i) => v === entries[i][1]) ? x : (Object.fromEntries(out) as T);
+}
+
+/** A cohort with its inline lists stored as sets named after it; the same object when it has none. */
+export function storeCohortLists(def: CohortDef, name: string): Promise<CohortDef> {
+  return storeUnder(def, name);
+}
+
+/** A document with each cohort's inline lists stored as sets named after the cohort; the same object when it has none. */
+export async function storeDocLists(doc: AnalysisDoc): Promise<AnalysisDoc> {
+  const cohorts = doc.cohorts || {};
+  const names = Object.keys(cohorts);
+  const out = await Promise.all(names.map((n) => storeCohortLists(cohorts[n], n)));
+  return out.every((d, i) => d === cohorts[names[i]]) ? doc : { ...doc, cohorts: Object.fromEntries(names.map((n, i) => [n, out[i]])) };
+}
diff --git a/app/lab/page.tsx b/app/lab/page.tsx
index c7ec4a80..48ddc040 100644
--- a/app/lab/page.tsx
+++ b/app/lab/page.tsx
@@ -4,6 +4,7 @@ import { useSearchParams } from "next/navigation";
 import { ExploreCharts } from "./explore-charts";
 import type { UnpackedContract } from "../../lib/oncoprint-binary.ts";
 import type { AnalysisDoc, CohortDef } from "../../lib/types.ts";
+import { storeCohortLists, storeDocLists } from "./id-sets-client.ts";
 import { useLabTools, LAB_TOOL_NAMES } from "./agent-tools.ts";
 import { AgentToolsMenu } from "../_agent/AgentToolsMenu.tsx";
 import { useCustomDataState } from "./custom-data-panel.tsx";
@@ -225,7 +226,20 @@ export default function AnalysisPage() {
   // Saved cohorts and analyses belong to the signed-in user (lib/auth.ts): see use-saved.ts.
   const loggedIn = customState.unlocked;
   const savedArtifacts = useSavedArtifacts(customState.user?.id ?? null);
-  const { cohorts: saved, workspaces: spaces, saveCohort: persist, saveWorkspace: persistSpaces, removeWorkspace: removeSpace } = savedArtifacts;
+  const { cohorts: saved, workspaces: spaces, removeWorkspace: removeSpace } = savedArtifacts;
+  // What is saved never carries an inline id list: each is stored as an id set first, and the open
+  // document is given the same sets, so saving it again stores nothing new (id-sets-client.ts).
+  const persist: typeof savedArtifacts.saveCohort = async (name, def, lastEval, id) =>
+    savedArtifacts.saveCohort(name, await storeCohortLists(def, name), lastEval, id);
+  const withListsStored = async (d: AnalysisDoc): Promise<AnalysisDoc> => {
+    const c = await storeDocLists(d);
+    // bookkeeping on the way to a save, not an edit the reader would undo
+    if (c !== d && docs.current.doc === d) docs.set(c, { undoable: false });
+    return c;
+  };
+  const persistSpaces = async (name: string, d: AnalysisDoc) => savedArtifacts.saveWorkspace(name, await withListsStored(d));
+  /** a list entering the document is stored as an id set when the reader is signed in; inline otherwise */
+  const storeLists = async (def: CohortDef, name: string): Promise<CohortDef> => loggedIn ? storeCohortLists(def, name) : def;
   /** Saving needs the login: logged out, ask for it rather than fail. Returns true when saving may go ahead. */
   const canSave = (): boolean => {
     if (loggedIn) return true;
@@ -318,10 +332,10 @@ export default function AnalysisPage() {
   const exampleLink = (ex: DslExample) => examplesUrl ? examplesUrl + "/lab?doc=" + docParam(ex.doc) : docLink(ex.doc);
   const workspace = useWorkspace({ canSave, doc, docs, goTab, persistSpaces, removeSpace, setError, setStudy, spaces, study,
     sharedSpaces: savedArtifacts.sharedWorkspaces,
-    saveShared: (id, name, d, version) => savedArtifacts.saveShared("workspace", id, name, d, version) });
+    saveShared: async (id, name, d, version) => savedArtifacts.saveShared("workspace", id, name, await withListsStored(d), version) });
   const { sharedOpen, openShared, confirmSharedSave, analysisSaved, clearAnalysis, confirmViewNoteEdit, confirmWorkspaceSave, deleteWorkspace, noteEdit, openWorkspace, openWorkspaceSave, setNotes, setParam, setViewNoteEditing, setWsOpen, viewNoteEditing, wsError, wsOpen } = workspace;
   const savedReady = loggedIn && !savedArtifacts.cohortsState.pending && !savedArtifacts.cohortsState.error;
-  const cohortEdits = useCohortEdits({ doc, docs, evalOf: (n) => { const c = result?.cohorts[n]; return c ? { count: c.count, text: c.text } : null; }, persist, proposePartition, saved, savedReady, setError, setToast, study });
+  const cohortEdits = useCohortEdits({ doc, docs, evalOf: (n) => { const c = result?.cohorts[n]; return c ? { count: c.count, text: c.text } : null; }, persist, proposePartition, saved, savedReady, setError, setToast, storeLists, study });
   const { analysisStudies, cohortEditing, cohortFromSelection, confirmCohortEdit, featureFromSelection, featureSaved, openCohortEdit, removeCohort, removePartitionNamed, renamePartitionRow, runEdited, setCohortEditing, setPartitionDef, splitCohortBy, splitsFlat, cohortSource, updateFromSaved, cohortSaveState, saveCohortToLibrary, cohortCells, openCohortCells } = cohortEdits;
   const exploreState = useExploreState({ addCohortToView: (...a) => addCohortToView(...a), analysisStudies, canSave, doc, docs, evalDef, featureSaved, goTab, persist, proposePartition, runEdited, setError, setStudy, setToast, study, tab });
   const { setAddChartOpen, addClause, addClauses, addDraftToAnalysis, addMode, analyzeDraft, barDef, clearDraft, closeAddCohort, exMsg, exSel, exStudies, explore, exploreBusy, fetchExplore, geneCharts, openAddCohort, openCustomManager, parseDraft, removeDraftClause, setExStudies, setExploreStudies } = exploreState;
@@ -490,6 +504,7 @@ export default function AnalysisPage() {
         }}
         onAdd={(name, def) => { if (chooser) addCohortToView(chooser, name, def); }}
         studies={analysisStudies()}
+        storeLists={storeLists}
         onExplore={() => { if (!chooser) return; const t = chooser; setChooser(null); openAddCohort(t); }}
         onLogin={requestLogin}
         cells={cellExplorerFor(doc.study || study)}
diff --git a/app/lab/use-cohort-edits.ts b/app/lab/use-cohort-edits.ts
index 64f0356b..c3e4ba14 100644
--- a/app/lab/use-cohort-edits.ts
+++ b/app/lab/use-cohort-edits.ts
@@ -37,13 +37,15 @@ export interface CohortEditsPage {
   /** the login's saved cohorts, and whether they have arrived */
   saved: Record<string, SavedCohort>;
   savedReady: boolean;
+  /** a cohort's inline id lists stored as id sets, where the reader is signed in (id-sets-client.ts) */
+  storeLists: (def: CohortDef, name: string) => Promise<CohortDef>;
   persist: (name: string, def: CohortDef, lastEval: SavedCohort["lastEval"], id?: string) => Promise<SavedCohort>;
   /** a cohort's last evaluation, kept with it when saved */
   evalOf: (name: string) => SavedCohort["lastEval"];
 }
 
 export function useCohortEdits(page: CohortEditsPage) {
-  const { doc, docs, evalOf, persist, proposePartition, saved, savedReady, setError, setToast, study } = page;
+  const { doc, docs, evalOf, persist, proposePartition, saved, savedReady, setError, setToast, storeLists, study } = page;
 
   // ---- editing a cohort's name/note (the gear menu's "edit…") -------------
   const [cohortEditing, setCohortEditing] = useState<string | null>(null); // the name AS IT IS in doc.cohorts right now
@@ -85,8 +87,9 @@ export function useCohortEdits(page: CohortEditsPage) {
     let name = sel.name || "selection";
     for (let i = 2; taken.has(name); i++) name = (sel.name || "selection") + " " + i;
     const qualified = ids.map(id => one + ":" + id);
-    const d: AnalysisDoc = { ...doc, cohorts: { ...doc.cohorts, [name]: { all: [{ kind: "patientList", ids: qualified }] } } };
-    docs.set(d);
+    const def = await storeLists({ all: [{ kind: "patientList", ids: qualified }] }, name);
+    const now = docs.current.doc;
+    docs.set({ ...now, cohorts: { ...now.cohorts, [name]: def } });
   };
 
   const removeCohort = (name: string) => {
@@ -158,8 +161,10 @@ export function useCohortEdits(page: CohortEditsPage) {
       const c = await persist(st.as, def, evalOf(name), st.id);
       const now = docs.current.doc;
       if (now.cohorts?.[name]) {
-        // bookkeeping after a save, not an edit the reader would undo
-        docs.set({ ...now, cohorts: { ...now.cohorts, [name]: { ...now.cohorts[name], from: { saved: c.id, name: st.as, hash: cohortHash(def), savedAt: c.savedAt } } } }, { undoable: false });
+        // bookkeeping after a save, not an edit the reader would undo. What was saved may differ from
+        // what was asked by its id lists, now stored as sets: the copy takes those too.
+        const kept = cohortHash(c.def) === cohortHash(def) ? now.cohorts[name] : { ...c.def };
+        docs.set({ ...now, cohorts: { ...now.cohorts, [name]: { ...kept, from: { saved: c.id, name: st.as, hash: cohortHash(c.def), savedAt: c.savedAt } } } }, { undoable: false });
       }
     } catch (e: any) {
       setError("could not save \u201c" + name + "\u201d: " + (e?.message || e));
diff --git a/db/migrations/0001_saved_artifacts.sql b/db/migrations/0001_saved_artifacts.sql
index 96638fd1..ca2e7cff 100644
--- a/db/migrations/0001_saved_artifacts.sql
+++ b/db/migrations/0001_saved_artifacts.sql
@@ -1,8 +1,9 @@
--- Writable store for saved cohorts and analysis workspaces — the one thing
--- that must NEVER live here is a patient or sample identifier. This table
--- holds only DSL definitions (rules), never frozen membership: see
--- docs/DATA-BOUNDARY.md and RATIONALE.md's "User state" section, which
--- deliberately deferred frozen-evaluation storage for exactly this reason.
+-- Writable store for saved cohorts and analysis workspaces: DSL definitions.
+-- A definition is a rule, not an evaluation: a saved cohort is re-run against
+-- today's data, never stored as its members. An explicit id list a definition
+-- names is kept in its own table as a stored id set (0006, lib/id-set-store.ts),
+-- which the definition names by id; the web app stores every list that way
+-- before saving.
 --
 -- Applied by `npm run db:migrate` (lib/migrate.ts), which runs this directory in name order and
 -- records each file in schema_migrations.
diff --git a/docs/dsl.md b/docs/dsl.md
index 11bac1e5..15748021 100644
--- a/docs/dsl.md
+++ b/docs/dsl.md
@@ -140,7 +140,9 @@ beside `set` are its name and size as the page wrote them, shown on the cohort's
 compiled. A set is its saver's and shared as saved cohorts are; reading one needs a signed-in request
 through the web app, so a document naming a set is refused, saying why, over MCP or without a
 sign-in — those carry their ids inline. Like an inline list, it never reaches a remote or
-aggregate-only participant.
+aggregate-only participant. The web app stores every list it makes as a set when its reader is
+signed in (a cohort picked on an oncoprint, donors from Cell Explorer, a pasted list), and every
+inline list still in a cohort or an analysis when it is saved, so what is saved names sets.
 
 ### OQL subset
 
diff --git a/e2e.cjs b/e2e.cjs
index bc523a4c..55578714 100644
--- a/e2e.cjs
+++ b/e2e.cjs
@@ -586,9 +586,12 @@ async function main() {
           const m = document.body.innerText.match(/dragged\s+([\d,]+)\s+patients/);
           return m ? Number(m[1].replace(/,/g, "")) : null;
         });
-        dragOk = claimed > 0 && leaf.kind === "patientList" && leaf.ids.length === claimed && counted === claimed
-          && leaf.ids.every((id) => id.startsWith("msk_chord_2024:"));
-        dragWhat = said + " -> " + leaf.ids.length + " ids -> compiler counted " + counted;
+        // signed in, the selection is stored as an id set and the cohort names it (app/lab/id-sets-client.ts);
+        // signed out, it stays an inline list
+        const n = leaf.set ? leaf.n : leaf.ids?.length;
+        dragOk = claimed > 0 && leaf.kind === "patientList" && n === claimed && counted === claimed
+          && (leaf.set ? /^[0-9a-f-]{36}$/.test(leaf.set) && !leaf.ids : leaf.ids.every((id) => id.startsWith("msk_chord_2024:")));
+        dragWhat = said + " -> " + (leaf.set ? "stored set of " + n : n + " inline ids") + " -> compiler counted " + counted;
       } catch (e) { dragWhat = String(e.message).split("\n")[0]; }
       ok("a drag across the oncoprint becomes a cohort of exactly those patients", dragOk, dragWhat);
 
@@ -1496,6 +1499,48 @@ async function main() {
       steps.matched && steps.named && steps.counted && steps.noIds && steps.signedOut && steps.otherUser && steps.deleted, JSON.stringify(steps));
     await ctx.close();
   }
+  // Nothing is saved with an inline id list: saving a cohort that carries one stores the list as an
+  // id set first, the analysis's copy takes the same set, and saving again stores nothing new.
+  if (LOGIN) {
+    const ctx = await browser.newContext({ viewport: { width: 1400, height: 1000 } });
+    const sp = await ctx.newPage();
+    let steps = {};
+    try {
+      await signIn(ctx, "lists." + LOGIN);
+      const ex = await (await ctx.request.get(BASE + "/api/custom-data/example?study=msk_chord_2024")).json();
+      const ids = (ex.patients || []).map((p) => "msk_chord_2024:" + p);
+      const name = "e2e inline " + Date.now();
+      const docOf = async () => JSON.parse(await sp.locator("#docjson").inputValue());
+      const sets = async () => ((await (await ctx.request.get(BASE + "/api/id-sets")).json()).sets || []).length;
+      const doc = { dsl: "2.7", study: "msk_chord_2024", cohorts: { [name]: { all: [{ kind: "patientList", ids }] } }, views: [{ kind: "survival", cohorts: [name] }] };
+      await sp.goto(BASE + "/lab?tab=analysis&doc=" + Buffer.from(JSON.stringify(doc)).toString("base64url"), { waitUntil: "domcontentloaded" });
+      await sp.waitForSelector(".cohortbox .cohortbox-head strong", { timeout: 120000 });
+      const before = await sets();
+      const save = async (label) => {
+        const gear = sp.locator(".cohortbox", { hasText: name }).locator(".cohortgear");
+        if ((await gear.getAttribute("data-state")) !== "open") await gear.click();
+        await sp.locator("[data-slot=popover-content]").getByRole("button", { name: label, exact: true }).click();
+      };
+      await save("save to library");
+      await sp.waitForFunction((n) => { try { return !!JSON.parse(document.querySelector("#docjson").value).cohorts[n].from; } catch { return false; } }, name, { timeout: 60000 });
+      const art = ((await (await ctx.request.get(BASE + "/api/artifacts?kind=cohort")).json()).artifacts || []).find((a) => a.name === name);
+      const savedLeaf = art?.definition?.all?.[0] || {};
+      const copyLeaf = (await docOf()).cohorts[name].all[0];
+      steps.saved = /^[0-9a-f-]{36}$/.test(savedLeaf.set || "") && !savedLeaf.ids && savedLeaf.n === ids.length;
+      steps.copy = copyLeaf.set === savedLeaf.set && !copyLeaf.ids;
+      steps.oneSet = (await sets()) === before + 1;
+      // the copy now matches what was saved, so there is nothing left to save
+      const gear = sp.locator(".cohortbox", { hasText: name }).locator(".cohortgear");
+      if ((await gear.getAttribute("data-state")) !== "open") await gear.click();
+      const items = await sp.locator("[data-slot=popover-content]").getByRole("button").allInnerTexts();
+      steps.nothingToSave = !items.some((t) => /^save/.test(t.trim()));
+      steps.stillCounted = (await sp.locator(".cohortbox-head").first().innerText()).replace(/\s+/g, "").includes(String(ids.length));
+      await ctx.request.delete(BASE + "/api/artifacts/" + art.id);
+    } catch (e) { steps.error = String(e.message || e).slice(0, 160); }
+    ok("saving a cohort stores its inline id list as an id set, which the analysis's copy then names; nothing is stored twice",
+      steps.saved && steps.copy && steps.oneSet && steps.nothingToSave && steps.stillCounted, JSON.stringify(steps));
+    await ctx.close();
+  }
   // A cohort with something to save — never saved, or re-split since — offers "save" in its gear
   // menu; saving makes the analysis's copy name the saved cohort as its source, and the item goes.
   if (LOGIN) {
diff --git a/lib/dsl-reference.ts b/lib/dsl-reference.ts
index bddcb752..ce48b9d8 100644
--- a/lib/dsl-reference.ts
+++ b/lib/dsl-reference.ts
@@ -1387,7 +1387,9 @@ beside \`set\` are its name and size as the page wrote them, shown on the cohort
 compiled. A set is its saver's and shared as saved cohorts are; reading one needs a signed-in request
 through the web app, so a document naming a set is refused, saying why, over MCP or without a
 sign-in — those carry their ids inline. Like an inline list, it never reaches a remote or
-aggregate-only participant.
+aggregate-only participant. The web app stores every list it makes as a set when its reader is
+signed in (a cohort picked on an oncoprint, donors from Cell Explorer, a pasted list), and every
+inline list still in a cohort or an analysis when it is saved, so what is saved names sets.
 
 ### OQL subset
 

From 3aa655aaa87f9c6d91aadd628527860c36658f68 Mon Sep 17 00:00:00 2001
From: Aaron Lisman <lisman.aaron@gmail.com>
Date: Sun, 18 Oct 2026 16:57:22 +0000
Subject: [PATCH 3/7] Locked cohorts: freeze a cohort, or the whole analysis,
 to the patients it selects now
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A cohort can be locked so it stops drifting as patients are added to the
data. Its `lock` names stored id sets of its patients and their samples then,
the moment, the data version and the OncoKB release, and the frozen patients
of each of its split arms (`children`, by "<split> / <arm>"). The document's
`locked` marks an analysis whose cohorts were all locked at one moment.

Engine:
- lib/cohort-lock.ts applyLocks runs after splits expand and before
  `extends` resolves (runAnalysis and resolveDocCohorts): a locked cohort or
  arm becomes its set alone; an arm added after the lock still extends its
  frozen cohort, so arms add up to it. compileCohortDef honours `lock` too, so
  Explore, oncoprint specs and links cannot fall back to the live definition.
- The definition is still run beside the set: result.cohorts[name].lock
  reports what it selects now, who it would add or drop, frozen patients no
  longer in the data, and new samples of the frozen patients
  (PatientLevelResolver.lockDrift, one logged query per study). The readback
  says "locked <date>: N patients who were <definition>".
- lib/cohort-lock-server.ts + POST /api/lock ({doc, cohorts?}) evaluate each
  cohort and arm at one moment and save the sets (empty sets allowed: an arm
  may hold nobody). Patient-level studies only; needs a sign-in.
- idSetRefsIn reads a lock's sets for its request; carriesPatientIds counts a
  locked cohort as ids; a request may name up to 128 sets.
- DSL 2.8 (no-op upgrade) so a 2.7 engine refuses a locked document instead
  of silently running the live definitions. Docs regenerated.

Page: a cohort's menu has "lock to these patients" / "unlock"; "Lock all
cohorts" beside the cohorts heading locks every cohort and arm at once
(then "locked <date> · unlock all"); unlocking one cohort clears the
analysis lock. A locked card says when, and either "unchanged since" or how
the data has moved. "Update to the saved version" asks before it drops a
lock; rename and notes leave it alone.

A lock freezes patients, not samples (new samples of frozen patients are
counted and shown), and not the values recorded about them.

Verified on msk_chord_2024: locking KRAS NSCLC (2,194, with a split) and EGFR
(2,158) took 0.45 s and left counts and views unchanged; with the definition
widened under the lock the cohort still answered 2,194 and reported
now 7,115, +4,921 entered, 0 left; an arm added after locking summed to
2,194 (conserved). test/cohort-lock.test.ts (10 checks); new e2e check (lock
all -> same counts, "unchanged since", one moment for all; unlock one ->
analysis lock cleared). Gate (GATE_PORT=4111 scripts/gate.sh) passes: 256
e2e checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvdfHurd9t63GK2ToazMti
---
 app/api/lock/route.ts         | 22 +++++++++
 app/lab/analysis-sections.tsx | 60 ++++++++++++++++++++++-
 app/lab/api.ts                |  6 ++-
 app/lab/page.tsx              |  4 +-
 app/lab/use-cohort-edits.ts   | 41 +++++++++++++++-
 app/lab/view-chrome.tsx       | 16 +++++-
 docs/dsl.md                   | 29 +++++++++--
 e2e.cjs                       | 43 +++++++++++++++++
 lib/analysis.ts               | 38 +++++++++++++--
 lib/api-schemas.ts            |  8 +++
 lib/cohort-lock-server.ts     | 91 +++++++++++++++++++++++++++++++++++
 lib/cohort-lock.ts            | 81 +++++++++++++++++++++++++++++++
 lib/cohort2.ts                | 35 +++++++++++++-
 lib/doc-version.ts            | 13 ++++-
 lib/dsl-reference.ts          | 26 +++++++++-
 lib/federation.ts             | 21 +++++++-
 lib/id-set-store.ts           | 18 ++++---
 lib/id-sets-server.ts         |  7 ++-
 lib/id-sets.ts                |  8 ++-
 lib/types.ts                  | 48 ++++++++++++++++++
 test/cohort-lock.test.ts      | 88 +++++++++++++++++++++++++++++++++
 21 files changed, 671 insertions(+), 32 deletions(-)
 create mode 100644 app/api/lock/route.ts
 create mode 100644 lib/cohort-lock-server.ts
 create mode 100644 lib/cohort-lock.ts
 create mode 100644 test/cohort-lock.test.ts

diff --git a/app/api/lock/route.ts b/app/api/lock/route.ts
new file mode 100644
index 00000000..f1c02867
--- /dev/null
+++ b/app/api/lock/route.ts
@@ -0,0 +1,22 @@
+import { parseBody, LockRequest } from "../../../lib/api-schemas.ts";
+import { requirePrincipal, AccessError } from "../../../lib/auth.ts";
+import { withRequestCustomData } from "../../../lib/custom-data-server.ts";
+import { lockCohorts } from "../../../lib/cohort-lock-server.ts";
+import { dataVersion } from "../../../lib/next-cache.ts";
+
+export const maxDuration = 60;
+
+/**
+ * Lock cohorts of a document (lib/cohort-lock.ts): `{ doc, cohorts? }`, every cohort when none are
+ * named. Answers the moment, the data version, the OncoKB release and each cohort's lock, for the
+ * page to write into the document. The members are saved as the reader's stored id sets.
+ */
+export async function POST(req: Request) {
+  try {
+    const principal = requirePrincipal(req, "lock cohorts");
+    const { customData, customRefs, doc, cohorts } = parseBody(LockRequest, await req.json());
+    return Response.json(await withRequestCustomData(customData, () => lockCohorts(principal, { doc, cohorts }, dataVersion), { refs: customRefs, req, uses: doc }));
+  } catch (e) {
+    return Response.json({ error: String((e as Error)?.message || e) }, { status: e instanceof AccessError ? e.status : 400 });
+  }
+}
diff --git a/app/lab/analysis-sections.tsx b/app/lab/analysis-sections.tsx
index 5e7a3971..419afe80 100644
--- a/app/lab/analysis-sections.tsx
+++ b/app/lab/analysis-sections.tsx
@@ -4,10 +4,13 @@
 // document names custom data that is not here. The page holds the state; each section reads it
 // and the page's actions from one AnalysisCtx.
 import { useState } from "react";
-import { Braces, LoaderCircle, Play, Plus, Redo2, Save, Undo2, X } from "lucide-react";
+import { Braces, LoaderCircle, Lock, Play, Plus, Redo2, Save, Undo2, X } from "lucide-react";
+import { lockDate } from "../../lib/cohort-lock.ts";
+import type { CohortLock, LockDrift } from "../../lib/types.ts";
 import { Button } from "../_ui/button";
 import { CHIP } from "../_ui/toolbar.ts";
 import { cn } from "../../lib/cn";
+import { TB } from "../_ui/toolbar.ts";
 import { Dialog, DialogClose, DialogContent, DialogFooter, DialogHeader, DialogTitle } from "../_ui/dialog";
 import { Textarea } from "../_ui/textarea";
 import CohortPills from "./pills";
@@ -61,6 +64,12 @@ export interface AnalysisCtx {
   /** whether a cohort has anything to save to the library, and the action that saves it */
   cohortSaveState: (name: string) => CohortSaveState | null;
   saveCohortToLibrary: (name: string) => Promise<void>;
+  /** lock the cohorts named, or every one (the analysis); unlock one, or all (lib/cohort-lock.ts) */
+  lockCohorts: (names?: string[]) => Promise<void>;
+  unlockCohort: (name: string) => void;
+  unlockAll: () => void;
+  /** whether the reader may store id sets (signed in); asks them to sign in when not */
+  canSave: () => boolean;
   /** the single-cell dataset a cohort's patients can be opened in (lib/cell-explorer.ts), and opening it */
   cohortCells: (name: string) => import("../../lib/cell-explorer.ts").CellExplorerDataset | null;
   openCohortCells: (name: string) => Promise<void>;
@@ -158,7 +167,13 @@ function EmptyViewCard({ ctx, vi }: { ctx: AnalysisCtx; vi: number }) {
 }
 
 export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
-  const { busy, catalogAttrs, cohortCells, cohortSaveState, cohortSource, doc, openCohortCells, loggedIn, menuOpenRef, openCohortEdit, removeCohort, removePartitionNamed, renamePartitionRow, result, saveCohortToLibrary, setPartitionDef, setUpgradeNote, showClauseData, spaces, splitCohortBy, splitsFlat, studyNames, updateFromSaved, upgradeNote, viewTitle } = ctx;
+  const { busy, canSave, catalogAttrs, cohortCells, cohortSaveState, cohortSource, doc, lockCohorts, openCohortCells, loggedIn, menuOpenRef, openCohortEdit, removeCohort, removePartitionNamed, renamePartitionRow, result, saveCohortToLibrary, setPartitionDef, setUpgradeNote, showClauseData, spaces, splitCohortBy, splitsFlat, studyNames, unlockAll, unlockCohort, updateFromSaved, upgradeNote, viewTitle } = ctx;
+  const [lockingAll, setLockingAll] = useState(false);
+  const lockAll = async () => {
+    if (!canSave()) return;
+    setLockingAll(true);
+    try { await lockCohorts(); } finally { setLockingAll(false); }
+  };
   const [cohortOpen, setCohortOpen] = useState<Set<string>>(() => new Set());
   const names = Object.keys(doc.cohorts || {});
   const flat = splitsFlat();
@@ -181,6 +196,19 @@ export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
         <section className="cohortsum" aria-label="cohorts in this analysis">
           <h2 className="vtitle flex items-center gap-2.5 mb-4">
             Cohorts in this analysis <span className="plain meta">— add one from a view</span>{busy && <span className="spinner" />}
+            <span className="analysislock ml-auto flex items-center gap-2 text-sm font-normal normal-case tracking-normal">
+              {doc.locked
+                ? <>
+                    <span className="inline-flex items-center gap-1 text-muted-foreground" title={"every cohort, and its split arms, frozen at once to the patients it selected then" +
+                      (doc.locked.dataVersion ? "\ndata version then: " + doc.locked.dataVersion : "")}>
+                      <Lock className="size-3.5" />locked {lockDate(doc.locked.at)}</span>
+                    <Button variant="link" size="inline" className="text-sm" disabled={busy} onClick={unlockAll}
+                      title="every cohort follows its definition again">unlock all</Button>
+                  </>
+                : <Button variant="outline" size="sm" className={cn(TB, "lockall")} disabled={busy || lockingAll} onClick={() => void lockAll()}
+                    title="freeze every cohort, and its split arms, at this moment to the patients it selects now, so the analysis stays the same as patients are added to the data">
+                    {lockingAll ? <span className="spinner" /> : <Lock />}Lock all cohorts</Button>}
+            </span>
           </h2>
           <div className="cohortlist">
             {names.map((n, i) => {
@@ -201,6 +229,7 @@ export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
                       save={toSave && { onSave: () => saveCohortToLibrary(n), label: toSave.action === "create" ? "save to library" : "save changes to library",
                         title: toSave.action === "create" ? "save “" + toSave.as + "” to your library, to add it to other analyses"
                           : "write this cohort's definition and splits over “" + toSave.as + "” in your library" }}
+                      lock={{ locked: !!doc.cohorts?.[n]?.lock, onLock: async () => { if (canSave()) await lockCohorts([n]); }, onUnlock: () => unlockCohort(n) }}
                       cells={cohortCells(n)} onCells={() => openCohortCells(n)}
                       menuId={"cohort:" + n} menuStore={menuOpenRef.current} />
                     <div className="cohortbox-head">
@@ -208,6 +237,7 @@ export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
                       {c ? <><strong>{c.count.toLocaleString()}</strong> <span className="meta">patients</span></>
                         : busy ? <span className="skeleton cohortsum-skel" /> : null}
                     </div>
+                    {doc.cohorts?.[n]?.lock && <LockLine lock={doc.cohorts[n].lock!} drift={c?.lock} />}
                     <CohortStudies ids={c?.studies && c.studies.length ? c.studies : [doc.cohorts?.[n]?.study || doc.study || result?.study].filter(Boolean) as string[]}
                       names={studyNames} />
                     {doc.cohorts?.[n] && <CohortPills def={doc.cohorts[n]} onCustomData={showClauseData(n)} />}
@@ -259,6 +289,32 @@ export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
   </>;
 }
 
+/**
+ * A locked cohort's lock, and how far the data has moved since: what its definition would select
+ * now, who that would add or drop, frozen patients no longer in the data, and their new samples.
+ */
+function LockLine({ lock, drift }: { lock: CohortLock; drift?: LockDrift }) {
+  const nf = (x: number) => x.toLocaleString();
+  const parts: string[] = [];
+  if (drift && !drift.error) {
+    if (drift.entered || drift.left)
+      parts.push("its definition now selects " + nf(drift.now) + (drift.entered ? " (+" + nf(drift.entered) + " new" : " (") +
+        (drift.entered && drift.left ? ", " : "") + (drift.left ? "−" + nf(drift.left) + " no longer" : "") + ")");
+    if (drift.present < drift.n) parts.push(nf(drift.n - drift.present) + " of the locked patients are no longer in the data");
+    if (drift.newSamples) parts.push(nf(drift.newSamples) + " new sample" + (drift.newSamples === 1 ? "" : "s") + " of these patients, which views include");
+  }
+  return (
+    <p className="lockline m-0 mb-1.5 flex flex-wrap items-baseline gap-x-2 text-sm text-muted-foreground"
+      title={"frozen " + lock.at + (lock.dataVersion ? "\ndata version then: " + lock.dataVersion : "") + (lock.oncokbPin ? "\nOncoKB " + lock.oncokbPin : "")}>
+      <span className="inline-flex items-center gap-1 text-foreground"><Lock className="size-3.5" />locked {lockDate(lock.at)}</span>
+      {!drift ? null
+        : drift.error ? <span className="text-destructive">{drift.error}</span>
+        : parts.length ? <span className="lockdrift">since then: {parts.join("; ")}</span>
+        : <span className="lockdrift">unchanged since: its definition still selects exactly these patients</span>}
+    </p>
+  );
+}
+
 export function DocDialog({ ctx }: { ctx: AnalysisCtx }) {
   const { applyText, busy, clearAnalysis, doc, docDialog, docText, docs, result } = ctx;
   return <>
diff --git a/app/lab/api.ts b/app/lab/api.ts
index a821188d..81f3e84b 100644
--- a/app/lab/api.ts
+++ b/app/lab/api.ts
@@ -6,7 +6,7 @@
 // They return the Response, as fetch does: a caller still decides how to read it (JSON, the
 // binary contract, a file) and what an error status means for it.
 import type {
-  AnalysisBody, NotebookBody, ExploreBody, OncoprintBody, OncoprintDetailBody, PatientsOfBody, PartitionBody, ViewPageBody, TableBody, CellExplorerBody,
+  AnalysisBody, NotebookBody, ExploreBody, OncoprintBody, OncoprintDetailBody, PatientsOfBody, PartitionBody, ViewPageBody, TableBody, CellExplorerBody, LockBody,
 } from "../../lib/api-schemas.ts";
 import { withCustomData, type UploadBinding } from "./custom-data-client.ts";
 import type { ArtifactKind } from "../../lib/artifacts.ts";
@@ -60,6 +60,10 @@ export const api = {
   partition: async (body: PartitionBody, opts: Opts = {}) =>
     post("/api/partition", await withCustomData(body), opts.signal),
 
+  /** Lock cohorts of the document: those named, or every one. Answers each cohort's lock (lib/cohort-lock-server.ts). */
+  lock: async (body: LockBody, opts: Opts = {}) =>
+    post("/api/lock", await withCustomData(body), opts.signal),
+
   /** One page of a table view, or the values one of its columns takes. */
   viewPage: async (body: ViewPageBody, opts: Opts = {}) =>
     post("/api/view-page", await withCustomData(body), opts.signal),
diff --git a/app/lab/page.tsx b/app/lab/page.tsx
index 48ddc040..2a589b7a 100644
--- a/app/lab/page.tsx
+++ b/app/lab/page.tsx
@@ -336,7 +336,7 @@ export default function AnalysisPage() {
   const { sharedOpen, openShared, confirmSharedSave, analysisSaved, clearAnalysis, confirmViewNoteEdit, confirmWorkspaceSave, deleteWorkspace, noteEdit, openWorkspace, openWorkspaceSave, setNotes, setParam, setViewNoteEditing, setWsOpen, viewNoteEditing, wsError, wsOpen } = workspace;
   const savedReady = loggedIn && !savedArtifacts.cohortsState.pending && !savedArtifacts.cohortsState.error;
   const cohortEdits = useCohortEdits({ doc, docs, evalOf: (n) => { const c = result?.cohorts[n]; return c ? { count: c.count, text: c.text } : null; }, persist, proposePartition, saved, savedReady, setError, setToast, storeLists, study });
-  const { analysisStudies, cohortEditing, cohortFromSelection, confirmCohortEdit, featureFromSelection, featureSaved, openCohortEdit, removeCohort, removePartitionNamed, renamePartitionRow, runEdited, setCohortEditing, setPartitionDef, splitCohortBy, splitsFlat, cohortSource, updateFromSaved, cohortSaveState, saveCohortToLibrary, cohortCells, openCohortCells } = cohortEdits;
+  const { lockCohorts, unlockCohort, unlockAll, analysisStudies, cohortEditing, cohortFromSelection, confirmCohortEdit, featureFromSelection, featureSaved, openCohortEdit, removeCohort, removePartitionNamed, renamePartitionRow, runEdited, setCohortEditing, setPartitionDef, splitCohortBy, splitsFlat, cohortSource, updateFromSaved, cohortSaveState, saveCohortToLibrary, cohortCells, openCohortCells } = cohortEdits;
   const exploreState = useExploreState({ addCohortToView: (...a) => addCohortToView(...a), analysisStudies, canSave, doc, docs, evalDef, featureSaved, goTab, persist, proposePartition, runEdited, setError, setStudy, setToast, study, tab });
   const { setAddChartOpen, addClause, addClauses, addDraftToAnalysis, addMode, analyzeDraft, barDef, clearDraft, closeAddCohort, exMsg, exSel, exStudies, explore, exploreBusy, fetchExplore, geneCharts, openAddCohort, openCustomManager, parseDraft, removeDraftClause, setExStudies, setExploreStudies } = exploreState;
   const openTab = (t: typeof TABS[number]) => { goTab(t); if (t === "explore" && !explore) fetchExplore(); };
@@ -351,7 +351,7 @@ export default function AnalysisPage() {
   /** what every view card reads and the edits it can make (app/lab/view-cards.tsx) */
   const viewCtx = { VIEW_KINDS, docHistory, study, assayOptions, attrsLoading, busy, cat, catLoading, catalogAttrs, cohortChoice, cohortFromSelection, contracts, doc, docView, drawsOwnHead, explore, featureFromSelection, maxCohortsOf, menuOpenRef, moveView, noteEdit, ocView, openCohortChooser, openGenes, patchView, pendingKeys, profileOptions, removeView, setContracts, setViewAttrs, setViewCohorts, trackAttrs, trackAttrsLoading, updateView, updateViewLocal, viewEvents, viewIds };
   /** what the Analysis tab's sections read and the actions they take (app/lab/analysis-sections.tsx) */
-  const analysisCtx: AnalysisCtx = { VIEW_KINDS, addView, docHistory, applyText, busy, catalogAttrs, clearAnalysis, doc, docDialog, docText, docs, explore, fetchExplore, cohortCells, cohortSaveState, cohortSource, openCohortCells, emptyViewHint, genesFor, goTab, loggedIn, menuOpenRef, moveView, openCohortChooser, openCohortEdit, openCustomManager, openWorkspaceSave, removeCohort, removePartitionNamed, removeView, removeViews, renamePartitionRow, result, saveCohortToLibrary, saved, setCdFocus, setGenesFor, setPartitionDef, setUpgradeNote, setViewGenes, showClauseData, spaces, splitCohortBy, splitsFlat, studyNames, tab, updateFromSaved, upgradeNote, viewCtx, viewIds, viewTitle };
+  const analysisCtx: AnalysisCtx = { lockCohorts, unlockCohort, unlockAll, canSave, VIEW_KINDS, addView, docHistory, applyText, busy, catalogAttrs, clearAnalysis, doc, docDialog, docText, docs, explore, fetchExplore, cohortCells, cohortSaveState, cohortSource, openCohortCells, emptyViewHint, genesFor, goTab, loggedIn, menuOpenRef, moveView, openCohortChooser, openCohortEdit, openCustomManager, openWorkspaceSave, removeCohort, removePartitionNamed, removeView, removeViews, renamePartitionRow, result, saveCohortToLibrary, saved, setCdFocus, setGenesFor, setPartitionDef, setUpgradeNote, setViewGenes, showClauseData, spaces, splitCohortBy, splitsFlat, studyNames, tab, updateFromSaved, upgradeNote, viewCtx, viewIds, viewTitle };
   // what the page offers the researcher's AI assistant (app/lab/agent-tools.ts), current every render
   const webmcp = useLabTools({
     doc, result, busy, error, tab, study, savedAs: analysisSaved ? doc.title || null : null,
diff --git a/app/lab/use-cohort-edits.ts b/app/lab/use-cohort-edits.ts
index c3e4ba14..56f452b1 100644
--- a/app/lab/use-cohort-edits.ts
+++ b/app/lab/use-cohort-edits.ts
@@ -5,7 +5,8 @@
 // open analysis reads, for add-cohort mode. A rename carries every view's reference along.
 import { useState } from "react";
 import type { ColumnSelection } from "../_oncoprint/OncoprintFigure.tsx";
-import type { AnalysisDoc, CohortDef, CohortSource, PartitionDef } from "../../lib/types.ts";
+import type { AnalysisDoc, CohortDef, CohortLock, CohortSource, PartitionDef } from "../../lib/types.ts";
+import { lockDate } from "../../lib/cohort-lock.ts";
 import { canonicalSplits, cohortHash } from "../../lib/cohort-hash.ts";
 import type { SavedCohort } from "./use-saved.ts";
 import type { SplitSpec } from "./partitions.tsx";
@@ -125,6 +126,8 @@ export function useCohortEdits(page: CohortEditsPage) {
     const s = cohortSource(name);
     if (!s || !s.src || !(s.state === "changed" || (s.state === "current" && s.edited))) return;
     const cur = doc.cohorts![name];
+    if (cur.lock && !s.src.def.lock && !confirm("“" + name + "” is locked to the " + cur.lock.n.toLocaleString() + " patients it had on " + lockDate(cur.lock.at) +
+      ". Taking the saved version's definition unlocks it, and it follows the data from then on. Go ahead?")) return;
     const next: CohortDef = { ...s.src.def, ...(cur.notes ? { notes: cur.notes } : {}), ...(cur.splits ? { splits: cur.splits } : {}),
       from: { saved: s.from.saved, name: s.srcName!, hash: s.now!, savedAt: s.src.savedAt } };
     docs.set({ ...doc, cohorts: { ...doc.cohorts, [name]: next } });
@@ -171,6 +174,40 @@ export function useCohortEdits(page: CohortEditsPage) {
     }
   };
 
+  // ---- locks: a cohort frozen to the patients it selects now (lib/cohort-lock.ts) ------------
+  /**
+   * Lock the cohorts named, or every cohort (the analysis as a whole, one moment for all of them).
+   * The server evaluates each definition and its split arms and keeps the patients as stored id
+   * sets; the document names them in each cohort's `lock`.
+   */
+  const lockCohorts = async (names?: string[]) => {
+    const res = await api.lock({ doc, ...(names ? { cohorts: names } : {}) });
+    const j = await res.json().catch(() => ({ error: res.statusText }));
+    if (!res.ok || j.error) { setError("could not lock: " + (j.error || res.statusText)); return; }
+    const now = docs.current.doc;
+    const cohorts = { ...now.cohorts };
+    for (const [n, lock] of Object.entries(j.locks as Record<string, CohortLock>)) if (cohorts[n]) cohorts[n] = { ...cohorts[n], lock };
+    docs.set({ ...now, cohorts, ...(names ? {} : { locked: { at: j.at, dataVersion: j.dataVersion, oncokbPin: j.oncokbPin } }) });
+  };
+  /** Unlock one cohort: it follows its definition again. The analysis is then no longer locked as a whole. */
+  const unlockCohort = (name: string) => {
+    const now = docs.current.doc;
+    const cur = now.cohorts?.[name];
+    if (!cur?.lock) return;
+    const { lock: _lock, ...rest } = cur;
+    const { locked: _locked, ...unlockedDoc } = now;
+    docs.set({ ...unlockedDoc, cohorts: { ...now.cohorts, [name]: rest } });
+  };
+  /** Unlock every cohort, and the analysis. */
+  const unlockAll = () => {
+    const now = docs.current.doc;
+    const { locked: _locked, ...unlockedDoc } = now;
+    docs.set({ ...unlockedDoc, cohorts: Object.fromEntries(Object.entries(now.cohorts || {}).map(([n, d]) => {
+      const { lock: _lock, ...rest } = d;
+      return [n, rest];
+    })) });
+  };
+
   // ---- partitions: a cohort split into arms that add up to it ------------------------------
   const runEdited = (d: AnalysisDoc) => { docs.set(d); };
   // the page edits splits in their flat form (keyed "<cohort> / <split>") and writes them back
@@ -261,5 +298,5 @@ export function useCohortEdits(page: CohortEditsPage) {
     }
   };
 
-  return { cohortEditing, setCohortEditing, featureSaved, featureFromSelection, cohortFromSelection, removeCohort, runEdited, splitsFlat, setPartitionDef, removePartitionNamed, renamePartitionRow, splitCohortBy, analysisStudies, openCohortEdit, confirmCohortEdit, cohortSource, updateFromSaved, cohortSaveState, saveCohortToLibrary, cohortCells, openCohortCells };
+  return { lockCohorts, unlockCohort, unlockAll, cohortEditing, setCohortEditing, featureSaved, featureFromSelection, cohortFromSelection, removeCohort, runEdited, splitsFlat, setPartitionDef, removePartitionNamed, renamePartitionRow, splitCohortBy, analysisStudies, openCohortEdit, confirmCohortEdit, cohortSource, updateFromSaved, cohortSaveState, saveCohortToLibrary, cohortCells, openCohortCells };
 }
diff --git a/app/lab/view-chrome.tsx b/app/lab/view-chrome.tsx
index a8fceaa5..78333ce9 100644
--- a/app/lab/view-chrome.tsx
+++ b/app/lab/view-chrome.tsx
@@ -9,7 +9,7 @@ import { VIEW_HELP } from "../../lib/view-help.ts";
 import { SERIES, seriesStyle } from "../../lib/chart/style.ts";
 import { HIGHLIGHT_CAP, HIGHLIGHT_COLORS } from "../../lib/plot-highlight.ts";
 import { Waiting } from "../_oncoprint/OncoprintCard.tsx";
-import { ArrowDown, ArrowUp, Ellipsis, ExternalLink, Pencil, Plus, Save, Split, StickyNote, Trash2, X } from "lucide-react";
+import { ArrowDown, ArrowUp, Ellipsis, ExternalLink, Lock, LockOpen, Pencil, Plus, Save, Split, StickyNote, Trash2, X } from "lucide-react";
 import { Button } from "../_ui/button";
 import { Input } from "../_ui/input";
 import { cn } from "../../lib/cn";
@@ -607,8 +607,10 @@ export function ViewMenu({ menuId, menuStore, onMoveUp, onMoveDown, onRemove, on
  * "Cohorts" heading for why that is deliberately a separate, unscoped piece
  * of work.
  */
-export function CohortEditMenu({ busy, canEdit, onEdit, onRemove, split, splitCount = 0, save, cells, onCells, menuId, menuStore }: {
+export function CohortEditMenu({ busy, canEdit, onEdit, onRemove, split, splitCount = 0, save, lock, cells, onCells, menuId, menuStore }: {
   busy?: boolean; canEdit: boolean; onEdit: () => void; onRemove: () => void;
+  /** freezing the cohort to the patients it selects now (lib/cohort-lock.ts), or following its definition again */
+  lock?: { locked: boolean; onLock: () => Promise<void>; onUnlock: () => void };
   /** the single-cell dataset this cohort's patients can be opened in, when its study has one */
   cells?: { label: string } | null;
   onCells?: () => Promise<void>;
@@ -622,6 +624,7 @@ export function CohortEditMenu({ busy, canEdit, onEdit, onRemove, split, splitCo
 }) {
   const [splitting, setSplitting] = useState(false);
   const [saving, setSaving] = useState(false);
+  const [locking, setLocking] = useState(false);
   return (
     <GearMenu menuId={menuId} menuStore={menuStore} className="cohortgear" label={<Ellipsis />} title="edit this cohort" ariaLabel="edit this cohort"
       wide={splitting} onOpenChange={(o) => { if (!o) setSplitting(false); }}>
@@ -637,6 +640,15 @@ export function CohortEditMenu({ busy, canEdit, onEdit, onRemove, split, splitCo
             onClick={() => setSplitting(true)}><Split />{splitCount ? "split another way…" : "split into arms…"}</MenuItem>
           <MenuSeparator />
         </>)}
+        {lock && !splitting && <>
+          {lock.locked
+            ? <MenuItem disabled={busy} title="follow the definition again: patients who match it from now on join, and those who stop matching leave"
+                onClick={() => { close(); lock.onUnlock(); }}><LockOpen />unlock</MenuItem>
+            : <MenuItem disabled={busy || locking} title="freeze this cohort, and its split arms, to the patients it selects now, so it stays the same as patients are added to the data"
+                onClick={async () => { setLocking(true); try { await lock.onLock(); close(); } finally { setLocking(false); } }}>
+                <Lock />lock to these patients{locking && <span className="spinner ml-1.5" />}</MenuItem>}
+          <MenuSeparator />
+        </>}
         {cells && onCells && !splitting && <>
           <MenuItem disabled={busy} title={"open this cohort's patients' cells in Cell Explorer: " + cells.label}
             onClick={() => { close(); void onCells(); }}><ExternalLink />open cells in Cell Explorer</MenuItem>
diff --git a/docs/dsl.md b/docs/dsl.md
index 15748021..14523ff9 100644
--- a/docs/dsl.md
+++ b/docs/dsl.md
@@ -1,6 +1,6 @@
 <!-- GENERATED FILE — do not edit. Source: lib/dsl-reference.ts; regenerate with `npm run docs:gen`. -->
 
-# cbio-lab DSL (v2.7)
+# cbio-lab DSL (v2.8)
 
 One declarative JSON object — the **Analysis document** — describes everything cbio-lab does:
 which patients form each cohort, and which views compare them. The server compiles it to
@@ -11,7 +11,7 @@ SQL each cohort compiled to.
 ## Analysis document
 
 ```
-{ "dsl":     "2.7",                         // the document's version; see "Versions" below
+{ "dsl":     "2.8",                         // the document's version; see "Versions" below
   "study":   "<default study id>",            // validated against cancer_study
   "cohorts": { "<name>": cohortDef, ... },    // max 16 — the store every view's "cohorts" names from
   "views":   [ view, ... ],                   // max 6; each lists its own "cohorts": ["<name>", ...]
@@ -36,7 +36,10 @@ cohortDef := { "all": [clause × 0-8],         // ANDed; [] means every patient
                "lineGap"?: 90,                // derived-treatment-line gap, days
                "notes"?:   "<prose>",         // the analyst's own note on this cohort; never compiled
                "from"?:    { "saved": "<id>", "name": "<name>", "hash": "<sha256>", "savedAt"?: "<when>" },  // set by the page: the saved cohort this was copied from, and the hash of what was copied; never compiled
-               "splits"?:  { "<name>": splitDef } }  // divisions of this cohort into arms that add up to it
+               "splits"?:  { "<name>": splitDef },  // divisions of this cohort into arms that add up to it
+               "lock"?:    { "set": "<id set>", "n": N, "samples"?: "<id set>", "nSamples"?: N, "at": "<ISO time>",
+                             "dataVersion"?: "…", "oncokbPin"?: "…", "children"?: { "<split> / <arm>": { "set", "n" } } } }
+                                              // frozen to the patients it selected at "at" — see "Locked cohorts" below
 splitDef  := { "arms": [ { "name": "<label>", "where": clause, "splits"?: {…} } × 1-8 ],  // tested in order; first match wins; an arm may be split again
                "other"?: "<label>",            // the remainder's name, default "Other"
                "otherSplits"?: {…},            // splits of the remainder
@@ -87,7 +90,7 @@ Up to 16 authored cohorts and 48 cohorts in all, children included. Expanded bef
 each child `extends` its parent and runs in the parent's studies. (Not to be confused with the
 `{"kind":"split"}` leaf below, which selects the engine's fixed discovery or validation half.)
 
-**Versions.** A document carries `"dsl": "2.7"`. One written for an older version is
+**Versions.** A document carries `"dsl": "2.8"`. One written for an older version is
 upgraded when it is read — the result's `upgraded` says from which version and what changed
 (2.2 → 2.3 moved top-level `partitions` onto the cohorts they split as `splits`, and renamed
 their children from `"<partition> / <arm>"` to `"<cohort> / <partition> / <arm>"`, views
@@ -95,7 +98,7 @@ included; 2.3 → 2.4 ended "a split replaces what it splits" — a view that dr
 under 2.3 is given those arms by name, so it draws the same thing; 2.4 → 2.5 ended "a view with no
 `cohorts` draws every cohort" — such a view is given every authored cohort by name; 2.5 → 2.6 renamed
 the oncoprint's study track "Study of origin"; 2.6 → 2.7 let a list clause name a stored id set, and
-changes nothing an older document says) — and saving it writes the new
+2.7 → 2.8 let a cohort be locked; neither changes anything an older document says) — and saving it writes the new
 version. One with no `dsl` is read the same way, so
 leaving it out is harmless. One written for a NEWER version than the server reads is refused,
 rather than silently ignoring what it does not understand.
@@ -128,6 +131,22 @@ kind of clause that can **never** leave for a remote or aggregate-only participa
 cohort is refused before any request is made, the same guarantee `docs/DATA-BOUNDARY.md`
 describes for every other identifier-bearing path.
 
+**Locked cohorts.** A cohort can be frozen to the patients its definition selects at one moment,
+so an analysis stops drifting as patients are added to the data: `lock` names the stored id set
+of those patients (and of their samples), when it was taken, the data version and OncoKB release
+then, and, under `children`, the frozen patients of each of its split arms by name. The engine
+evaluates the set, not the definition; the definition stays as the record of how the cohort was
+made, and is still run beside the set, so the result's `cohorts[name].lock` says how far the
+data has moved: what the definition selects `now`, who it would add (`entered`) or drop
+(`left`), how many frozen patients the data still holds (`present` of `n`), and how many
+samples those patients have that they did not have then (`newSamples` — a lock freezes
+patients, and views read every sample of them). A split arm added after the lock is evaluated
+inside the frozen cohort, so arms still add up to it. The document's `locked` says every cohort
+was locked at once, one moment for all. Locks are taken by `POST /api/lock` (`{doc, cohorts?}`,
+every cohort when none are named) or the page — a cohort's menu, or "Lock all cohorts" — and need a
+sign-in, since the sets are the reader's. Unlocking is removing `lock`. Values recorded about
+the frozen patients (a re-called mutation, an edited clinical field) are read as they are now.
+
 **Stored id sets.** A long list is saved once on the server — `POST /api/id-sets` with
 `{name, level:"sample"|"patient", studies, ids}`, or "+ Add cohort" → "From a list of ids" — and
 named by its id: `{"kind":"sampleList","set":"<id>"}`. The ids are matched to the studies' own
diff --git a/e2e.cjs b/e2e.cjs
index 55578714..82b7bb87 100644
--- a/e2e.cjs
+++ b/e2e.cjs
@@ -1541,6 +1541,49 @@ async function main() {
       steps.saved && steps.copy && steps.oneSet && steps.nothingToSave && steps.stillCounted, JSON.stringify(steps));
     await ctx.close();
   }
+  // Locking: "Lock all cohorts" freezes every cohort and its split arms at one moment; the counts
+  // do not change, each cohort says it is locked and that nothing has moved since, the document
+  // names the frozen sets and when; a cohort unlocks on its own, and the analysis is then no
+  // longer locked as a whole.
+  if (LOGIN) {
+    const ctx = await browser.newContext({ viewport: { width: 1400, height: 1000 } });
+    const sp = await ctx.newPage();
+    let steps = {};
+    try {
+      await signIn(ctx, "locks." + LOGIN);
+      const docOf = async () => JSON.parse(await sp.locator("#docjson").inputValue());
+      const counts = async () => sp.$$eval(".cohortbox-head", (hs) => hs.map((h) => h.innerText.replace(/\s+/g, " ")));
+      const doc = { dsl: "2.8", study: "msk_chord_2024", cohorts: {
+        "KRAS NSCLC": { all: [{ kind: "oql", q: "KRAS: MUT" }, { kind: "clinical", attribute: "CANCER_TYPE", values: ["Non-Small Cell Lung Cancer"], per: "sample" }],
+          splits: { g12c: { arms: [{ name: "G12C", where: { kind: "oql", q: "KRAS: G12C" } }] } } },
+        "EGFR": { all: [{ kind: "oql", q: "EGFR: MUT" }] } },
+        views: [{ kind: "survival", cohorts: ["KRAS NSCLC", "EGFR"] }] };
+      await sp.goto(BASE + "/lab?tab=analysis&doc=" + Buffer.from(JSON.stringify(doc)).toString("base64url"), { waitUntil: "domcontentloaded" });
+      await sp.waitForFunction(() => document.querySelectorAll(".cohortbox-head strong").length === 2, null, { timeout: 180000 });
+      const before = await counts();
+      await sp.locator(".lockall").click();
+      await sp.waitForSelector(".lockdrift", { timeout: 180000 });
+      await sp.waitForFunction(() => document.querySelectorAll(".lockdrift").length === 2, null, { timeout: 180000 });
+      const d = await docOf();
+      const k = d.cohorts["KRAS NSCLC"].lock || {};
+      steps.locked = !!d.locked?.at && /^[0-9a-f-]{36}$/.test(k.set || "") && /^[0-9a-f-]{36}$/.test(k.samples || "") && k.at === d.locked.at && d.cohorts.EGFR.lock?.at === d.locked.at;
+      steps.arms = Object.keys(k.children || {}).some((c) => c.startsWith("g12c / "));
+      steps.sameCounts = JSON.stringify(await counts()) === JSON.stringify(before);
+      const lines = await sp.$$eval(".lockline", (ls) => ls.map((l) => l.innerText.replace(/\s+/g, " ")));
+      steps.unchanged = lines.length === 2 && lines.every((l) => /locked \d+ \w+ \d{4}/.test(l) && /unchanged since/.test(l));
+      steps.header = /locked \d+ \w+ \d{4}/.test(await sp.locator(".analysislock").innerText());
+      const gear = sp.locator(".cohortbox", { hasText: "EGFR" }).locator(".cohortgear");
+      await gear.click();
+      await sp.locator("[data-slot=popover-content]").getByRole("button", { name: "unlock", exact: true }).click();
+      await sp.waitForFunction(() => document.querySelectorAll(".lockline").length === 1, null, { timeout: 60000 });
+      const d2 = await docOf();
+      steps.unlockedOne = !d2.cohorts.EGFR.lock && !!d2.cohorts["KRAS NSCLC"].lock && !d2.locked;
+      steps.lockAllBack = await sp.locator(".lockall").isVisible();
+    } catch (e) { steps.error = String(e.message || e).slice(0, 160); }
+    ok("locking all cohorts freezes them and their arms at one moment, keeps the counts, says nothing moved since; one cohort unlocks on its own",
+      steps.locked && steps.arms && steps.sameCounts && steps.unchanged && steps.header && steps.unlockedOne && steps.lockAllBack, JSON.stringify(steps));
+    await ctx.close();
+  }
   // A cohort with something to save — never saved, or re-split since — offers "save" in its gear
   // menu; saving makes the analysis's copy name the saved cohort as its source, and the item goes.
   if (LOGIN) {
diff --git a/lib/analysis.ts b/lib/analysis.ts
index dc84cf83..50cd47d4 100644
--- a/lib/analysis.ts
+++ b/lib/analysis.ts
@@ -6,10 +6,11 @@
 // oncoprint — the one view whose output is patients — carries the cohort SQL and
 // re-derives its columns inside the owning database.
 // Deliberately deferred: cross-study patient dedup and attribute harmonization.
+import { applyLocks, lockDate } from "./cohort-lock.ts";
 import { chQuery, STUDY, PRIMARY, type ChConn } from "./ch.ts";
 import { sq } from "./compiler.ts";
 import { describeCohortDef } from "./cohort2.ts";
-import type { AnalysisDoc, AnalysisResult, CohortDef, PartitionDef, ViewResult, ViewParticipation, TemplateDoc, SplitBy } from "./types.ts";
+import type { AnalysisDoc, AnalysisResult, CohortDef, PartitionDef, ViewResult, ViewParticipation, TemplateDoc, SplitBy, LockDrift } from "./types.ts";
 import { resolveSplitBy, type AttributeDistribution } from "./cohort-splitby.ts";
 import { resolverFor, PatientLevelResolver, AggregateResolver, studyRouting, restrictedStudies, studyAccess, type Resolver } from "./federation.ts";
 import { cantDraw } from "./view-coverage.ts";
@@ -167,7 +168,7 @@ export interface PartitionProposalRequest {
 export async function resolveDocCohorts(input: unknown): Promise<{ paramsDoc: AnalysisDoc; doc: AnalysisDoc; docStudy: string }> {
   const { doc: paramsDoc } = resolveParams(upgradeDocument(input as AnalysisDoc).doc);
   const { doc: partitionedDoc } = expandSplitTree(paramsDoc as AnalysisDoc);
-  const extendsDoc = resolveExtends(partitionedDoc);
+  const extendsDoc = resolveExtends(applyLocks(partitionedDoc).doc);
   const docStudy = await resolveStudy(extendsDoc.study);
   const doc = await resolveCohortPercentiles(extendsDoc, docStudy, async (study, refDef, attribute, per, p) =>
     (await resolverFor(study, {})).attributeQuantile(refDef, attribute, per, p));
@@ -243,7 +244,10 @@ export async function runAnalysis(template: AnalysisDoc | TemplateDoc, opts: Run
   const { doc: paramsDoc, params: usedParams, unused: unusedParams } = resolveParams(currentDoc);
   const authoredNames = Object.keys(paramsDoc.cohorts || {});
   const { doc: partitionedDoc, plans: partitionPlans } = expandSplitTree(paramsDoc);
-  const extendsDoc = resolveExtends(partitionedDoc);
+  // a locked cohort (and each locked arm) is its frozen set from here on; its definition is kept
+  // aside, run beside it to say how far the data has moved (lib/cohort-lock.ts)
+  const { doc: lockedDoc, live: liveDoc, locked } = applyLocks(partitionedDoc);
+  const extendsDoc = resolveExtends(lockedDoc);
   assertPartitionChildrenFit(extendsDoc.cohorts, partitionPlans);
   assertCustomDataPresent(extendsDoc);
   const docStudy = await resolveStudy(extendsDoc.study);
@@ -255,6 +259,10 @@ export async function runAnalysis(template: AnalysisDoc | TemplateDoc, opts: Run
     const res = await resolverFor(study, {});
     return res.attributeQuantile(refDef, attribute, per, p);
   });
+  const live = Object.keys(locked).length
+    ? await resolveCohortPercentiles(resolveExtends(liveDoc), docStudy, async (study, refDef, attribute, per, p) =>
+      (await resolverFor(study, {})).attributeQuantile(refDef, attribute, per, p))
+    : null;
   const pin = process.env.ONCOKB_PIN || await oncokbPin();
   const names = Object.keys(doc.cohorts || {});
   if (!names.length) throw new Error("document has no cohorts");
@@ -307,6 +315,29 @@ export async function runAnalysis(template: AnalysisDoc | TemplateDoc, opts: Run
     };
   };
   for (const name of names) cohorts[name] = await evalCohortDef(doc.cohorts[name]);
+  // A locked cohort answers from its frozen patients; its definition is run beside them, so the
+  // reader is told how far the data has moved since, never left to notice.
+  const drift: Record<string, LockDrift> = {};
+  for (const [name, l] of Object.entries(locked)) {
+    if (!cohorts[name] || !live) continue;
+    const liveDef = live.cohorts[name];
+    const d: LockDrift = { cohort: l.cohort, at: l.lock.at, ...(l.lock.dataVersion ? { dataVersion: l.lock.dataVersion } : {}),
+      n: l.members.n, present: 0, now: 0, entered: 0, left: 0, newSamples: l.members.samples ? 0 : null };
+    try {
+      for (const s of cohorts[name].studies) {
+        const res = resolvers[s];
+        if (!(res instanceof PatientLevelResolver)) throw new Error(s + " is not held at patient level here");
+        const r = await res.lockDrift(doc.cohorts[name], liveDef, l.members.samples ?? null);
+        d.present += r.present; d.now += r.now; d.entered += r.entered; d.left += r.left;
+        if (d.newSamples != null) d.newSamples = r.newSamples == null ? null : d.newSamples + r.newSamples;
+      }
+    } catch (e) { d.error = "how far the data has moved could not be measured: " + ((e as Error)?.message || e); }
+    drift[name] = d;
+    const studies = cohorts[name].studies;
+    cohorts[name].text = "locked " + lockDate(l.lock.at) + ": " + l.members.n.toLocaleString("en-US") + " patient" + (l.members.n === 1 ? "" : "s") +
+      " who were " + describeCohortDef(liveDef) +
+      (studies.length > 1 ? " — across " + studies.length + " studies" : studies[0] !== docStudy ? " — in " + studies[0] : "");
+  }
   // The children of a partition are disjoint and cover the parent by construction; counting
   // them is the check that the construction held, so a mismatch is reported, never hidden.
   const partitionResults: NonNullable<AnalysisResult["splits"]> = {};
@@ -487,6 +518,7 @@ export async function runAnalysis(template: AnalysisDoc | TemplateDoc, opts: Run
     cohorts: Object.fromEntries(names.map((n) => [n, {
       count: cohorts[n].count, text: cohorts[n].text,
       studies: cohorts[n].studies,
+      ...(drift[n] ? { lock: drift[n] } : {}),
       sql: Object.entries(cohorts[n].perStudy).map(([s, x]) => "-- " + s + "\n" + x.sql).join("\n\n-- combined at the analysis layer: each study is evaluated separately against its own\n" +
         "-- instance and the counts are ADDED; patient overlap across studies is not deduplicated.\n\n")
     }])),
diff --git a/lib/api-schemas.ts b/lib/api-schemas.ts
index 7a8b9d14..4af4e5ec 100644
--- a/lib/api-schemas.ts
+++ b/lib/api-schemas.ts
@@ -120,6 +120,13 @@ export const TableRequest = z.object({
   ...customData,
 });
 
+/** POST /api/lock — lock cohorts of a document: those named, or every one (the analysis as a whole). */
+export const LockRequest = z.object({
+  doc: DocEnvelope,
+  cohorts: z.array(z.string()).min(1).optional(),
+  ...customData,
+});
+
 /** A spec or a document goes out with the fields the envelope does not name. */
 type Open<T> = T & Record<string, unknown>;
 export type AnalysisBody = z.input<typeof AnalysisRequest>;
@@ -133,6 +140,7 @@ export type CellExplorerBody = z.input<typeof CellExplorerRequest>;
 export type MembersBody = z.input<typeof MembersRequest>;
 export type ViewPageBody = z.input<typeof ViewPageRequest>;
 export type TableBody = z.input<typeof TableRequest>;
+export type LockBody = z.input<typeof LockRequest>;
 
 /**
  * The body, checked against its envelope, with its defaults filled in and every field the
diff --git a/lib/cohort-lock-server.ts b/lib/cohort-lock-server.ts
new file mode 100644
index 00000000..0f185610
--- /dev/null
+++ b/lib/cohort-lock-server.ts
@@ -0,0 +1,91 @@
+// Locking cohorts (lib/cohort-lock.ts): evaluate what each definition selects right now, and keep it
+// as stored id sets the cohort then names — its patients, their samples, and each of its split
+// arms' patients — with when, and against which data, it was done.
+//
+// Every cohort asked for is locked at one moment, so an analysis locked as a whole is one snapshot:
+// a data load between two cohorts' locks cannot leave them reflecting different data. A cohort
+// that is already locked is locked afresh from its definition. Patient-level studies only: a lock
+// lists patients.
+import { resolveDocCohorts, resolveStudy, studyProfiles } from "./analysis.ts";
+import { resolverFor, PatientLevelResolver } from "./federation.ts";
+import { cohortStudies } from "./view-coverage.ts";
+import { oncokbPin } from "./annotation.ts";
+import { saveIdSet } from "./id-set-store.ts";
+import { lockDate } from "./cohort-lock.ts";
+import type { AnalysisDoc, CohortDef, CohortLock, LockedMembers } from "./types.ts";
+
+export interface Locked {
+  at: string;
+  dataVersion: string;
+  oncokbPin: string | null;
+  /** each cohort asked for -> its lock, to write into the document as `cohorts[name].lock` */
+  locks: Record<string, CohortLock>;
+}
+
+/**
+ * Lock `cohorts` of `doc` (every authored cohort when none are named): what each definition, and
+ * each of its split arms, selects now, saved as the principal's stored sets.
+ */
+export async function lockCohorts(principal: string, input: { doc: unknown; cohorts?: unknown },
+  /** what the data looks like now (lib/next-cache.ts dataVersion, passed in: that module exists only under Next) */
+  dataVersion: () => Promise<string>): Promise<Locked> {
+  const src = input.doc as AnalysisDoc;
+  if (!src || typeof src !== "object" || !src.cohorts || typeof src.cohorts !== "object") throw new Error("doc must be an analysis document with cohorts");
+  const authored = Object.keys(src.cohorts);
+  const names = input.cohorts == null ? authored : Array.isArray(input.cohorts) ? input.cohorts.map(String) : null;
+  if (!names || !names.length) throw new Error("cohorts must name at least one of the document's cohorts");
+  const unknown = names.filter((n) => !authored.includes(n));
+  if (unknown.length) throw new Error("no cohort " + unknown.map((n) => "“" + n + "”").join(", ") + " to lock; have " + authored.join(", "));
+  // a cohort locked again is locked from its definition, not from its last lock
+  const fresh: AnalysisDoc = { ...src, cohorts: Object.fromEntries(Object.entries(src.cohorts).map(([n, d]) => {
+    if (!names.includes(n)) return [n, d];
+    const { lock: _lock, ...rest } = d as CohortDef;
+    return [n, rest];
+  })) };
+  const { doc, docStudy } = await resolveDocCohorts(fresh);
+  const at = new Date().toISOString();
+  const [version, pin] = await Promise.all([dataVersion(), process.env.ONCOKB_PIN ? Promise.resolve(process.env.ONCOKB_PIN) : oncokbPin()]);
+  const lockOf = (cohort: string) => ({ cohort, at, dataVersion: version, oncokbPin: pin ?? null });
+
+  const resolvers = new Map<string, PatientLevelResolver>();
+  const resolver = async (requested: string): Promise<{ study: string; res: PatientLevelResolver }> => {
+    const study = await resolveStudy(requested, docStudy);
+    let res = resolvers.get(study);
+    if (!res) {
+      const r = await resolverFor(study, { oncokbPin: pin ?? undefined, ...(await studyProfiles(study)) });
+      if (!(r instanceof PatientLevelResolver))
+        throw new Error("a lock lists the cohort's patients, and " + r.instance.label + " is not entitled to patient-level data (" + study + ")");
+      res = r;
+      resolvers.set(study, r);
+    }
+    return { study, res };
+  };
+  /** one cohort's or arm's members now, per study, saved as a stored set (and its samples, when asked) */
+  const freeze = async (name: string, owner: string, withSamples: boolean): Promise<LockedMembers> => {
+    const def = doc.cohorts[name];
+    const patients: Record<string, string[]> = {}, samples: Record<string, string[]> = {};
+    for (const s of cohortStudies(def, docStudy)) {
+      const { study, res } = await resolver(s);
+      patients[study] = await res.members(def);
+      if (withSamples) samples[study] = await res.memberSamples(def);
+    }
+    const label = name + " — locked " + lockDate(at);
+    const count = (m: Record<string, string[]>) => Object.values(m).reduce((n, x) => n + x.length, 0);
+    const source = (ids: number) => ({ idsIn: ids, unmatched: 0, duplicates: 0, multiStudy: 0, lockOf: lockOf(owner) });
+    const p = await saveIdSet(principal, { name: label, level: "patient", perStudy: patients, source: source(count(patients)) }, { allowEmpty: true });
+    if (!withSamples) return { set: p.id, n: p.count };
+    const sm = await saveIdSet(principal, { name: label + " (samples)", level: "sample", perStudy: samples, source: source(count(samples)) }, { allowEmpty: true });
+    return { set: p.id, n: p.count, samples: sm.id, nSamples: sm.count };
+  };
+
+  const locks: Record<string, CohortLock> = {};
+  for (const name of names) {
+    const top = await freeze(name, name, true);
+    const children: Record<string, LockedMembers> = {};
+    // its split arms, at every depth: "<name> / <split> / <arm>[ / <split> / <arm> …]"
+    for (const child of Object.keys(doc.cohorts).filter((n) => n.startsWith(name + " / ") && !authored.includes(n)))
+      children[child.slice(name.length + 3)] = await freeze(child, name, false);
+    locks[name] = { ...top, at, dataVersion: version, oncokbPin: pin ?? null, ...(Object.keys(children).length ? { children } : {}) };
+  }
+  return { at, dataVersion: version, oncokbPin: pin ?? null, locks };
+}
diff --git a/lib/cohort-lock.ts b/lib/cohort-lock.ts
new file mode 100644
index 00000000..5c53248e
--- /dev/null
+++ b/lib/cohort-lock.ts
@@ -0,0 +1,81 @@
+// Locked cohorts: a cohort frozen to the patients its definition selected at one moment, so an
+// analysis stops drifting as patients are added to the data.
+//
+// A locked cohort keeps its definition (`all`, the record of how it was made) and gains a `lock`:
+// the stored id set of its patients then (lib/id-set-store.ts), its samples then, when, against
+// which data version and OncoKB release — and the frozen membership of each of its split arms,
+// keyed by the arm's name under the cohort ("<split> / <arm>"). The engine evaluates the set, not
+// the definition; the definition is still run, beside it, to say how far the data has moved since.
+//
+// `applyLocks` rewrites a document whose splits are expanded (lib/cohort-partitions.ts) but whose
+// `extends` is not yet resolved: a locked cohort, and each locked arm, becomes its set alone. An arm
+// added after the lock still `extends` its parent, so it is evaluated inside the frozen parent and
+// the parent's arms still add up to it. Run before `extends` resolves, in every pipeline that reads
+// a document's cohorts (runAnalysis, resolveDocCohorts), so no reader sees the live definition by
+// mistake. Pure and browser-safe.
+import type { AnalysisDoc, CohortDef, CohortLock, LockedMembers } from "./types.ts";
+
+/** The clause a locked cohort or arm compiles to: its patients when it was locked. */
+export function lockClause(m: LockedMembers): { kind: "patientList"; set: string } {
+  return { kind: "patientList", set: m.set };
+}
+
+/** What a locked name is evaluated from, and what its definition still says. */
+export interface AppliedLock {
+  /** the cohort that holds the lock: the name itself, or the cohort a split arm belongs to */
+  cohort: string;
+  lock: CohortLock;
+  members: LockedMembers;
+}
+
+/**
+ * Every locked cohort and arm in an expanded document, made its frozen set; and the document as
+ * it would be without the locks, which says what the definitions select now.
+ */
+export function applyLocks(doc: AnalysisDoc): { doc: AnalysisDoc; live: AnalysisDoc; locked: Record<string, AppliedLock> } {
+  const cohorts = doc.cohorts || {};
+  const holders = Object.entries(cohorts).filter(([, d]) => d && d.lock);
+  if (!holders.length) return { doc, live: doc, locked: {} };
+  const locked: Record<string, AppliedLock> = {};
+  for (const [cohort, d] of holders) {
+    const lock = validLock(d.lock, cohort);
+    locked[cohort] = { cohort, lock, members: lock };
+    for (const [rel, m] of Object.entries(lock.children || {})) {
+      const name = cohort + " / " + rel;
+      // an arm that no longer exists (its split was edited away) has nothing to freeze
+      if (cohorts[name]) locked[name] = { cohort, lock, members: validMembers(m, name) };
+    }
+  }
+  const out: Record<string, CohortDef> = {};
+  const live: Record<string, CohortDef> = {};
+  for (const [name, def] of Object.entries(cohorts)) {
+    const { lock: _lock, ...unlocked } = def;
+    live[name] = unlocked;
+    const l = locked[name];
+    if (!l) { out[name] = def; continue; }
+    const { extends: _ext, ...rest } = unlocked;
+    out[name] = { ...rest, all: [lockClause(l.members)] };
+  }
+  return { doc: { ...doc, cohorts: out }, live: { ...doc, cohorts: live }, locked };
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+function validMembers(m: unknown, name: string): LockedMembers {
+  const x = (m && typeof m === "object" ? m : {}) as Partial<LockedMembers>;
+  if (typeof x.set !== "string" || !UUID.test(x.set)) throw new Error("cohort “" + name + "” is locked, but its lock names no stored set of patients");
+  if (!Number.isInteger(x.n) || (x.n as number) < 0) throw new Error("cohort “" + name + "” is locked, but its lock does not say how many patients it froze");
+  return x as LockedMembers;
+}
+
+function validLock(l: unknown, name: string): CohortLock {
+  const x = validMembers(l, name) as CohortLock;
+  if (typeof x.at !== "string" || Number.isNaN(Date.parse(x.at))) throw new Error("cohort “" + name + "” is locked, but its lock does not say when");
+  return x;
+}
+
+/** "18 Oct 2026", the way a lock is named on the page and in a readback. */
+export function lockDate(at: string): string {
+  const d = new Date(at);
+  return Number.isNaN(d.getTime()) ? at : d.toLocaleDateString("en-GB", { day: "numeric", month: "short", year: "numeric", timeZone: "UTC" });
+}
diff --git a/lib/cohort2.ts b/lib/cohort2.ts
index 1c278363..2a0da726 100644
--- a/lib/cohort2.ts
+++ b/lib/cohort2.ts
@@ -20,6 +20,7 @@ import { clinicalValueFoldSql, foldedEqualsSql } from "./event-names.ts";
 import { linesCtes, DEFAULT_LINE_GAP } from "./treatment-lines.ts";
 import { clinicalTable } from "./custom-data.ts";
 import { idSetTable, idSetIfLoaded, ID_SET_UUID } from "./id-sets.ts";
+import { lockClause } from "./cohort-lock.ts";
 import type {
   CohortDef, Clause, Leaf, CompileCtx, ClinicalLeaf, ClinicalRange,
   ProfiledLeaf, CaseListLeaf, GenomicDataLeaf, GenericAssayLeaf,
@@ -409,6 +410,36 @@ function patientListLeafSql(leaf: PatientListLeaf, ctx: Ctx): string {
   return basePatientsSql(ctx.study, dbOf(ctx)) + "\n    AND " + member;
 }
 
+/** The samples, as bare ids, of the patients `patientsSql` selects in `study`: what a lock records beside them. */
+export function memberSamplesSql(patientsSql: string, study: string, db: string): string {
+  return "SELECT DISTINCT " + PID("sample_unique_id", study) + " AS sid\n" +
+    "  FROM " + db + ".sample_derived\n" +
+    "  WHERE cancer_study_identifier = " + sq(study) + "\n" +
+    "    AND " + PID("patient_unique_id", study) + " IN (SELECT pid FROM (" + patientsSql + "))";
+}
+
+/**
+ * How far the data has moved from a locked cohort, in `study`: of the frozen patients
+ * (`lockedSql`) how many the data still holds, what the definition (`liveSql`) selects now, who it
+ * would add and who it would drop, and how many samples the frozen patients have that were not
+ * theirs when locked (`samplesSet`, the lock's sample set; null when the lock recorded none).
+ */
+export function lockDriftSql(lockedSql: string, liveSql: string, study: string, db: string, samplesSet: string | null): string {
+  const pid = PID("patient_unique_id", study), sid = PID("sample_unique_id", study);
+  let newSamples = "toInt64(-1)";
+  if (samplesSet) {
+    const table = idSetTable(samplesSet, study, "sample");
+    newSamples = "(SELECT count() FROM " + db + ".sample_derived WHERE cancer_study_identifier = " + sq(study) +
+      " AND " + pid + " IN (SELECT pid FROM locked)" + (table ? " AND " + sid + " NOT IN (SELECT id FROM " + table + ")" : "") + ")";
+  }
+  return "WITH locked AS (" + lockedSql + "),\n     live AS (" + liveSql + ")\n" +
+    "SELECT (SELECT count() FROM locked) AS present,\n" +
+    "       (SELECT count() FROM live) AS now,\n" +
+    "       (SELECT count() FROM live WHERE pid NOT IN (SELECT pid FROM locked)) AS entered,\n" +
+    "       (SELECT count() FROM locked WHERE pid NOT IN (SELECT pid FROM live)) AS left,\n" +
+    "       " + newSamples + " AS newSamples";
+}
+
 // The salt is part of what every held-out result means: changing it reshuffles every
 // discovery/validation partition ever reported. test/cohort.test.ts pins it.
 export const SPLIT_SALT = "cohort-lab-split-v1";
@@ -478,7 +509,9 @@ function normalizeSugar(def: CohortDef): CohortDef {
 // def -> SQL producing the cohort's patient stable ids (column: pid)
 export function compileCohortDef(def: CohortDef | null | undefined, { oncokbPin, profiles, gaProfiles, study = STUDY, db }: Partial<CompileCtx> = {}): string {
   if (!def) return basePatientsSql(study, db || DB);
-  const d = normalizeSugar(def);
+  // a locked cohort is its frozen patients wherever it is compiled, not only inside runAnalysis
+  // (which has already made it so, lib/cohort-lock.ts): Explore, an oncoprint spec, a link
+  const d = def.lock ? { ...normalizeSugar(def), all: [lockClause(def.lock)] } : normalizeSugar(def);
   const clauses = d.all;
   // No clauses means every patient in the study — the same thing an absent
   // definition means, and a legitimate cohort (it is the denominator for
diff --git a/lib/doc-version.ts b/lib/doc-version.ts
index 601cfe92..d9778c6f 100644
--- a/lib/doc-version.ts
+++ b/lib/doc-version.ts
@@ -14,7 +14,7 @@
 
 import { flattenSplits, viewDrawProblem } from "./partition-arms.ts";
 
-export const DOC_VERSION = "2.7";
+export const DOC_VERSION = "2.8";
 
 /** what upgrading a document did, reported in the result so a reader is told, not left to notice */
 export interface DocUpgrade {
@@ -201,13 +201,22 @@ function studyTrackRenamed(doc: AnyDoc, changes: string[]): AnyDoc {
  */
 const idSetsNamed = (doc: AnyDoc): AnyDoc => doc;
 
+/**
+ * 2.7 → 2.8: a cohort may be locked (`lock`, and the document's `locked`): evaluated from the
+ * patients it selected then, not from its definition. Nothing an older document says changes; the
+ * version exists so a 2.7 engine refuses a locked document rather than silently running the live
+ * definitions, which is exactly the drift a lock is there to stop.
+ */
+const cohortsLockable = (doc: AnyDoc): AnyDoc => doc;
+
 /** each step upgrades from the version before `to`; unversioned documents start at the first */
 const STEPS: { to: string; run: (doc: AnyDoc, changes: string[]) => AnyDoc }[] = [
   { to: "2.3", run: partitionsToSplits },
   { to: "2.4", run: splitsNoLongerReplace },
   { to: "2.5", run: viewsNameTheirCohorts },
   { to: "2.6", run: studyTrackRenamed },
-  { to: "2.7", run: idSetsNamed }
+  { to: "2.7", run: idSetsNamed },
+  { to: "2.8", run: cohortsLockable }
 ];
 
 /**
diff --git a/lib/dsl-reference.ts b/lib/dsl-reference.ts
index ce48b9d8..f0b42dd7 100644
--- a/lib/dsl-reference.ts
+++ b/lib/dsl-reference.ts
@@ -1283,7 +1283,10 @@ cohortDef := { "all": [clause × 0-8],         // ANDed; [] means every patient
                "lineGap"?: 90,                // derived-treatment-line gap, days
                "notes"?:   "<prose>",         // the analyst's own note on this cohort; never compiled
                "from"?:    { "saved": "<id>", "name": "<name>", "hash": "<sha256>", "savedAt"?: "<when>" },  // set by the page: the saved cohort this was copied from, and the hash of what was copied; never compiled
-               "splits"?:  { "<name>": splitDef } }  // divisions of this cohort into arms that add up to it
+               "splits"?:  { "<name>": splitDef },  // divisions of this cohort into arms that add up to it
+               "lock"?:    { "set": "<id set>", "n": N, "samples"?: "<id set>", "nSamples"?: N, "at": "<ISO time>",
+                             "dataVersion"?: "…", "oncokbPin"?: "…", "children"?: { "<split> / <arm>": { "set", "n" } } } }
+                                              // frozen to the patients it selected at "at" — see "Locked cohorts" below
 splitDef  := { "arms": [ { "name": "<label>", "where": clause, "splits"?: {…} } × 1-8 ],  // tested in order; first match wins; an arm may be split again
                "other"?: "<label>",            // the remainder's name, default "Other"
                "otherSplits"?: {…},            // splits of the remainder
@@ -1342,7 +1345,7 @@ included; 2.3 → 2.4 ended "a split replaces what it splits" — a view that dr
 under 2.3 is given those arms by name, so it draws the same thing; 2.4 → 2.5 ended "a view with no
 \`cohorts\` draws every cohort" — such a view is given every authored cohort by name; 2.5 → 2.6 renamed
 the oncoprint's study track "Study of origin"; 2.6 → 2.7 let a list clause name a stored id set, and
-changes nothing an older document says) — and saving it writes the new
+2.7 → 2.8 let a cohort be locked; neither changes anything an older document says) — and saving it writes the new
 version. One with no \`dsl\` is read the same way, so
 leaving it out is harmless. One written for a NEWER version than the server reads is refused,
 rather than silently ignoring what it does not understand.
@@ -1375,6 +1378,22 @@ kind of clause that can **never** leave for a remote or aggregate-only participa
 cohort is refused before any request is made, the same guarantee \`docs/DATA-BOUNDARY.md\`
 describes for every other identifier-bearing path.
 
+**Locked cohorts.** A cohort can be frozen to the patients its definition selects at one moment,
+so an analysis stops drifting as patients are added to the data: \`lock\` names the stored id set
+of those patients (and of their samples), when it was taken, the data version and OncoKB release
+then, and, under \`children\`, the frozen patients of each of its split arms by name. The engine
+evaluates the set, not the definition; the definition stays as the record of how the cohort was
+made, and is still run beside the set, so the result's \`cohorts[name].lock\` says how far the
+data has moved: what the definition selects \`now\`, who it would add (\`entered\`) or drop
+(\`left\`), how many frozen patients the data still holds (\`present\` of \`n\`), and how many
+samples those patients have that they did not have then (\`newSamples\` — a lock freezes
+patients, and views read every sample of them). A split arm added after the lock is evaluated
+inside the frozen cohort, so arms still add up to it. The document's \`locked\` says every cohort
+was locked at once, one moment for all. Locks are taken by \`POST /api/lock\` (\`{doc, cohorts?}\`,
+every cohort when none are named) or the page — a cohort's menu, or "Lock all cohorts" — and need a
+sign-in, since the sets are the reader's. Unlocking is removing \`lock\`. Values recorded about
+the frozen patients (a re-called mutation, an edited clinical field) are read as they are now.
+
 **Stored id sets.** A long list is saved once on the server — \`POST /api/id-sets\` with
 \`{name, level:"sample"|"patient", studies, ids}\`, or "+ Add cohort" → "From a list of ids" — and
 named by its id: \`{"kind":"sampleList","set":"<id>"}\`. The ids are matched to the studies' own
@@ -1959,6 +1978,9 @@ Leaf kinds:
   internal underscore, since a bare id may contain one). A list the page saved on the server is
   {"kind":"sampleList"|"patientList","set":"<id>","label":"…","n":N}: keep such a clause as it is
   (copy it whole when reusing the cohort) — its ids are not in the document.
+- A cohort with "lock" is frozen to the patients it selected when locked: the engine evaluates the
+  lock, not "all". Leave "lock" as it is; editing "all" does not change who is in a locked cohort
+  (the result's cohorts[name].lock reports what "all" selects now). Remove "lock" to unlock it.
 - {"kind":"clinical",...} also supports "values":[...] (OR across values), "range":{"gte":60,"lt":80}
   (numeric), and "per":"sample" (patient matches if ANY sample matches — say so when used).
   "op"+"percentile" (0-1, e.g. {"op":">=","percentile":0.8}) resolves "value" live from a
diff --git a/lib/federation.ts b/lib/federation.ts
index f6bb2af2..905dc981 100644
--- a/lib/federation.ts
+++ b/lib/federation.ts
@@ -23,7 +23,7 @@ import { chQuery, DB, PRIMARY, connections, loopbackOnlyConn, isAbortError, Loop
 import { sq } from "./compiler.ts";
 import { canonicalEventName, nameFoldSql, foldedEqualsSql } from "./event-names.ts";
 import { linesCtes, lineGapOf, inLineClassesSql, TREATMENT_EVENT } from "./treatment-lines.ts";
-import { compileCohortDef, eventTypeMatchSql } from "./cohort2.ts";
+import { compileCohortDef, eventTypeMatchSql, memberSamplesSql, lockDriftSql } from "./cohort2.ts";
 import { axisKind, axisLabel, axisSelect, corrPValue, plotShape, tukey, validateAxis,
   categoryColor, CATEGORY_CAP, COLOR_CAP, DEFAULT_BINS, POINTS_CAP, VIOLIN_BINS,
   plotBinsSql, plotBoxSql, plotCountSql, plotCoverageSql, plotMomentsSql, plotPointsSql, plotStatsSql, plotTableSql, plotViolinSql,
@@ -1217,6 +1217,8 @@ export function carriesPatientIds(def: CohortDef | null | undefined): boolean {
     if ((o.kind === "sampleList" || o.kind === "patientList") && Array.isArray(o.ids) && o.ids.length > 0) return true;
     // a stored set is the same list kept on the server: the instance would be asked for its ids
     if ((o.kind === "sampleList" || o.kind === "patientList") && (o as { set?: unknown }).set !== undefined) return true;
+    // a locked cohort is its frozen patients' ids (lib/cohort-lock.ts)
+    if ((o as { lock?: unknown }).lock) return true;
     return Object.values(x).some(walk);
   };
   return walk(def);
@@ -1993,6 +1995,23 @@ export class PatientLevelResolver extends BaseResolver implements PatientLevelCa
     return r.data.map((x) => x.pid);
   }
 
+  /** The samples of a cohort's patients, as bare ids: what locking a cohort records beside its patients. */
+  async memberSamples(def: CohortDef | null | undefined): Promise<string[]> {
+    const r = await chQuery<ChRow>(memberSamplesSql(this.cohortSql(def), this.study, this.instance.conn.db), this.instance.conn);
+    return r.data.map((x) => x.sid);
+  }
+
+  /**
+   * How far the data has moved from a locked cohort (lib/cohort-lock.ts): counts only, but over the
+   * frozen patients' ids, so patient-level only, as members() is.
+   */
+  async lockDrift(locked: CohortDef, live: CohortDef, samplesSet: string | null): Promise<{ present: number; now: number; entered: number; left: number; newSamples: number | null; sql: string }> {
+    const sql = lockDriftSql(this.cohortSql(locked), this.cohortSql(live), this.study, this.instance.conn.db, samplesSet);
+    const r = (await this.runLogged<ChRow>("lock: drift since locked", sql, this.instance.conn)).data[0];
+    const ns = Number(r.newSamples);
+    return { present: Number(r.present), now: Number(r.now), entered: Number(r.entered), left: Number(r.left), newSamples: ns < 0 ? null : ns, sql };
+  }
+
   /**
    * Per-patient (time, event, covariate values) rows for a Cox fit — patient-level only, for
    * the same reason plotPoints() is: it lives nowhere on AggregateResolver, so a participant
diff --git a/lib/id-set-store.ts b/lib/id-set-store.ts
index a40ae508..cef27f52 100644
--- a/lib/id-set-store.ts
+++ b/lib/id-set-store.ts
@@ -17,8 +17,11 @@ import { AccessError } from "./auth.ts";
 import { groupsOf, readableWhere, canRead, canShare, rightsOf, sharingOf, validateSharing, type Rights, type Shareable, type Sharing } from "./access.ts";
 import type { IdSetLevel, LoadedIdSet } from "./id-sets.ts";
 
-/** how the list was matched when it was saved */
-export interface IdSetSource { idsIn: number; unmatched: number; duplicates: number; multiStudy: number }
+/** how the list was matched when it was saved; for a lock's set, which cohort it froze and when */
+export interface IdSetSource {
+  idsIn: number; unmatched: number; duplicates: number; multiStudy: number;
+  lockOf?: { cohort: string; at: string; dataVersion?: string; oncokbPin?: string | null };
+}
 
 export interface IdSetMeta {
   id: string; name: string; owner: string; ownerEmail: string; level: IdSetLevel;
@@ -89,10 +92,12 @@ export async function readIdSet(principal: string, id: string): Promise<{ meta:
 }
 
 /**
- * Save a set: members already matched to the studies' own ids (lib/id-sets-server.ts), as bare
- * ids per study. Empty studies are dropped; a set with no members at all is refused.
+ * Save a set: members already matched to the studies' own ids (lib/id-set-import.ts), as bare
+ * ids per study. Empty studies are dropped; a set with no members at all is refused unless
+ * `allowEmpty` (a lock freezing a cohort or arm that held nobody).
  */
-export async function saveIdSet(principal: string, input: { name: string; level: IdSetLevel; perStudy: Record<string, string[]>; source: IdSetSource }): Promise<IdSetMeta> {
+export async function saveIdSet(principal: string, input: { name: string; level: IdSetLevel; perStudy: Record<string, string[]>; source: IdSetSource },
+  opts: { allowEmpty?: boolean } = {}): Promise<IdSetMeta> {
   const name = String(input.name ?? "").trim().slice(0, 200);
   if (!name) throw new Error("a stored id set needs a name");
   if (input.level !== "patient" && input.level !== "sample") throw new Error("level must be 'patient' or 'sample'");
@@ -103,7 +108,8 @@ export async function saveIdSet(principal: string, input: { name: string; level:
   }
   const studies = Object.keys(perStudy);
   const count = studies.reduce((n, s) => n + perStudy[s].length, 0);
-  if (!count) throw new Error("none of the ids matched a " + input.level + " of the studies given; nothing to save");
+  // a pasted list that matched nothing is a mistake; a locked arm that held nobody is a fact (lib/cohort-lock-server.ts)
+  if (!count && !opts.allowEmpty) throw new Error("none of the ids matched a " + input.level + " of the studies given; nothing to save");
   if (count > ID_SET_MAX) throw new Error("a stored id set holds at most " + ID_SET_MAX.toLocaleString("en-US") + " ids; this one has " + count.toLocaleString("en-US"));
   const json = JSON.stringify(perStudy);
   const id = randomUUID();
diff --git a/lib/id-sets-server.ts b/lib/id-sets-server.ts
index 36861d63..5babb382 100644
--- a/lib/id-sets-server.ts
+++ b/lib/id-sets-server.ts
@@ -10,8 +10,11 @@ import { requirePrincipal } from "./auth.ts";
 import { studyRouting, instanceForStudy } from "./federation.ts";
 import { peerForStudy } from "./federation-remote.ts";
 
-/** The most stored sets one request may name. */
-export const MAX_SETS_PER_REQUEST = 16;
+/**
+ * The most stored sets one request may name: a locked analysis names two per cohort and one per
+ * locked arm, and a document holds at most 48 cohorts with their arms.
+ */
+export const MAX_SETS_PER_REQUEST = 128;
 
 /**
  * Run `fn` with every stored set `body` names read for it (a no-op when it names none). A set
diff --git a/lib/id-sets.ts b/lib/id-sets.ts
index a66ffcf6..98082767 100644
--- a/lib/id-sets.ts
+++ b/lib/id-sets.ts
@@ -114,11 +114,17 @@ export function idSetRefsIn(x: unknown): string[] {
     if (!v || typeof v !== "object" || seen.has(v)) return;
     seen.add(v);
     if (Array.isArray(v)) { v.forEach(walk); return; }
-    const o = v as { kind?: unknown; set?: unknown };
+    const o = v as { kind?: unknown; set?: unknown; lock?: unknown };
     if ((o.kind === "sampleList" || o.kind === "patientList") && o.set !== undefined) {
       if (typeof o.set !== "string" || !ID_SET_UUID.test(o.set)) throw new Error(o.kind + " clause: set must be a stored id set's id (a uuid), got " + JSON.stringify(o.set));
       out.add(o.set);
     }
+    // a locked cohort's frozen patients and samples, and each locked arm's (lib/cohort-lock.ts)
+    if (o.lock && typeof o.lock === "object") {
+      const l = o.lock as { set?: unknown; samples?: unknown; children?: Record<string, { set?: unknown; samples?: unknown }> };
+      for (const m of [l, ...Object.values(l.children && typeof l.children === "object" ? l.children : {})])
+        for (const x of [m?.set, m?.samples]) if (typeof x === "string" && ID_SET_UUID.test(x)) out.add(x);
+    }
     Object.values(v).forEach(walk);
   };
   walk(x);
diff --git a/lib/types.ts b/lib/types.ts
index 8ed2980c..224cd9c7 100644
--- a/lib/types.ts
+++ b/lib/types.ts
@@ -227,10 +227,37 @@ export interface CohortDef {
    * engine never reads it; the page compares it with the saved cohort to offer an update.
    */
   from?: CohortSource;
+  /** frozen to the patients it selected when it was locked (lib/cohort-lock.ts) */
+  lock?: CohortLock;
 }
 
 export interface CohortSource { saved: string; name: string; hash: string; savedAt?: string }
 
+/** A cohort's (or a split arm's) members when it was locked: stored id sets (lib/id-set-store.ts). */
+export interface LockedMembers {
+  /** a patient-level stored set: the patients it selected */
+  set: string;
+  n: number;
+  /** a sample-level stored set: those patients' samples then, what "new samples since" is measured against */
+  samples?: string;
+  nSamples?: number;
+}
+
+/**
+ * A cohort frozen to what its definition selected at one moment (lib/cohort-lock.ts). The engine
+ * evaluates the stored set; the definition is kept, and still run beside it, to say how far the
+ * data has moved since.
+ */
+export interface CohortLock extends LockedMembers {
+  /** when it was locked (ISO 8601) */
+  at: string;
+  /** the warehouse's data version then, and the OncoKB release the definition was read against */
+  dataVersion?: string;
+  oncokbPin?: string | null;
+  /** each split arm's own frozen members, keyed by its name under this cohort ("<split> / <arm>") */
+  children?: Record<string, LockedMembers>;
+}
+
 /**
  * One arm of a split: a name and the clause a patient must match to be in it. Arms are tested in
  * order and the first match wins, so a patient is in exactly one arm. An arm may itself be split.
@@ -1529,11 +1556,32 @@ export interface AnalysisDoc {
    * local upload, sent by the browser that holds it.
    */
   uploads?: { as: string; dataset: string; version: number }[];
+  /** every cohort was locked at once, at this moment (lib/cohort-lock.ts): the analysis as of then */
+  locked?: { at: string; dataVersion?: string; oncokbPin?: string | null };
 }
 
 // ---------- results ---------------------------------------------------------
 export interface CohortResult {
   count: number; text: string; studies: string[]; sql: string;
+  /** for a locked cohort or arm: when, how many it froze, and how far the data has moved since */
+  lock?: LockDrift;
+}
+export interface LockDrift {
+  /** the locked cohort that holds the lock (this name, or the cohort a split arm belongs to) */
+  cohort: string;
+  at: string;
+  dataVersion?: string;
+  /** patients frozen, and of those how many the data still holds */
+  n: number;
+  present: number;
+  /** what the definition selects now, and how that differs from the frozen patients */
+  now: number;
+  entered: number;
+  left: number;
+  /** samples the frozen patients have now that they did not have when locked; null when not measured */
+  newSamples: number | null;
+  /** why the movement could not be measured (the frozen patients still answered) */
+  error?: string;
 }
 export interface CompareCell {
   cohort: string; profiled: number; any: number; driver: number;
diff --git a/test/cohort-lock.test.ts b/test/cohort-lock.test.ts
new file mode 100644
index 00000000..989eedaa
--- /dev/null
+++ b/test/cohort-lock.test.ts
@@ -0,0 +1,88 @@
+// Locked cohorts (lib/cohort-lock.ts): a locked cohort, and each locked split arm, is evaluated
+// from its frozen set wherever it is compiled; an arm added after the lock is evaluated inside the
+// frozen cohort; the sets a lock names are read for its request, and never go where ids may not.
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { applyLocks, lockDate } from "../lib/cohort-lock.ts";
+import { resolveExtends } from "../lib/cohort-extends.ts";
+import { compileCohortDef } from "../lib/cohort2.ts";
+import { withIdSets, idSetRefsIn, idSetTableName } from "../lib/id-sets.ts";
+import { carriesPatientIds } from "../lib/federation.ts";
+import { lockDriftSql } from "../lib/cohort2.ts";
+import type { AnalysisDoc, CohortLock } from "../lib/types.ts";
+
+const P = "11111111-1111-4111-8111-111111111111", S = "22222222-2222-4222-8222-222222222222", F = "33333333-3333-4333-8333-333333333333";
+const lock: CohortLock = { set: P, n: 3, samples: S, nSamples: 4, at: "2026-10-18T16:30:00.000Z", dataVersion: "v1", oncokbPin: "v7.5",
+  children: { "sex / Female": { set: F, n: 1 } } };
+const KRAS = { kind: "oql" as const, q: "KRAS: MUT" };
+const female = { kind: "clinical" as const, attribute: "SEX", values: ["Female"] };
+// a document as runAnalysis has it after splits are expanded: the arms `extends` their cohort
+const expanded = (): AnalysisDoc => ({ study: "s1", cohorts: {
+  A: { all: [KRAS], lock },
+  "A / sex / Female": { extends: "A", all: [female] },
+  "A / stage / IV": { extends: "A", all: [{ kind: "clinical", attribute: "STAGE", values: ["IV"] }] },
+  B: { all: [KRAS] },
+} });
+
+describe("applyLocks", () => {
+  test("a locked cohort, and its locked arm, become their sets; the rest keep their definitions", () => {
+    const { doc, locked } = applyLocks(expanded());
+    assert.deepEqual(doc.cohorts.A.all, [{ kind: "patientList", set: P }]);
+    assert.deepEqual(doc.cohorts["A / sex / Female"].all, [{ kind: "patientList", set: F }]);
+    assert.equal(doc.cohorts["A / sex / Female"].extends, undefined, "a frozen arm does not inherit its cohort's clauses");
+    assert.deepEqual(doc.cohorts.B.all, [KRAS]);
+    assert.deepEqual(Object.keys(locked).sort(), ["A", "A / sex / Female"]);
+    assert.equal(locked["A / sex / Female"].cohort, "A");
+  });
+  test("an arm added after the lock is evaluated inside the frozen cohort, so arms still add up to it", () => {
+    const resolved = resolveExtends(applyLocks(expanded()).doc);
+    assert.deepEqual(resolved.cohorts["A / stage / IV"].all, [{ kind: "patientList", set: P }, { kind: "clinical", attribute: "STAGE", values: ["IV"] }]);
+  });
+  test("the live document is the same cohorts without their locks: what the definitions select now", () => {
+    const live = resolveExtends(applyLocks(expanded()).live);
+    assert.deepEqual(live.cohorts.A.all, [KRAS]);
+    assert.equal(live.cohorts.A.lock, undefined);
+    assert.deepEqual(live.cohorts["A / sex / Female"].all, [KRAS, female]);
+  });
+  test("a document with no lock is handed back untouched", () => {
+    const d: AnalysisDoc = { cohorts: { B: { all: [KRAS] } } };
+    const r = applyLocks(d);
+    assert.equal(r.doc, d);
+    assert.equal(r.live, d);
+  });
+  test("a lock that names no set, no count or no moment is refused by name, not run as its definition", () => {
+    assert.throws(() => applyLocks({ cohorts: { A: { all: [KRAS], lock: { ...lock, set: "nope" } } } }), /“A” is locked, but its lock names no stored set/);
+    assert.throws(() => applyLocks({ cohorts: { A: { all: [KRAS], lock: { ...lock, n: -1 } } } }), /does not say how many/);
+    assert.throws(() => applyLocks({ cohorts: { A: { all: [KRAS], lock: { ...lock, at: "soon" } } } }), /does not say when/);
+  });
+});
+
+describe("a locked cohort compiled anywhere", () => {
+  const sets = (fn: () => string) => withIdSets([{ id: P, name: "A — locked", level: "patient", count: 3, perStudy: { s1: ["P-1", "P-2", "P-3"] } }],
+    new Map([["s1", "a"]]), async () => fn());
+  test("compiles to its frozen set even outside runAnalysis (Explore, an oncoprint spec)", async () => {
+    const sql = await sets(() => compileCohortDef({ all: [KRAS], lock }, { study: "s1", db: "db" }));
+    assert.match(sql, new RegExp("IN \\(SELECT id FROM " + idSetTableName(P, "s1") + "\\)"));
+    assert.doesNotMatch(sql, /KRAS/);
+  });
+  test("the drift query measures the frozen set against the definition, and new samples against the frozen samples", async () => {
+    const sql = await withIdSets([{ id: S, name: "A — samples", level: "sample", count: 4, perStudy: { s1: ["S-1"] } }], new Map([["s1", "a"]]),
+      async () => lockDriftSql("SELECT 'P-1' AS pid", "SELECT 'P-9' AS pid", "s1", "db", S));
+    assert.match(sql, /AS entered/);
+    assert.match(sql, /AS left/);
+    assert.match(sql, new RegExp("NOT IN \\(SELECT id FROM " + idSetTableName(S, "s1") + "\\)"));
+  });
+});
+
+describe("a lock's sets travel with its request, and nowhere ids may not", () => {
+  test("idSetRefsIn finds the patients, samples and arm sets a lock names", () => {
+    assert.deepEqual(idSetRefsIn({ cohorts: { A: { all: [KRAS], lock } } }).sort(), [P, S, F].sort());
+  });
+  test("carriesPatientIds counts a locked cohort as ids", () => {
+    assert.equal(carriesPatientIds({ all: [KRAS], lock }), true);
+    assert.equal(carriesPatientIds({ all: [KRAS] }), false);
+  });
+  test("a lock is named by its day", () => {
+    assert.equal(lockDate(lock.at), "18 Oct 2026");
+  });
+});

From fdf7eee20dd1fe7ed83327930f106ed5e0d0bd71 Mon Sep 17 00:00:00 2001
From: Aaron Lisman <lisman.aaron@gmail.com>
Date: Sun, 18 Oct 2026 22:02:33 +0000
Subject: [PATCH 4/7] Saving a cohort from its card asks for its library name
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- "save to library…" / "save changes to library…" open a dialog prefilled
  with the cohort's library name, which says what saving does: a new saved
  cohort, the one it is linked to updated, or (in red, button "Replace")
  another saved cohort of that name replaced.
- Saved under another name, the cohort takes that name in the analysis too,
  views drawing it included (as "edit…" renames), unless the analysis already
  has a cohort of that name; then it keeps its name and a message says so.
- "save changes to library…" is offered only for a cohort linked to a saved
  cohort (copied from it, or saved before) and changed since. A cohort that
  merely shares a saved cohort's name (default names repeat: "selection",
  "from Cell Explorer") is offered as a new save, and the dialog warns.
- The pasted-list tab has no default name: "Match and save" waits for one.
- The source badge reads "in library" (was a bare hash), and its tooltip and
  panel say "linked to your saved cohort" (was "copied from", wrong for a
  cohort that was saved rather than copied).

Verified on the test server (dialog, rename, no page errors) and in the
e2e save check: rename on first save, view follows, "in library" badge,
"Updates your saved cohort" on re-save, a same-name cohort offered as new
with the Replace warning. Gate (GATE_PORT=4111 scripts/gate.sh) passes: 256
e2e checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvdfHurd9t63GK2ToazMti
---
 app/lab/add-cohort-dialog.tsx | 12 ++++----
 app/lab/analysis-sections.tsx | 30 ++++++++++++-------
 app/lab/dialogs.tsx           | 34 ++++++++++++++++++++++
 app/lab/use-cohort-edits.ts   | 39 ++++++++++++++++++-------
 app/lab/view-chrome.tsx       |  4 +--
 e2e.cjs                       | 54 ++++++++++++++++++++++++++++-------
 6 files changed, 134 insertions(+), 39 deletions(-)

diff --git a/app/lab/add-cohort-dialog.tsx b/app/lab/add-cohort-dialog.tsx
index e6283da7..4d6fd27d 100644
--- a/app/lab/add-cohort-dialog.tsx
+++ b/app/lab/add-cohort-dialog.tsx
@@ -264,7 +264,8 @@ function ListSource({ studies, saved, full, replaces, addTitle, nameFor, onAdd,
 }) {
   const [text, setText] = useState("");
   const [level, setLevel] = useState<"sample" | "patient">("sample");
-  const [name, setName] = useState("from a list");
+  // no default: a list's name is how it is found again, in the analysis and the library
+  const [name, setName] = useState("");
   const [busy, setBusy] = useState(false);
   const [err, setErr] = useState<string | null>(null);
   const [done, setDone] = useState<SavedSet | null>(null);
@@ -274,7 +275,7 @@ function ListSource({ studies, saved, full, replaces, addTitle, nameFor, onAdd,
   const save = async () => {
     setBusy(true); setErr(null); setDone(null);
     try {
-      const res = await api.idSets.create({ name: name.trim() || "from a list", level, studies, ids });
+      const res = await api.idSets.create({ name: name.trim(), level, studies, ids });
       const j = await res.json();
       if (!res.ok || j.error) throw new Error(j.error || res.statusText);
       setDone(j);
@@ -310,10 +311,11 @@ function ListSource({ studies, saved, full, replaces, addTitle, nameFor, onAdd,
         onChange={(e) => { setText(e.target.value); setDone(null); }} />
       <div className="viewtb">
         <div className="tbz">
-          <label className="tbfield">name <Input aria-label="set name" className="h-ctl w-56 text-md md:text-md" value={name}
+          <label className="tbfield">name <Input aria-label="set name" className="h-ctl w-56 text-md md:text-md" value={name} placeholder="name this list…"
             onChange={(e) => { setName(e.target.value); setDone(null); }} /></label>
-          <Button variant="outline" size="sm" className={cn(TB, "idsetsave")} disabled={busy || !ids.length || !studies.length}
-            title={!studies.length ? "the analysis names no study to match the ids in" : !ids.length ? "paste some ids first" : undefined}
+          <Button variant="outline" size="sm" className={cn(TB, "idsetsave")} disabled={busy || !ids.length || !studies.length || !name.trim()}
+            title={!studies.length ? "the analysis names no study to match the ids in" : !ids.length ? "paste some ids first"
+              : !name.trim() ? "name the list first: it is how it is found again, in the analysis and your library" : undefined}
             onClick={() => void save()}>
             {busy && <span className="spinner" />}Match and save {ids.length ? ids.length.toLocaleString() + " id" + (ids.length === 1 ? "" : "s") : ""}</Button>
         </div>
diff --git a/app/lab/analysis-sections.tsx b/app/lab/analysis-sections.tsx
index 419afe80..ef764355 100644
--- a/app/lab/analysis-sections.tsx
+++ b/app/lab/analysis-sections.tsx
@@ -11,6 +11,7 @@ import { Button } from "../_ui/button";
 import { CHIP } from "../_ui/toolbar.ts";
 import { cn } from "../../lib/cn";
 import { TB } from "../_ui/toolbar.ts";
+import { SaveToLibraryDialog } from "./dialogs.tsx";
 import { Dialog, DialogClose, DialogContent, DialogFooter, DialogHeader, DialogTitle } from "../_ui/dialog";
 import { Textarea } from "../_ui/textarea";
 import CohortPills from "./pills";
@@ -63,7 +64,7 @@ export interface AnalysisCtx {
   updateFromSaved: (name: string) => void;
   /** whether a cohort has anything to save to the library, and the action that saves it */
   cohortSaveState: (name: string) => CohortSaveState | null;
-  saveCohortToLibrary: (name: string) => Promise<void>;
+  saveCohortToLibrary: (name: string, as?: string) => Promise<void>;
   /** lock the cohorts named, or every one (the analysis); unlock one, or all (lib/cohort-lock.ts) */
   lockCohorts: (names?: string[]) => Promise<void>;
   unlockCohort: (name: string) => void;
@@ -167,8 +168,10 @@ function EmptyViewCard({ ctx, vi }: { ctx: AnalysisCtx; vi: number }) {
 }
 
 export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
-  const { busy, canSave, catalogAttrs, cohortCells, cohortSaveState, cohortSource, doc, lockCohorts, openCohortCells, loggedIn, menuOpenRef, openCohortEdit, removeCohort, removePartitionNamed, renamePartitionRow, result, saveCohortToLibrary, setPartitionDef, setUpgradeNote, showClauseData, spaces, splitCohortBy, splitsFlat, studyNames, unlockAll, unlockCohort, updateFromSaved, upgradeNote, viewTitle } = ctx;
+  const { busy, canSave, saved, catalogAttrs, cohortCells, cohortSaveState, cohortSource, doc, lockCohorts, openCohortCells, loggedIn, menuOpenRef, openCohortEdit, removeCohort, removePartitionNamed, renamePartitionRow, result, saveCohortToLibrary, setPartitionDef, setUpgradeNote, showClauseData, spaces, splitCohortBy, splitsFlat, studyNames, unlockAll, unlockCohort, updateFromSaved, upgradeNote, viewTitle } = ctx;
   const [lockingAll, setLockingAll] = useState(false);
+  /** the cohort whose "save to library…" dialog is open */
+  const [savingToLibrary, setSavingToLibrary] = useState<string | null>(null);
   const lockAll = async () => {
     if (!canSave()) return;
     setLockingAll(true);
@@ -226,7 +229,7 @@ export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
                       onEdit={() => openCohortEdit(n)} onRemove={() => removeCohort(n)}
                       split={(done: () => void) => <SplitForm cohort={n} attrs={catalogAttrs()} busy={busy} onSplit={splitCohortBy} onDone={done} />}
                       splitCount={splits.length}
-                      save={toSave && { onSave: () => saveCohortToLibrary(n), label: toSave.action === "create" ? "save to library" : "save changes to library",
+                      save={toSave && { onSave: async () => setSavingToLibrary(n), label: toSave.action === "create" ? "save to library…" : "save changes to library…",
                         title: toSave.action === "create" ? "save “" + toSave.as + "” to your library, to add it to other analyses"
                           : "write this cohort's definition and splits over “" + toSave.as + "” in your library" }}
                       lock={{ locked: !!doc.cohorts?.[n]?.lock, onLock: async () => { if (canSave()) await lockCohorts([n]); }, onUnlock: () => unlockCohort(n) }}
@@ -247,25 +250,25 @@ export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
                         {views.length ? "in " + views.join(", ") : "in no view"}
                       </span>
                       {src && <button className={"srcbadge" + (src.state === "changed" ? " changed" : "")} aria-expanded={open} onClick={toggle}
-                        title={src.state === "changed" ? "the saved cohort “" + src.srcName + "” has changed since this copy was made — open to compare and update"
-                          : src.state === "deleted" ? "copied from a saved cohort “" + src.from.name + "” that has since been deleted"
-                          : "copied from the saved cohort “" + src.from.name + "”"}>
-                        {src.state === "changed" ? "saved version changed" : src.state === "deleted" ? "source deleted" : "#" + shortHash(src.from.hash)}</button>}
+                        title={src.state === "changed" ? "your saved cohort “" + src.srcName + "” has changed since this one was linked to it — open to compare and update"
+                          : src.state === "deleted" ? "linked to a saved cohort “" + src.from.name + "” that has since been deleted"
+                          : "linked to your saved cohort “" + (src.srcName || src.from.name) + "” (#" + shortHash(src.from.hash) + ") — open for details"}>
+                        {src.state === "changed" ? "saved version changed" : src.state === "deleted" ? "source deleted" : "in library"}</button>}
                     </div>
                     {open && src && (
                       <div className="cohortsrc meta">
-                        <span>Copied from saved cohort <strong>“{src.from.name}”</strong>{src.from.savedAt ? " (saved " + src.from.savedAt + ")" : ""}
+                        <span>Linked to your saved cohort <strong>“{src.from.name}”</strong>{src.from.savedAt ? " (saved " + src.from.savedAt + ")" : ""}
                           {" "}· definition <code title={src.from.hash}>#{shortHash(src.from.hash)}</code>.</span>
                         {src.state === "unknown" && <span> {loggedIn ? "Checking the saved cohort…" : "Sign in to compare it with the saved cohort."}</span>}
-                        {src.state === "deleted" && <span> That saved cohort has since been deleted; this copy is unaffected.</span>}
+                        {src.state === "deleted" && <span> That saved cohort has since been deleted; this one is unaffected.</span>}
                         {(src.state === "current" || src.state === "changed") && src.srcName !== src.from.name && <span> It is now named “{src.srcName}”.</span>}
                         {src.state === "current" && !src.edited && <span> The saved cohort is unchanged.</span>}
-                        {src.edited && <span> This copy has been edited here since (now <code>#{shortHash(cohortHash(doc.cohorts![n]))}</code>).</span>}
+                        {src.edited && <span> This one has been edited here since (now <code>#{shortHash(cohortHash(doc.cohorts![n]))}</code>).</span>}
                         {src.state === "changed" && <span className="cohortsrc-changed"> The saved cohort has changed since (now <code title={src.now}>#{shortHash(src.now!)}</code>, saved {src.src!.savedAt}).</span>}
                         {(src.state === "changed" || (src.state === "current" && src.edited)) && <>
                           {src.state === "changed" && <div className="cohortsrc-new"><span className="meta">The saved version:</span> <CohortPills def={src.src!.def} /></div>}
                           <Button variant="outline" size="sm" className="h-ctl" disabled={busy} onClick={() => updateFromSaved(n)}
-                            title={"replace this copy's definition with the saved cohort's; every view drawing “" + n + "” re-runs"}>
+                            title={"replace this cohort's definition with the saved cohort's; every view drawing “" + n + "” re-runs"}>
                             {src.state === "changed" ? "Update to the saved version" : "Revert to the saved version"}</Button>
                         </>}
                       </div>
@@ -285,6 +288,11 @@ export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
           <AnalysisSources sources={result?.sources} names={studyNames} />
         </section>
       )}
+      {savingToLibrary && (() => {
+        const st = cohortSaveState(savingToLibrary);
+        return st && <SaveToLibraryDialog cohort={savingToLibrary} initial={st.as} updates={st.action === "update" ? st.as : null}
+          taken={Object.keys(saved)} onSave={(as) => saveCohortToLibrary(savingToLibrary, as)} onClose={() => setSavingToLibrary(null)} />;
+      })()}
     </div>
   </>;
 }
diff --git a/app/lab/dialogs.tsx b/app/lab/dialogs.tsx
index 38b03074..a2c32c6e 100644
--- a/app/lab/dialogs.tsx
+++ b/app/lab/dialogs.tsx
@@ -64,6 +64,40 @@ export function SaveCohortDialog({ initial, meta, onSave, onClose }: {
   );
 }
 
+/**
+ * A cohort card's "save to library…": the name it is saved under, prefilled with the library name it
+ * would take. Says what saving does — a new saved cohort, the one it came from updated, or another
+ * saved cohort of that name replaced — before it is done.
+ */
+export function SaveToLibraryDialog({ cohort, initial, updates, taken, onSave, onClose }: {
+  /** the cohort's name in this analysis */
+  cohort: string;
+  initial: string;
+  /** the saved cohort this one would update when saved under its name, if any */
+  updates: string | null;
+  /** the names of the reader's saved cohorts */
+  taken: string[];
+  onSave: (name: string) => Promise<void>;
+  onClose: () => void;
+}) {
+  const [name, setName] = useState(initial);
+  const [busy, setBusy] = useState(false);
+  const n = name.trim();
+  const replaces = !!n && n !== updates && taken.includes(n);
+  const what = !n ? "" : n === updates ? "Updates your saved cohort “" + n + "” with this definition."
+    : replaces ? "You already have a saved cohort named “" + n + "”: saving replaces it with this one."
+    : "Saves a new cohort “" + n + "” to your library.";
+  return (
+    <FormDialog className="savelibrarydialog" title={"Save “" + cohort + "” to your library"} onClose={onClose}
+      onSubmit={async () => { if (!n || busy) return; setBusy(true); try { await onSave(n); onClose(); } finally { setBusy(false); } }}
+      footer={<CancelSave onClose={onClose} disabled={!n || busy} label={busy ? "Saving…" : replaces ? "Replace" : "Save"} />}>
+      <Label className={META} htmlFor="savelibraryname">Name in your library</Label>
+      <Input id="savelibraryname" className={FIELD} value={name} onChange={(e) => setName(e.target.value)} autoFocus placeholder="cohort name…" />
+      <p className={cn(META, "m-0", replaces && "text-destructive")}>{what}</p>
+    </FormDialog>
+  );
+}
+
 /** Explore's "Save as feature": the name of the yes/no attribute the current filters become. */
 export function SaveFeatureDialog({ initial, meta, onSave, onClose }: {
   initial: string; meta: string; onSave: (name: string) => void; onClose: () => void;
diff --git a/app/lab/use-cohort-edits.ts b/app/lab/use-cohort-edits.ts
index 56f452b1..19a8a1fa 100644
--- a/app/lab/use-cohort-edits.ts
+++ b/app/lab/use-cohort-edits.ts
@@ -138,7 +138,7 @@ export function useCohortEdits(page: CohortEditsPage) {
    * is nothing to save, or while the saved cohorts are not known (logged out, loading). A cohort
    * copied from a saved one saves back over it once edited here or re-split; one whose saved
    * version has changed since is not offered, since saving would discard that change. A cohort
-   * with no source matches a saved cohort by name.
+   * with no source is saved as a new one.
    */
   const cohortSaveState = (name: string): CohortSaveState | null => {
     const def = doc.cohorts?.[name];
@@ -149,25 +149,44 @@ export function useCohortEdits(page: CohortEditsPage) {
       if (s.state !== "current") return null;
       return s.edited || canonicalSplits(def) !== canonicalSplits(s.src!.def) ? { action: "update", id: s.src!.id, as: s.srcName! } : null;
     }
+    // Not copied from a saved cohort: saving makes a new one. A saved cohort that only shares its
+    // name (default names repeat: "selection", "from Cell Explorer") is not this one's earlier
+    // version; the save dialog says so and offers to replace it. One identical to it is already saved.
     const same = saved[name];
-    if (!same) return { action: "create", as: name };
-    return cohortHash(def) !== cohortHash(same.def) || canonicalSplits(def) !== canonicalSplits(same.def)
-      ? { action: "update", id: same.id, as: name } : null;
+    if (same && cohortHash(def) === cohortHash(same.def) && canonicalSplits(def) === canonicalSplits(same.def)) return null;
+    return { action: "create", as: name };
   };
-  /** Save a cohort to the library (cohortSaveState says where); the analysis's copy then names it as its source. */
-  const saveCohortToLibrary = async (name: string) => {
+  /**
+   * Save a cohort to the library under `as` (default: where cohortSaveState says): over the saved
+   * cohort it would update when `as` is that one's name, over another saved cohort already named
+   * `as`, else as a new one. The analysis's copy then names it as its source.
+   */
+  const saveCohortToLibrary = async (name: string, as?: string) => {
     const st = cohortSaveState(name);
     const cur = doc.cohorts?.[name];
     if (!st || !cur) return;
     const { from: _from, ...def } = cur;
+    const target = as ?? st.as;
+    const id = target === st.as ? st.id : saved[target]?.id;
     try {
-      const c = await persist(st.as, def, evalOf(name), st.id);
+      const c = await persist(target, def, evalOf(name), id);
       const now = docs.current.doc;
       if (now.cohorts?.[name]) {
-        // bookkeeping after a save, not an edit the reader would undo. What was saved may differ from
-        // what was asked by its id lists, now stored as sets: the copy takes those too.
+        // What was saved may differ from what was asked by its id lists, now stored as sets: the
+        // copy takes those too, and names the saved cohort as its source.
         const kept = cohortHash(c.def) === cohortHash(def) ? now.cohorts[name] : { ...c.def };
-        docs.set({ ...now, cohorts: { ...now.cohorts, [name]: { ...kept, from: { saved: c.id, name: st.as, hash: cohortHash(c.def), savedAt: c.savedAt } } } }, { undoable: false });
+        const linked: CohortDef = { ...kept, from: { saved: c.id, name: target, hash: cohortHash(c.def), savedAt: c.savedAt } };
+        // Saved under another name, the cohort takes that name here too (as "edit…" renames it,
+        // views drawing it included) — unless the analysis already has a cohort of that name.
+        const rename = target !== name && !now.cohorts[target];
+        if (!rename) {
+          // bookkeeping after a save, not an edit the reader would undo
+          docs.set({ ...now, cohorts: { ...now.cohorts, [name]: linked } }, { undoable: false });
+          if (target !== name) setToast("saved to your library as “" + target + "”; this analysis already has a cohort named that, so this one keeps the name “" + name + "”");
+        } else {
+          const cohorts = Object.fromEntries(Object.entries(now.cohorts).map(([k, v]) => k === name ? [target, linked] : [k, v]));
+          docs.set({ ...now, cohorts, views: renameInViews(now.views, name, target) as AnalysisDoc["views"] });
+        }
       }
     } catch (e: any) {
       setError("could not save \u201c" + name + "\u201d: " + (e?.message || e));
diff --git a/app/lab/view-chrome.tsx b/app/lab/view-chrome.tsx
index 78333ce9..6a1ae1b7 100644
--- a/app/lab/view-chrome.tsx
+++ b/app/lab/view-chrome.tsx
@@ -614,7 +614,7 @@ export function CohortEditMenu({ busy, canEdit, onEdit, onRemove, split, splitCo
   /** the single-cell dataset this cohort's patients can be opened in, when its study has one */
   cells?: { label: string } | null;
   onCells?: () => Promise<void>;
-  /** saving the cohort to the library, offered only while it has something to save */
+  /** saving the cohort to the library (opening its naming dialog), offered only while it has something to save */
   save?: { onSave: () => Promise<void>; label: string; title: string } | null;
   /** the split form; `done` closes this menu. A cohort may have several splits — each view draws one */
   split?: (done: () => void) => React.ReactNode;
@@ -631,7 +631,7 @@ export function CohortEditMenu({ busy, canEdit, onEdit, onRemove, split, splitCo
       {(close) => <>
         {save && !splitting && <>
           <MenuItem disabled={busy || saving} title={save.title}
-            onClick={async () => { setSaving(true); try { await save.onSave(); } finally { setSaving(false); } }}>
+            onClick={async () => { setSaving(true); try { await save.onSave(); close(); } finally { setSaving(false); } }}>
             <Save />{save.label}{saving && <span className="spinner ml-1.5" />}</MenuItem>
           <MenuSeparator />
         </>}
diff --git a/e2e.cjs b/e2e.cjs
index 82b7bb87..cde42149 100644
--- a/e2e.cjs
+++ b/e2e.cjs
@@ -40,6 +40,16 @@ async function main() {
   // development sign-in and passes the email to sign in as here; signed out, the store must refuse.
   const LOGIN = process.env.E2E_LOGIN_EMAIL || "";
   const signIn = (ctx, email = LOGIN) => ctx.request.post(BASE + "/api/auth/dev", { data: { email } });
+  /** a cohort card's "save to library…" dialog: optionally rename, then save; answers what it said saving does */
+  const saveToLibraryDialog = async (p, as) => {
+    const dlg = p.locator("[role=dialog].savelibrarydialog");
+    await dlg.waitFor({ timeout: 30000 });
+    if (as != null) await dlg.locator("#savelibraryname").fill(as);
+    const said = (await dlg.locator("p").last().innerText()).trim();
+    await dlg.locator("button[type=submit]").click();
+    await dlg.waitFor({ state: "detached", timeout: 60000 });
+    return said;
+  };
   {
     const anon = await browser.newContext();
     const r = await anon.request.get(BASE + "/api/artifacts?kind=cohort");
@@ -1521,7 +1531,8 @@ async function main() {
         if ((await gear.getAttribute("data-state")) !== "open") await gear.click();
         await sp.locator("[data-slot=popover-content]").getByRole("button", { name: label, exact: true }).click();
       };
-      await save("save to library");
+      await save("save to library…");
+      await saveToLibraryDialog(sp);
       await sp.waitForFunction((n) => { try { return !!JSON.parse(document.querySelector("#docjson").value).cohorts[n].from; } catch { return false; } }, name, { timeout: 60000 });
       const art = ((await (await ctx.request.get(BASE + "/api/artifacts?kind=cohort")).json()).artifacts || []).find((a) => a.name === name);
       const savedLeaf = art?.definition?.all?.[0] || {};
@@ -1608,30 +1619,51 @@ async function main() {
       };
       const savedDef = async () => {
         const j = await (await ctx.request.get(BASE + "/api/artifacts?kind=cohort")).json();
-        return (j.artifacts || []).find((a) => a.name === name);
+        return (j.artifacts || []).find((a) => a.name === libName);
       };
+      // saved under a name of the reader's choosing, not necessarily the analysis's
+      const libName = name + " (library)";
       await open({ dsl: "2.5", study: "msk_chord_2024", cohorts: { [name]: { all: [{ kind: "oql", q: "KRAS: MUT" }] } }, views: [{ kind: "survival", cohorts: [name] }] });
       let m = await menuItems();
-      steps.offered = m.items.some((t) => t.trim() === "save to library");
-      await sp.locator("[data-slot=popover-content]").getByRole("button", { name: "save to library", exact: true }).click();
-      await sp.waitForFunction((n) => { try { return !!JSON.parse(document.querySelector("#docjson").value).cohorts[n].from; } catch { return false; } }, name, { timeout: 60000 });
+      steps.offered = m.items.some((t) => t.trim() === "save to library…");
+      await sp.locator("[data-slot=popover-content]").getByRole("button", { name: "save to library…", exact: true }).click();
+      steps.said = /Saves a new cohort/.test(await saveToLibraryDialog(sp, libName));
+      // saved under another name, the cohort takes it in the analysis too, its view following
+      await sp.waitForFunction((n) => { try { return !!JSON.parse(document.querySelector("#docjson").value).cohorts[n].from; } catch { return false; } }, libName, { timeout: 60000 });
       const a1 = await savedDef();
-      steps.saved = !!a1 && (await docOf()).cohorts[name].from.saved === a1.id;
+      const afterSave = await docOf();
+      steps.saved = !!a1 && afterSave.cohorts[libName].from.saved === a1.id && afterSave.cohorts[libName].from.name === libName;
+      steps.renamed = !afterSave.cohorts[name] && afterSave.views[0].cohorts.includes(libName);
+      steps.badge = (await sp.locator(".cohortbox", { hasText: libName }).locator(".srcbadge").innerText()).trim() === "in library";
       m = await menuItems();
       steps.goneAfter = !m.items.some((t) => /^save/.test(t.trim()));
       const d = await docOf();
-      d.cohorts[name].splits = { sex: { arms: [{ name: "Female", where: { kind: "clinical", attribute: "SEX", values: ["Female"] } }] } };
+      d.cohorts[libName].splits = { sex: { arms: [{ name: "Female", where: { kind: "clinical", attribute: "SEX", values: ["Female"] } }] } };
       await open(d);
       m = await menuItems();
-      steps.offeredAfterSplit = m.items.some((t) => t.trim() === "save changes to library");
-      await sp.locator("[data-slot=popover-content]").getByRole("button", { name: "save changes to library", exact: true }).click();
+      steps.offeredAfterSplit = m.items.some((t) => t.trim() === "save changes to library…");
+      await sp.locator("[data-slot=popover-content]").getByRole("button", { name: "save changes to library…", exact: true }).click();
+      steps.saidUpdate = /Updates your saved cohort/.test(await saveToLibraryDialog(sp));
       for (let i = 0; i < 60 && !(await savedDef())?.definition?.splits; i++) await sp.waitForTimeout(1000);
       const a2 = await savedDef();
       steps.splitSaved = !!a2 && a2.id === a1.id && !!a2.definition.splits?.sex && !a2.definition.from;
+      // a different cohort that only shares the saved one's name is not its earlier version: it is
+      // offered as a new save, and the dialog warns that saving under that name replaces the other
+      await open({ dsl: "2.8", study: "msk_chord_2024", cohorts: { [libName]: { all: [{ kind: "oql", q: "EGFR: MUT" }] } }, views: [{ kind: "survival", cohorts: [libName] }] });
+      const gear2 = sp.locator(".cohortbox", { hasText: libName }).locator(".cohortgear");
+      await gear2.click();
+      const items2 = await sp.locator("[data-slot=popover-content]").getByRole("button").allInnerTexts();
+      steps.sameNameIsNew = items2.some((t) => t.trim() === "save to library…") && !items2.some((t) => /save changes/.test(t));
+      await sp.locator("[data-slot=popover-content]").getByRole("button", { name: "save to library…", exact: true }).click();
+      const dlg = sp.locator("[role=dialog].savelibrarydialog");
+      await dlg.waitFor({ timeout: 30000 });
+      steps.warnsReplace = /already have a saved cohort/.test(await dlg.locator("p").last().innerText()) && (await dlg.locator("button[type=submit]").innerText()).trim() === "Replace";
+      await dlg.getByRole("button", { name: "Cancel" }).click();
       await ctx.request.delete(BASE + "/api/artifacts/" + a1.id);
     } catch (e) { steps.error = String(e.message || e).slice(0, 160); }
-    ok("a cohort that is unsaved, or re-split since saving, offers save in its menu, and saving records it as the source",
-      steps.offered && steps.saved && steps.goneAfter && steps.offeredAfterSplit && steps.splitSaved, JSON.stringify(steps));
+    ok("a cohort that is unsaved, or re-split since saving, offers save in its menu; saving asks for its library name, takes that name in the analysis and records it as the source",
+      steps.offered && steps.said && steps.saved && steps.renamed && steps.badge && steps.goneAfter && steps.offeredAfterSplit && steps.saidUpdate && steps.splitSaved
+        && steps.sameNameIsNew && steps.warnsReplace, JSON.stringify(steps));
     await ctx.close();
   }
   // The study picker STAGES. Ticking boxes must not query: assembling a

From a455c188efa00e6f4f7ff5ad0433c56e65d3d354 Mon Sep 17 00:00:00 2001
From: Aaron Lisman <lisman.aaron@gmail.com>
Date: Mon, 19 Oct 2026 00:05:37 +0000
Subject: [PATCH 5/7] A cohort saved to the library names its study

A cohort with no `study`/`studies` runs in its analysis's study. Saved to
the library like that, it would silently take the study of whatever analysis
it joined next ("EP300 mutant in MSK-CHORD" becoming "EP300 mutant in
GENIE"). The page's persist, which every cohort save goes through (a cohort's
card, Explore, a library example, the assistant's save), now pins such a
cohort to the study it was running in: the analysis's, or for a template its
parameter's current value. The analysis's copy takes the same definition, so
it stays "in library", not "changed". Saved analyses are untouched, so
templates (`"study": "$study"`) keep working.

Verified: the e2e save check asserts a cohort with no study is saved naming
msk_chord_2024, the analysis's study, and the analysis's copy names it too.
Gate (GATE_PORT=4111 scripts/gate.sh) passes: 256 e2e checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvdfHurd9t63GK2ToazMti
---
 app/lab/page.tsx | 14 ++++++++++++--
 e2e.cjs          |  4 +++-
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/app/lab/page.tsx b/app/lab/page.tsx
index 2a589b7a..9737ccef 100644
--- a/app/lab/page.tsx
+++ b/app/lab/page.tsx
@@ -229,8 +229,18 @@ export default function AnalysisPage() {
   const { cohorts: saved, workspaces: spaces, removeWorkspace: removeSpace } = savedArtifacts;
   // What is saved never carries an inline id list: each is stored as an id set first, and the open
   // document is given the same sets, so saving it again stores nothing new (id-sets-client.ts).
-  const persist: typeof savedArtifacts.saveCohort = async (name, def, lastEval, id) =>
-    savedArtifacts.saveCohort(name, await storeCohortLists(def, name), lastEval, id);
+  // A saved cohort names its study: one that inherited the analysis's would, in the library, take
+  // whatever study the next analysis it joins uses. It is pinned to the one it was running in (a
+  // template's, its parameter's current value).
+  const runningStudy = (): string => {
+    const s = doc.study;
+    const v = typeof s === "string" && s.startsWith("$") ? doc.params?.[s.slice(1)] : s;
+    return typeof v === "string" && v ? v : study;
+  };
+  const persist: typeof savedArtifacts.saveCohort = async (name, def, lastEval, id) => {
+    const pinned: CohortDef = def.study || def.studies?.length ? def : { ...def, study: runningStudy() };
+    return savedArtifacts.saveCohort(name, await storeCohortLists(pinned, name), lastEval, id);
+  };
   const withListsStored = async (d: AnalysisDoc): Promise<AnalysisDoc> => {
     const c = await storeDocLists(d);
     // bookkeeping on the way to a save, not an edit the reader would undo
diff --git a/e2e.cjs b/e2e.cjs
index cde42149..603ce511 100644
--- a/e2e.cjs
+++ b/e2e.cjs
@@ -1633,6 +1633,8 @@ async function main() {
       const a1 = await savedDef();
       const afterSave = await docOf();
       steps.saved = !!a1 && afterSave.cohorts[libName].from.saved === a1.id && afterSave.cohorts[libName].from.name === libName;
+      // it named no study (it ran in the analysis's): saved, it names that one, and so does the analysis's copy
+      steps.studyPinned = a1?.definition?.study === "msk_chord_2024" && afterSave.cohorts[libName].study === "msk_chord_2024";
       steps.renamed = !afterSave.cohorts[name] && afterSave.views[0].cohorts.includes(libName);
       steps.badge = (await sp.locator(".cohortbox", { hasText: libName }).locator(".srcbadge").innerText()).trim() === "in library";
       m = await menuItems();
@@ -1662,7 +1664,7 @@ async function main() {
       await ctx.request.delete(BASE + "/api/artifacts/" + a1.id);
     } catch (e) { steps.error = String(e.message || e).slice(0, 160); }
     ok("a cohort that is unsaved, or re-split since saving, offers save in its menu; saving asks for its library name, takes that name in the analysis and records it as the source",
-      steps.offered && steps.said && steps.saved && steps.renamed && steps.badge && steps.goneAfter && steps.offeredAfterSplit && steps.saidUpdate && steps.splitSaved
+      steps.offered && steps.said && steps.saved && steps.studyPinned && steps.renamed && steps.badge && steps.goneAfter && steps.offeredAfterSplit && steps.saidUpdate && steps.splitSaved
         && steps.sameNameIsNew && steps.warnsReplace, JSON.stringify(steps));
     await ctx.close();
   }

From 43522247f1b73478ebea221a3d862be7983d1f14 Mon Sep 17 00:00:00 2001
From: Aaron Lisman <lisman.aaron@gmail.com>
Date: Mon, 19 Oct 2026 14:34:35 +0000
Subject: [PATCH 6/7] A cohort from a list of ids, from the library and the
 cohort panel; example cohorts move to Examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- The paste-ids form is its own component (app/lab/list-cohort.tsx: ListSource,
  ListCohortDialog), used in three places:
  - the Saved tab: "New cohort from a list of ids…" chooses the study (there
    is no analysis to take one from) and saves straight to the library; a name
    already taken gets " (2)", never an overwrite;
  - the analysis's "Cohorts in this analysis" panel: "From a list of ids…"
    adds the cohort before any view exists (the panel now shows with no
    cohorts, saying how to add one);
  - a view's "+ Add cohort", as before.
  A list cohort always names the study it was matched in.
- Example cohorts are only on the Examples page, in a new Cohorts tab (preview,
  analyze, save to library); they are gone from the Saved tab and from
  "+ Add cohort"'s library.
- User-facing text speaks of list cohorts, not stored id sets.

Verified: new e2e check (library: study must be chosen, saved with its set
and study; panel: cohort added with no view; examples only on the Examples
page). e2e-saved.cjs follows the examples to the Examples page. Gate
(GATE_PORT=4111 scripts/gate.sh) passes: 257 e2e checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvdfHurd9t63GK2ToazMti
---
 app/lab/add-cohort-dialog.tsx | 115 +---------------------
 app/lab/analysis-sections.tsx |  23 ++++-
 app/lab/examples-tab.tsx      |  61 +++++++++++-
 app/lab/list-cohort.tsx       | 174 ++++++++++++++++++++++++++++++++++
 app/lab/page.tsx              |  12 ++-
 app/lab/saved-tab.tsx         |  57 +++++------
 app/lab/use-library.ts        |  16 +++-
 e2e-saved.cjs                 |  22 +++--
 e2e.cjs                       |  65 ++++++++++++-
 9 files changed, 377 insertions(+), 168 deletions(-)
 create mode 100644 app/lab/list-cohort.tsx

diff --git a/app/lab/add-cohort-dialog.tsx b/app/lab/add-cohort-dialog.tsx
index 4d6fd27d..d4952cab 100644
--- a/app/lab/add-cohort-dialog.tsx
+++ b/app/lab/add-cohort-dialog.tsx
@@ -1,6 +1,6 @@
 "use client";
 // "+ Add cohort" on a view: one dialog with the places a cohort comes from — the analysis's own
-// cohorts, the library (the login's saved cohorts and the built-in examples), Explore, where a new
+// cohorts, the library (the login's saved cohorts and those shared with them), Explore, where a new
 // one is built and comes back to this view, and a pasted list of ids, saved as a stored id set.
 import { useEffect, useState } from "react";
 import { Plus } from "lucide-react";
@@ -13,9 +13,9 @@ import { Dialog, DialogContent, DialogHeader, DialogTitle } from "../_ui/dialog"
 import { Input } from "../_ui/input";
 import { Tabs, TabsList, TabsTrigger } from "../_ui/tabs";
 import { TB } from "../_ui/toolbar.ts";
-import { cn } from "../../lib/cn";
 import { Textarea } from "../_ui/textarea";
 import { api } from "./api.ts";
+import { ListSource, addLabel, type SignInState } from "./list-cohort.tsx";
 import type { CellExplorerDataset } from "../../lib/cell-explorer.ts";
 
 export interface AddCohortTarget {
@@ -30,11 +30,10 @@ export interface AddCohortTarget {
 
 export interface LibraryState {
   /** saved cohorts are the signed-in reader's: "locked" when signed out, "off" where there is no sign-in */
-  saved: "off" | "locked" | "loading" | "ready" | "error";
+  saved: SignInState;
   savedError?: string | null;
   /** the login's saved cohorts: `id` is the artifact's, which survives a rename */
   cohorts: { id: string; name: string; def: CohortDef; savedAt: string }[];
-  examples: { name: string; desc: string; def: CohortDef }[];
 }
 
 type Source = "analysis" | "library" | "explore" | "list" | "cells";
@@ -97,7 +96,6 @@ export function AddCohortDialog({ target, analysis, library, studies, storeLists
     );
   };
   const saved = library.cohorts.filter((c) => match(c.name));
-  const examples = library.examples.filter((c) => match(c.name) || match(c.desc));
 
   return (
     <Dialog open={!!target} onOpenChange={(open) => { if (!open) onClose(); }}>
@@ -144,7 +142,6 @@ export function AddCohortDialog({ target, analysis, library, studies, storeLists
 
         {source === "library" && <>
           <Input className="h-8 text-md md:text-md" placeholder="search the library…" value={q} onChange={(e) => setQ(e.target.value)} autoFocus />
-          <h4 className="acd-h">Your saved cohorts</h4>
           {library.saved === "off" ? <p className="note">This deployment has no sign-in, so it keeps no saved cohorts.</p>
             : library.saved === "locked" ? <p className="note"><Button variant="link" size="inline" className="text-md" onClick={onLogin}>Sign in</Button> to see your saved cohorts.</p>
             : library.saved === "loading" ? <p className="note"><span className="spinner" /> loading your saved cohorts…</p>
@@ -152,9 +149,6 @@ export function AddCohortDialog({ target, analysis, library, studies, storeLists
             : !library.cohorts.length ? <p className="note">You have no saved cohorts yet — save one from Explore (“Save as a cohort”).</p>
             : !saved.length ? <p className="note">No saved cohort matches “{q}”.</p>
             : <ul className="acd-list">{saved.map((c) => libraryRow(c.name, c.def, "saved " + c.savedAt, { id: c.id, savedAt: c.savedAt }))}</ul>}
-          <h4 className="acd-h">Examples</h4>
-          {examples.length ? <ul className="acd-list">{examples.map((c) => libraryRow(c.name, c.def, c.desc))}</ul>
-            : <p className="note">No example matches “{q}”.</p>}
         </>}
 
         {source === "explore" && (
@@ -166,8 +160,8 @@ export function AddCohortDialog({ target, analysis, library, studies, storeLists
             <Button disabled={full} title={full ? addTitle("") : undefined} onClick={onExplore}>Open Explore</Button>
           </div>
         )}
-        {source === "list" && <ListSource studies={studies} saved={library.saved} full={full} replaces={replaces} addTitle={addTitle}
-          nameFor={libraryName} onAdd={onAdd} onLogin={onLogin} />}
+        {source === "list" && <ListSource studies={studies} saved={library.saved} disabled={full} doneTitle={(as) => addTitle("“" + as + "”")}
+          doneLabel={addLabel(replaces)} nameFor={libraryName} onDone={(as, def) => onAdd(as, def)} onLogin={onLogin} />}
         {source === "cells" && cells && <CellsSource cells={cells} full={full} replaces={replaces} addTitle={addTitle}
           nameFor={libraryName} storeLists={storeLists} onAdd={onAdd} />}
       </DialogContent>}
@@ -242,102 +236,3 @@ function CellsSource({ cells, full, replaces, addTitle, nameFor, storeLists, onA
     </div>
   );
 }
-
-/** One id per line, or separated by commas, semicolons, tabs or spaces. */
-const splitIds = (text: string): string[] => text.split(/[\s,;]+/).map((x) => x.trim()).filter(Boolean);
-
-interface SavedSet {
-  set: { id: string; name: string; level: "sample" | "patient"; studies: string[]; count: number };
-  unmatched: number; unmatchedExamples: string[]; duplicates: number; multiStudy: number;
-  refused: { study: string; reason: string }[];
-}
-
-/**
- * A cohort from a pasted list of sample or patient ids. The list is matched to the studies' own
- * cases and saved on the server as a stored id set (lib/id-set-store.ts); the cohort names the
- * set by its id, so the document and its link stay small however long the list is. Needs a
- * sign-in, since the set is its saver's. The text stays in this component while it is typed.
- */
-function ListSource({ studies, saved, full, replaces, addTitle, nameFor, onAdd, onLogin }: {
-  studies: string[]; saved: LibraryState["saved"]; full: boolean; replaces: boolean; addTitle: (what: string) => string;
-  nameFor: (name: string, def: CohortDef) => string; onAdd: (name: string, def?: CohortDef) => void; onLogin: () => void;
-}) {
-  const [text, setText] = useState("");
-  const [level, setLevel] = useState<"sample" | "patient">("sample");
-  // no default: a list's name is how it is found again, in the analysis and the library
-  const [name, setName] = useState("");
-  const [busy, setBusy] = useState(false);
-  const [err, setErr] = useState<string | null>(null);
-  const [done, setDone] = useState<SavedSet | null>(null);
-  if (saved === "off") return <p className="note">A list of ids is kept on the server as a stored id set, which needs a sign-in, and this deployment has none.</p>;
-  if (saved === "locked") return <p className="note"><Button variant="link" size="inline" className="text-md" onClick={onLogin}>Sign in</Button> to add a cohort from a list of ids: the list is kept on the server as your stored id set.</p>;
-  const ids = splitIds(text);
-  const save = async () => {
-    setBusy(true); setErr(null); setDone(null);
-    try {
-      const res = await api.idSets.create({ name: name.trim(), level, studies, ids });
-      const j = await res.json();
-      if (!res.ok || j.error) throw new Error(j.error || res.statusText);
-      setDone(j);
-    } catch (e) { setErr(String((e as Error)?.message || e)); }
-    finally { setBusy(false); }
-  };
-  const def: CohortDef | null = done ? {
-    all: [{ kind: done.set.level === "sample" ? "sampleList" : "patientList", set: done.set.id, label: done.set.name, n: done.set.count }],
-    ...(done.set.studies.length > 1 ? { studies: done.set.studies } : done.set.studies[0] !== studies[0] ? { study: done.set.studies[0] } : {}),
-  } : null;
-  const as = def ? nameFor(done!.set.name, def) : name.trim();
-  const noun = level === "sample" ? "sample" : "patient";
-  return (
-    <div className="acd-list-ids flex flex-col gap-2.5">
-      <p className="note mt-0">
-        Paste {noun} ids, one per line or separated by commas or spaces, as <code>study:id</code> or bare ids, which are looked
-        up in {studies.length ? studies.join(", ") : "the analysis's study"}. The ids are matched to the {noun}s there and kept on
-        the server as a stored id set; the cohort names the set, so the analysis and its links stay small however long the list is.
-      </p>
-      <div className="viewtb">
-        <div className="tbz">
-          <span className="tbl">ids are</span>
-          <Tabs value={level} onValueChange={(v) => { setLevel(v as "sample" | "patient"); setDone(null); }}>
-            <TabsList className="h-ctl">
-              <TabsTrigger value="sample" className="px-2.5 text-md">samples</TabsTrigger>
-              <TabsTrigger value="patient" className="px-2.5 text-md">patients</TabsTrigger>
-            </TabsList>
-          </Tabs>
-        </div>
-      </div>
-      <Textarea aria-label={noun + " ids"} rows={6} className="font-mono text-md md:text-md" value={text}
-        placeholder={level === "sample" ? "P-0000012-T01-IM3\nP-0000015-T01-IM3\n…" : "P-0000012\nP-0000015\n…"}
-        onChange={(e) => { setText(e.target.value); setDone(null); }} />
-      <div className="viewtb">
-        <div className="tbz">
-          <label className="tbfield">name <Input aria-label="set name" className="h-ctl w-56 text-md md:text-md" value={name} placeholder="name this list…"
-            onChange={(e) => { setName(e.target.value); setDone(null); }} /></label>
-          <Button variant="outline" size="sm" className={cn(TB, "idsetsave")} disabled={busy || !ids.length || !studies.length || !name.trim()}
-            title={!studies.length ? "the analysis names no study to match the ids in" : !ids.length ? "paste some ids first"
-              : !name.trim() ? "name the list first: it is how it is found again, in the analysis and your library" : undefined}
-            onClick={() => void save()}>
-            {busy && <span className="spinner" />}Match and save {ids.length ? ids.length.toLocaleString() + " id" + (ids.length === 1 ? "" : "s") : ""}</Button>
-        </div>
-      </div>
-      {err && <p className="error m-0">{err}</p>}
-      {done && def && <>
-        <p className="note m-0 idsetresult">
-          Saved “{done.set.name}”: <strong>{done.set.count.toLocaleString()}</strong> {noun}{done.set.count === 1 ? "" : "s"}
-          {done.set.studies.length > 1 ? " across " + done.set.studies.length + " studies" : " in " + done.set.studies[0]}
-          {done.unmatched > 0 && <> · <span className="text-destructive">{done.unmatched.toLocaleString()} matched no {noun}</span>: {done.unmatchedExamples.slice(0, 5).join(", ")}{done.unmatched > 5 ? ", …" : ""}</>}
-          {done.duplicates > 0 && <> · {done.duplicates.toLocaleString()} given more than once</>}
-          {done.multiStudy > 0 && <> · {done.multiStudy.toLocaleString()} found in more than one study, kept in each</>}
-          {done.refused.length > 0 && <> · not matched in {done.refused.map((r) => r.study + " (" + r.reason + ")").join(", ")}</>}
-        </p>
-        <div className="viewtb">
-          <div className="tbz">
-            <Button variant="outline" size="sm" className={TB} disabled={full} title={addTitle("“" + as + "”")}
-              onClick={() => onAdd(as, def)}>{replaces ? "Use" : <><Plus />Add</>}</Button>
-          </div>
-        </div>
-        {as !== done.set.name && <p className="meta m-0">added as “{as}”, since this analysis already has a different “{done.set.name}”</p>}
-      </>}
-    </div>
-  );
-}
diff --git a/app/lab/analysis-sections.tsx b/app/lab/analysis-sections.tsx
index ef764355..19129d44 100644
--- a/app/lab/analysis-sections.tsx
+++ b/app/lab/analysis-sections.tsx
@@ -12,6 +12,7 @@ import { CHIP } from "../_ui/toolbar.ts";
 import { cn } from "../../lib/cn";
 import { TB } from "../_ui/toolbar.ts";
 import { SaveToLibraryDialog } from "./dialogs.tsx";
+import { ListCohortDialog, type SignInState } from "./list-cohort.tsx";
 import { Dialog, DialogClose, DialogContent, DialogFooter, DialogHeader, DialogTitle } from "../_ui/dialog";
 import { Textarea } from "../_ui/textarea";
 import CohortPills from "./pills";
@@ -71,6 +72,10 @@ export interface AnalysisCtx {
   unlockAll: () => void;
   /** whether the reader may store id sets (signed in); asks them to sign in when not */
   canSave: () => boolean;
+  signIn: SignInState;
+  requestLogin: () => void;
+  /** the studies the analysis uses: a pasted bare id is looked up in each */
+  analysisStudies: () => string[];
   /** the single-cell dataset a cohort's patients can be opened in (lib/cell-explorer.ts), and opening it */
   cohortCells: (name: string) => import("../../lib/cell-explorer.ts").CellExplorerDataset | null;
   openCohortCells: (name: string) => Promise<void>;
@@ -168,10 +173,13 @@ function EmptyViewCard({ ctx, vi }: { ctx: AnalysisCtx; vi: number }) {
 }
 
 export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
-  const { busy, canSave, saved, catalogAttrs, cohortCells, cohortSaveState, cohortSource, doc, lockCohorts, openCohortCells, loggedIn, menuOpenRef, openCohortEdit, removeCohort, removePartitionNamed, renamePartitionRow, result, saveCohortToLibrary, setPartitionDef, setUpgradeNote, showClauseData, spaces, splitCohortBy, splitsFlat, studyNames, unlockAll, unlockCohort, updateFromSaved, upgradeNote, viewTitle } = ctx;
+  const { busy, canSave, saved, signIn, requestLogin, analysisStudies, docs, catalogAttrs, cohortCells, cohortSaveState, cohortSource, doc, lockCohorts, openCohortCells, loggedIn, menuOpenRef, openCohortEdit, removeCohort, removePartitionNamed, renamePartitionRow, result, saveCohortToLibrary, setPartitionDef, setUpgradeNote, showClauseData, spaces, splitCohortBy, splitsFlat, studyNames, unlockAll, unlockCohort, updateFromSaved, upgradeNote, viewTitle } = ctx;
   const [lockingAll, setLockingAll] = useState(false);
   /** the cohort whose "save to library…" dialog is open */
   const [savingToLibrary, setSavingToLibrary] = useState<string | null>(null);
+  const [fromList, setFromList] = useState(false);
+  /** a pasted list's cohort joins the analysis under its name, or the next free one */
+  const freeName = (n: string) => { const have = docs.current.doc.cohorts || {}; if (!have[n]) return n; for (let i = 2; ; i++) if (!have[n + " (" + i + ")"]) return n + " (" + i + ")"; };
   const lockAll = async () => {
     if (!canSave()) return;
     setLockingAll(true);
@@ -195,11 +203,14 @@ export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
       {/* The analysis's cohorts are not its top level: each view names the ones it draws, and these
           cards summarise them — each with the views that draw it and the saved cohort it was copied
           from. Cohorts come in through a view's "+ Add cohort". */}
-      {names.length > 0 && (
+      {(names.length > 0 || doc.study) && (
         <section className="cohortsum" aria-label="cohorts in this analysis">
           <h2 className="vtitle flex items-center gap-2.5 mb-4">
             Cohorts in this analysis <span className="plain meta">— add one from a view</span>{busy && <span className="spinner" />}
-            <span className="analysislock ml-auto flex items-center gap-2 text-sm font-normal normal-case tracking-normal">
+            <span className="ml-auto flex items-center gap-2 text-sm font-normal normal-case tracking-normal">
+            <Button variant="outline" size="sm" className={cn(TB, "fromlist")} disabled={busy} onClick={() => setFromList(true)}
+              title="add a cohort made from a pasted list of sample or patient ids to this analysis"><Plus />From a list of ids…</Button>
+            {names.length > 0 && <span className="analysislock flex items-center gap-2">
               {doc.locked
                 ? <>
                     <span className="inline-flex items-center gap-1 text-muted-foreground" title={"every cohort, and its split arms, frozen at once to the patients it selected then" +
@@ -211,8 +222,10 @@ export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
                 : <Button variant="outline" size="sm" className={cn(TB, "lockall")} disabled={busy || lockingAll} onClick={() => void lockAll()}
                     title="freeze every cohort, and its split arms, at this moment to the patients it selects now, so the analysis stays the same as patients are added to the data">
                     {lockingAll ? <span className="spinner" /> : <Lock />}Lock all cohorts</Button>}
+            </span>}
             </span>
           </h2>
+          {!names.length && <p className="note mt-0">No cohorts yet: add one to a view with its “+ Add cohort”, or make one from a list of ids.</p>}
           <div className="cohortlist">
             {names.map((n, i) => {
               const c = result?.cohorts[n];
@@ -288,6 +301,10 @@ export function CohortColumn({ ctx }: { ctx: AnalysisCtx }) {
           <AnalysisSources sources={result?.sources} names={studyNames} />
         </section>
       )}
+      {fromList && <ListCohortDialog title="Add a cohort from a list of ids" studies={analysisStudies()} saved={signIn}
+        doneLabel={<><Plus />Add to the analysis</>} doneTitle={(as) => "add “" + as + "” to this analysis; it is in no view until you add it to one"}
+        nameFor={freeName} onLogin={requestLogin} onClose={() => setFromList(false)}
+        onDone={async (as, def) => { const now = docs.current.doc; docs.set({ ...now, cohorts: { ...now.cohorts, [as]: def } }); }} />}
       {savingToLibrary && (() => {
         const st = cohortSaveState(savingToLibrary);
         return st && <SaveToLibraryDialog cohort={savingToLibrary} initial={st.as} updates={st.action === "update" ? st.as : null}
diff --git a/app/lab/examples-tab.tsx b/app/lab/examples-tab.tsx
index 013d7f43..80e99fea 100644
--- a/app/lab/examples-tab.tsx
+++ b/app/lab/examples-tab.tsx
@@ -15,6 +15,9 @@ import { cn } from "../../lib/cn";
 import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "../_ui/dialog";
 import { usePublicEnv } from "../_env/public-env-context.tsx";
 import { parseExamplesUrl } from "../../lib/site.ts";
+import type { CohortDef } from "../../lib/types.ts";
+import { Tabs, TabsList, TabsTrigger } from "../_ui/tabs";
+import CohortPills from "./pills";
 
 /** a tag filter: an outline chip, filled while it is the one shown */
 const TAG = "group rounded-pill px-2.5 text-sm font-normal aria-pressed:border-link aria-pressed:bg-link aria-pressed:text-card aria-pressed:hover:bg-link/90 aria-pressed:hover:text-card";
@@ -35,7 +38,16 @@ export function useExamplesUrl(): { examplesUrl: string | null; examplesUrlError
   catch (e) { return { examplesUrl: null, examplesUrlError: String((e as Error)?.message || e) }; }
 }
 
-export function ExamplesTab({ tag, onTag, query, onQuery, busy, onRun, link, elsewhere, elsewhereError, onError }: {
+/** An example cohort: a definition to preview, analyse or save, one per kind of clause. */
+export type ExampleCohort = { name: string; desc: string; def: CohortDef };
+export type ExampleEval = { count?: number; error?: string; busy?: boolean } | null;
+
+export function ExamplesTab({ tag, onTag, query, onQuery, busy, onRun, link, elsewhere, elsewhereError, onError, cohorts }: {
+  /** the example cohorts' tab: each previewed, analysed or saved on its own */
+  cohorts: {
+    examples: ExampleCohort[]; evals: Record<string, ExampleEval>; study: string; canSave: boolean;
+    onPreview: (ex: ExampleCohort) => void; onAnalyze: (ex: ExampleCohort) => void; onSave: (ex: ExampleCohort) => void;
+  };
   tag: string;
   onTag: (t: string) => void;
   /** the search over titles, descriptions and pills */
@@ -52,6 +64,7 @@ export function ExamplesTab({ tag, onTag, query, onQuery, busy, onRun, link, els
   onError: (msg: string) => void;
 }) {
   const [copied, setCopied] = useState<string | null>(null);
+  const [sub, setSub] = useState<"analyses" | "cohorts">("analyses");
   // the example whose Run is waiting on the reader's go-ahead to leave this site
   const [leaving, setLeaving] = useState<DslExample | null>(null);
   const run = (ex: DslExample) => { if (elsewhere) setLeaving(ex); else onRun(ex); };
@@ -83,6 +96,14 @@ export function ExamplesTab({ tag, onTag, query, onQuery, busy, onRun, link, els
 
   return (
     <div>
+      <Tabs value={sub} onValueChange={(v) => setSub(v as typeof sub)} className="mb-3">
+        <TabsList aria-label="examples" className="h-8">
+          <TabsTrigger value="analyses" className="px-3 text-md">Analyses</TabsTrigger>
+          <TabsTrigger value="cohorts" className="px-3 text-md">Cohorts</TabsTrigger>
+        </TabsList>
+      </Tabs>
+      {sub === "cohorts" && <ExampleCohorts {...cohorts} />}
+      {sub === "analyses" && <>
       <div className="card">
         <h2>Examples <span className="plain">— every one of these is executed by the test gate</span></h2>
         <p className="note exintro">
@@ -164,6 +185,7 @@ export function ExamplesTab({ tag, onTag, query, onQuery, busy, onRun, link, els
           );
         })}
       </div>
+      </>}
       {leaving && elsewhere && (
         <Dialog open onOpenChange={(open) => { if (!open) setLeaving(null); }}>
           <DialogContent data-tw className="leavedialog gap-3 sm:max-w-md">
@@ -187,3 +209,40 @@ export function ExamplesTab({ tag, onTag, query, onQuery, busy, onRun, link, els
     </div>
   );
 }
+
+/**
+ * The example cohorts, one per kind of clause: each previewed (its size), analysed on its own, or
+ * saved to the library. One with no study runs in the study the page is on.
+ */
+function ExampleCohorts({ examples, evals, study, canSave, onPreview, onAnalyze, onSave }: {
+  examples: ExampleCohort[]; evals: Record<string, ExampleEval>; study: string; canSave: boolean;
+  onPreview: (ex: ExampleCohort) => void; onAnalyze: (ex: ExampleCohort) => void; onSave: (ex: ExampleCohort) => void;
+}) {
+  return (
+    <div className="card excohorts">
+      <h2>Example cohorts <span className="plain">— one for each kind of clause; those that name no study run in {study}</span></h2>
+      {examples.map((ex) => {
+        const ev = evals[ex.name];
+        const where = ex.def.studies?.length ? ex.def.studies.join(" + ") : ex.def.study || study;
+        return (
+          <div key={ex.name} className="listrow">
+            <div className="listrow-head">
+              <strong>{ex.name}</strong>
+              <span className="meta">{ex.desc}</span>
+              <span className="meta">{where}</span>
+              {ev && ev.count != null && <span className="meta"><strong>{ev.count.toLocaleString()}</strong> pts</span>}
+              {ev && ev.busy && <span className="spinner" />}
+              <span className="spacer" />
+              <Button variant="link" size="inline" onClick={() => onPreview(ex)}>preview</Button>
+              <Button variant="link" size="inline" onClick={() => onAnalyze(ex)}>analyze</Button>
+              <Button variant="link" size="inline" onClick={() => onSave(ex)}
+                title={canSave ? "save it to your library" : "sign in to save it to your library"}>save to library</Button>
+            </div>
+            {ev && ev.error && <div className="error">{ev.error}</div>}
+            <div className="listrow-body"><CohortPills def={ex.def} /></div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/app/lab/list-cohort.tsx b/app/lab/list-cohort.tsx
new file mode 100644
index 00000000..704cb5d6
--- /dev/null
+++ b/app/lab/list-cohort.tsx
@@ -0,0 +1,174 @@
+"use client";
+// A cohort from a pasted list of sample or patient ids, wherever one can be made: a view's
+// "+ Add cohort", the analysis's cohort panel, and the library. The list is matched to the
+// studies' own cases and kept on the server (a stored id set, lib/id-set-store.ts); the cohort
+// names it by its id, so the analysis and its link stay small however long the list is. Needs a
+// sign-in, since the list is its saver's. The text stays in this component while it is typed.
+import { useState } from "react";
+import { Plus } from "lucide-react";
+import type { CohortDef } from "../../lib/types.ts";
+import { cn } from "../../lib/cn";
+import { Button } from "../_ui/button";
+import { Choice } from "../_ui/choice";
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from "../_ui/dialog";
+import { Input } from "../_ui/input";
+import { Tabs, TabsList, TabsTrigger } from "../_ui/tabs";
+import { Textarea } from "../_ui/textarea";
+import { TB } from "../_ui/toolbar.ts";
+import { api } from "./api.ts";
+
+/** The reader's sign-in, as the places that save cohorts know it. */
+export type SignInState = "off" | "locked" | "loading" | "ready" | "error";
+
+/** One id per line, or separated by commas, semicolons, tabs or spaces. */
+const splitIds = (text: string): string[] => text.split(/[\s,;]+/).map((x) => x.trim()).filter(Boolean);
+
+interface SavedList {
+  set: { id: string; name: string; level: "sample" | "patient"; studies: string[]; count: number };
+  unmatched: number; unmatchedExamples: string[]; duplicates: number; multiStudy: number;
+  refused: { study: string; reason: string }[];
+}
+
+/**
+ * The paste, match and confirm steps. `studies` are those the ids are matched in (a bare id is
+ * looked up in each); `studyPicker`, when given, sits in front of the form to choose them.
+ */
+export function ListSource({ studies, studyPicker, saved, disabled, doneTitle, doneLabel, nameFor = (n) => n, onDone, onLogin }: {
+  studies: string[];
+  studyPicker?: React.ReactNode;
+  saved: SignInState;
+  /** the final action is not possible now; `doneTitle` says why */
+  disabled?: boolean;
+  doneTitle: (as: string) => string;
+  doneLabel: React.ReactNode;
+  /** the name the cohort takes where it goes, when that place already has a different one of this name */
+  nameFor?: (name: string, def: CohortDef) => string;
+  onDone: (name: string, def: CohortDef) => void | Promise<void>;
+  onLogin: () => void;
+}) {
+  const [text, setText] = useState("");
+  const [level, setLevel] = useState<"sample" | "patient">("sample");
+  // no default: a list's name is how it is found again, in the analysis and the library
+  const [name, setName] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [err, setErr] = useState<string | null>(null);
+  const [done, setDone] = useState<SavedList | null>(null);
+  if (saved === "off") return <p className="note">A cohort from a list of ids is kept on the server, which needs a sign-in, and this deployment has none.</p>;
+  if (saved === "locked") return <p className="note"><Button variant="link" size="inline" className="text-md" onClick={onLogin}>Sign in</Button> to make a cohort from a list of ids: the list is kept on the server, as yours.</p>;
+  const ids = splitIds(text);
+  const save = async () => {
+    setBusy(true); setErr(null); setDone(null);
+    try {
+      const res = await api.idSets.create({ name: name.trim(), level, studies, ids });
+      const j = await res.json();
+      if (!res.ok || j.error) throw new Error(j.error || res.statusText);
+      setDone(j);
+    } catch (e) { setErr(String((e as Error)?.message || e)); }
+    finally { setBusy(false); }
+  };
+  const finish = async (as: string, d: CohortDef) => {
+    setBusy(true); setErr(null);
+    try { await onDone(as, d); }
+    catch (e) { setErr(String((e as Error)?.message || e)); }
+    finally { setBusy(false); }
+  };
+  const def: CohortDef | null = done ? {
+    all: [{ kind: done.set.level === "sample" ? "sampleList" : "patientList", set: done.set.id, label: done.set.name, n: done.set.count }],
+    // a cohort names the studies it was matched in, so it means the same wherever it is used
+    ...(done.set.studies.length > 1 ? { studies: done.set.studies } : { study: done.set.studies[0] }),
+  } : null;
+  const as = def ? nameFor(done!.set.name, def) : name.trim();
+  const noun = level === "sample" ? "sample" : "patient";
+  const reset = () => setDone(null);
+  return (
+    <div className="acd-list-ids flex flex-col gap-2.5">
+      <p className="note mt-0">
+        Paste {noun} ids, one per line or separated by commas or spaces, as <code>study:id</code> or bare ids, which are looked
+        up in {studies.length ? studies.join(", ") : "the study you choose"}. They are matched to the {noun}s there, and the
+        cohort is those {noun}s{noun === "sample" ? "' patients" : ""}.
+      </p>
+      <div className="viewtb">
+        {studyPicker && <div className="tbz">{studyPicker}</div>}
+        <div className="tbz">
+          <span className="tbl">ids are</span>
+          <Tabs value={level} onValueChange={(v) => { setLevel(v as "sample" | "patient"); reset(); }}>
+            <TabsList className="h-ctl">
+              <TabsTrigger value="sample" className="px-2.5 text-md">samples</TabsTrigger>
+              <TabsTrigger value="patient" className="px-2.5 text-md">patients</TabsTrigger>
+            </TabsList>
+          </Tabs>
+        </div>
+      </div>
+      <Textarea aria-label={noun + " ids"} rows={6} className="font-mono text-md md:text-md" value={text}
+        placeholder={level === "sample" ? "P-0000012-T01-IM3\nP-0000015-T01-IM3\n…" : "P-0000012\nP-0000015\n…"}
+        onChange={(e) => { setText(e.target.value); reset(); }} />
+      <div className="viewtb">
+        <div className="tbz">
+          <label className="tbfield">name <Input aria-label="set name" className="h-ctl w-56 text-md md:text-md" value={name} placeholder="name this list…"
+            onChange={(e) => { setName(e.target.value); reset(); }} /></label>
+          <Button variant="outline" size="sm" className={cn(TB, "idsetsave")} disabled={busy || !ids.length || !studies.length || !name.trim()}
+            title={!studies.length ? "choose the study to match the ids in" : !ids.length ? "paste some ids first"
+              : !name.trim() ? "name the list first: it is how it is found again, in the analysis and your library" : undefined}
+            onClick={() => void save()}>
+            {busy && !done && <span className="spinner" />}Match {ids.length ? ids.length.toLocaleString() + " id" + (ids.length === 1 ? "" : "s") : "ids"}</Button>
+        </div>
+      </div>
+      {err && <p className="error m-0">{err}</p>}
+      {done && def && <>
+        <p className="note m-0 idsetresult">
+          “{done.set.name}”: <strong>{done.set.count.toLocaleString()}</strong> {noun}{done.set.count === 1 ? "" : "s"}
+          {done.set.studies.length > 1 ? " across " + done.set.studies.length + " studies" : " in " + done.set.studies[0]}
+          {done.unmatched > 0 && <> · <span className="text-destructive">{done.unmatched.toLocaleString()} matched no {noun}</span>: {done.unmatchedExamples.slice(0, 5).join(", ")}{done.unmatched > 5 ? ", …" : ""}</>}
+          {done.duplicates > 0 && <> · {done.duplicates.toLocaleString()} given more than once</>}
+          {done.multiStudy > 0 && <> · {done.multiStudy.toLocaleString()} found in more than one study, kept in each</>}
+          {done.refused.length > 0 && <> · not matched in {done.refused.map((r) => r.study + " (" + r.reason + ")").join(", ")}</>}
+        </p>
+        <div className="viewtb">
+          <div className="tbz">
+            <Button variant="outline" size="sm" className={cn(TB, "idsetdone")} disabled={disabled || busy} title={doneTitle(as)}
+              onClick={() => void finish(as, def)}>{busy && <span className="spinner" />}{doneLabel}</Button>
+          </div>
+        </div>
+        {as !== done.set.name && <p className="meta m-0">as “{as}”, since “{done.set.name}” is already taken by a different cohort</p>}
+      </>}
+    </div>
+  );
+}
+
+/**
+ * The paste form in a dialog of its own: for the analysis's cohort panel (the analysis's studies)
+ * and the library (a study chosen here, since there is no analysis to take one from).
+ */
+export function ListCohortDialog({ title, studies, chooseFrom, saved, doneLabel, doneTitle, nameFor, onDone, onLogin, onClose }: {
+  title: string;
+  /** the studies to match in; absent → the reader chooses one from `chooseFrom` */
+  studies?: string[];
+  chooseFrom?: { id: string; name: string }[];
+  saved: SignInState;
+  doneLabel: React.ReactNode;
+  doneTitle: (as: string) => string;
+  nameFor?: (name: string, def: CohortDef) => string;
+  onDone: (name: string, def: CohortDef) => Promise<void>;
+  onLogin: () => void;
+  onClose: () => void;
+}) {
+  const [study, setStudy] = useState("");
+  const picker = !studies && (
+    <label className="tbfield">study <Choice size="ctl" className="w-72" value={study} onChange={setStudy} placeholder="choose a study…"
+      pending={chooseFrom && chooseFrom.length ? undefined : "loading studies…"}
+      options={(chooseFrom || []).map((s) => [s.id, s.name + " (" + s.id + ")"] as const)} /></label>
+  );
+  return (
+    <Dialog open onOpenChange={(open) => { if (!open) onClose(); }}>
+      <DialogContent aria-describedby={undefined} className="listcohortdialog flex max-h-[85vh] w-[min(94vw,40rem)] max-w-[40rem] flex-col gap-3 overflow-y-auto sm:max-w-[40rem]">
+        <DialogHeader><DialogTitle className="text-base">{title}</DialogTitle></DialogHeader>
+        <ListSource studies={studies || (study ? [study] : [])} studyPicker={picker || undefined} saved={saved}
+          doneLabel={doneLabel} doneTitle={doneTitle} nameFor={nameFor} onLogin={onLogin}
+          onDone={async (n, d) => { await onDone(n, d); onClose(); }} />
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+/** The usual final button: add, or use in place of the one cohort a view draws. */
+export const addLabel = (replaces: boolean) => replaces ? "Use" : <><Plus />Add</>;
diff --git a/app/lab/page.tsx b/app/lab/page.tsx
index 9737ccef..aaee065d 100644
--- a/app/lab/page.tsx
+++ b/app/lab/page.tsx
@@ -5,6 +5,7 @@ import { ExploreCharts } from "./explore-charts";
 import type { UnpackedContract } from "../../lib/oncoprint-binary.ts";
 import type { AnalysisDoc, CohortDef } from "../../lib/types.ts";
 import { storeCohortLists, storeDocLists } from "./id-sets-client.ts";
+import type { SignInState } from "./list-cohort.tsx";
 import { useLabTools, LAB_TOOL_NAMES } from "./agent-tools.ts";
 import { AgentToolsMenu } from "../_agent/AgentToolsMenu.tsx";
 import { useCustomDataState } from "./custom-data-panel.tsx";
@@ -336,7 +337,7 @@ export default function AnalysisPage() {
   const toolActions = useToolActions({ doc, docs, goTab, persistSpaces, queryClient, setError, setStudy, setValidating, study });
   const { commitDoc, proposePartition, saveAs, validateDoc } = toolActions;
   const library = useLibrary({ docs, evalDef, goTab, persist, saved, sharedSaved: savedArtifacts.sharedCohorts, setError, setStudy, study });
-  const { analyzePicked, cohortsSubTab, docLink, exEvals, exQuery, exTag, picked, previewExample, runDocExample, saveExample, setCohortsSubTab, setExQuery, setExTag, setPicked, togglePick } = library;
+  const { analyzeExampleCohort, analyzePicked, cohortsSubTab, docLink, exEvals, exQuery, exTag, picked, previewExample, runDocExample, saveExample, setCohortsSubTab, setExQuery, setExTag, setPicked, togglePick } = library;
   // where the gallery examples run (EXAMPLES_URL): here, or a deployment that holds their studies
   const { examplesUrl, examplesUrlError } = useExamplesUrl();
   const exampleLink = (ex: DslExample) => examplesUrl ? examplesUrl + "/lab?doc=" + docParam(ex.doc) : docLink(ex.doc);
@@ -361,7 +362,7 @@ export default function AnalysisPage() {
   /** what every view card reads and the edits it can make (app/lab/view-cards.tsx) */
   const viewCtx = { VIEW_KINDS, docHistory, study, assayOptions, attrsLoading, busy, cat, catLoading, catalogAttrs, cohortChoice, cohortFromSelection, contracts, doc, docView, drawsOwnHead, explore, featureFromSelection, maxCohortsOf, menuOpenRef, moveView, noteEdit, ocView, openCohortChooser, openGenes, patchView, pendingKeys, profileOptions, removeView, setContracts, setViewAttrs, setViewCohorts, trackAttrs, trackAttrsLoading, updateView, updateViewLocal, viewEvents, viewIds };
   /** what the Analysis tab's sections read and the actions they take (app/lab/analysis-sections.tsx) */
-  const analysisCtx: AnalysisCtx = { lockCohorts, unlockCohort, unlockAll, canSave, VIEW_KINDS, addView, docHistory, applyText, busy, catalogAttrs, clearAnalysis, doc, docDialog, docText, docs, explore, fetchExplore, cohortCells, cohortSaveState, cohortSource, openCohortCells, emptyViewHint, genesFor, goTab, loggedIn, menuOpenRef, moveView, openCohortChooser, openCohortEdit, openCustomManager, openWorkspaceSave, removeCohort, removePartitionNamed, removeView, removeViews, renamePartitionRow, result, saveCohortToLibrary, saved, setCdFocus, setGenesFor, setPartitionDef, setUpgradeNote, setViewGenes, showClauseData, spaces, splitCohortBy, splitsFlat, studyNames, tab, updateFromSaved, upgradeNote, viewCtx, viewIds, viewTitle };
+  const analysisCtx: AnalysisCtx = { lockCohorts, unlockCohort, unlockAll, canSave, analysisStudies, requestLogin, signIn: (!customState.enabled ? "off" : !loggedIn ? "locked" : "ready") as SignInState, VIEW_KINDS, addView, docHistory, applyText, busy, catalogAttrs, clearAnalysis, doc, docDialog, docText, docs, explore, fetchExplore, cohortCells, cohortSaveState, cohortSource, openCohortCells, emptyViewHint, genesFor, goTab, loggedIn, menuOpenRef, moveView, openCohortChooser, openCohortEdit, openCustomManager, openWorkspaceSave, removeCohort, removePartitionNamed, removeView, removeViews, renamePartitionRow, result, saveCohortToLibrary, saved, setCdFocus, setGenesFor, setPartitionDef, setUpgradeNote, setViewGenes, showClauseData, spaces, splitCohortBy, splitsFlat, studyNames, tab, updateFromSaved, upgradeNote, viewCtx, viewIds, viewTitle };
   // what the page offers the researcher's AI assistant (app/lab/agent-tools.ts), current every render
   const webmcp = useLabTools({
     doc, result, busy, error, tab, study, savedAs: analysisSaved ? doc.title || null : null,
@@ -485,14 +486,16 @@ export default function AnalysisPage() {
 
         {/* ================= Saved tab ================= */}
         {tab === "cohorts" && <SavedTab login={customState} onLogin={requestLogin}
-          sub={cohortsSubTab} onSub={setCohortsSubTab} examples={EXAMPLES}
+          sub={cohortsSubTab} onSub={setCohortsSubTab}
           picked={picked} onTogglePick={togglePick} onClearPicked={() => setPicked([])} onAnalyze={analyzePicked}
-          evals={exEvals} onPreview={previewExample} onSaveExample={saveExample}
+          studies={studies} onNewFromList={async (name, def) => { await persist(name, def, null); }}
           saved={savedArtifacts} onOpenWorkspace={openWorkspace} onOpenShared={openShared} onDeleteWorkspace={deleteWorkspace}
           wsError={wsError} onCustomData={showClauseData} />}
 
         {/* ================= Examples tab ================= */}
         {tab === "examples" && <ExamplesTab tag={exTag} onTag={setExTag} query={exQuery} onQuery={setExQuery} busy={busy}
+          cohorts={{ examples: EXAMPLES, evals: exEvals, study, canSave: loggedIn, onPreview: (ex) => void previewExample(ex), onAnalyze: analyzeExampleCohort,
+            onSave: (ex) => { if (canSave()) void saveExample(ex); } }}
           onRun={runDocExample} link={exampleLink} elsewhere={examplesUrl} elsewhereError={examplesUrlError} onError={setError} />}
 
         {/* ================= Analysis tab ================= */}
@@ -510,7 +513,6 @@ export default function AnalysisPage() {
             : savedArtifacts.cohortsState.pending ? "loading" : savedArtifacts.cohortsState.error ? "error" : "ready",
           savedError: savedArtifacts.cohortsState.error,
           cohorts: Object.entries(saved).map(([name, x]) => ({ id: x.id, name, def: x.def, savedAt: x.savedAt })),
-          examples: EXAMPLES,
         }}
         onAdd={(name, def) => { if (chooser) addCohortToView(chooser, name, def); }}
         studies={analysisStudies()}
diff --git a/app/lab/saved-tab.tsx b/app/lab/saved-tab.tsx
index 631b4c2c..84902271 100644
--- a/app/lab/saved-tab.tsx
+++ b/app/lab/saved-tab.tsx
@@ -8,6 +8,10 @@ import { ShareDialog, sharingLabel } from "./share-dialog.tsx";
 import { useGroups } from "./use-groups.ts";
 import { shareServerDataset } from "./custom-data-client.ts";
 import { api } from "./api.ts";
+import { ListCohortDialog } from "./list-cohort.tsx";
+import { cn } from "../../lib/cn";
+import { TB } from "../_ui/toolbar.ts";
+import { Plus, Save } from "lucide-react";
 import type { ArtifactKind } from "../../lib/artifacts.ts";
 import type { Sharing } from "../../lib/access.ts";
 import { Waiting } from "../_oncoprint/OncoprintCard.tsx";
@@ -18,8 +22,6 @@ import { Button } from "../_ui/button";
 import { Checkbox } from "../_ui/checkbox";
 import { Tabs, TabsList, TabsTrigger } from "../_ui/tabs";
 
-export type ExampleCohort = { name: string; desc: string; def: CohortDef };
-export type ExampleEval = { count?: number; error?: string; busy?: boolean } | null;
 
 const OWN = "yours, shared as each says";
 
@@ -44,22 +46,22 @@ function ListStatus({ state, what, empty, isEmpty }: { state: ListState; what: s
 }
 
 export function SavedTab({
-  login, onLogin, sub, onSub, examples, picked, onTogglePick, onClearPicked, onAnalyze,
-  evals, onPreview, onSaveExample, saved, onOpenWorkspace, onOpenShared, onDeleteWorkspace, wsError, onCustomData,
+  login, onLogin, sub, onSub, picked, onTogglePick, onClearPicked, onAnalyze,
+  studies, onNewFromList, saved, onOpenWorkspace, onOpenShared, onDeleteWorkspace, wsError, onCustomData,
 }: {
   login: ServerState;
   onLogin: () => void;
   sub: "cohorts" | "analyses";
   onSub: (s: "cohorts" | "analyses") => void;
-  examples: ExampleCohort[];
-  /** keys "ex:<name>" / "saved:<name>" */
+  /** keys "saved:<name>" / "shared:<id>" */
   picked: string[];
   onTogglePick: (key: string) => void;
   onClearPicked: () => void;
   onAnalyze: () => void;
-  evals: Record<string, ExampleEval>;
-  onPreview: (ex: ExampleCohort) => void;
-  onSaveExample: (ex: ExampleCohort) => void;
+  /** the studies a new cohort from a list may be matched in */
+  studies: { id: string; name: string }[];
+  /** save a cohort made from a list of ids to the library */
+  onNewFromList: (name: string, def: CohortDef) => Promise<void>;
   /** open an analysis someone shared with the reader, by id */
   onOpenShared: (id: string) => void;
   saved: SavedArtifacts;
@@ -70,6 +72,7 @@ export function SavedTab({
 }) {
   const groups = useGroups(login.user?.id ?? null);
   const [sharing, setSharing] = useState<{ kind: ArtifactKind; id: string; name: string; sharing: Sharing } | null>(null);
+  const [newList, setNewList] = useState(false);
   if (!login.loaded) return <div className="card"><Waiting what="your sign-in" /></div>;
   if (!login.unlocked) return <div className="card">
     <p className="flush">Saved cohorts and analyses are your own.{" "}
@@ -104,33 +107,14 @@ export function SavedTab({
         {picked.length > 0 && <Button variant="link" size="inline" onClick={onClearPicked}>clear</Button>}
       </div>
 
-      <h2 className="savedsec">Examples</h2>
-      {examples.map(ex => {
-        const ev = evals[ex.name];
-        return (
-          <div key={ex.name} className="listrow">
-            <div className="listrow-head">
-              <label className="pick">
-                <Checkbox checked={picked.includes("ex:" + ex.name)} onCheckedChange={() => onTogglePick("ex:" + ex.name)} />
-                <strong>{ex.name}</strong>
-              </label>
-              <span className="meta">{ex.desc}</span>
-              {ev && ev.count != null && <span className="meta"><strong>{ev.count.toLocaleString()}</strong> pts</span>}
-              {ev && ev.busy && <span className="spinner" />}
-              <span className="spacer" />
-              <Button variant="link" size="inline" onClick={() => onPreview(ex)}>preview</Button>
-              <Button variant="link" size="inline" onClick={() => onSaveExample(ex)}>save</Button>
-            </div>
-            {ev && ev.error && <div className="error">{ev.error}</div>}
-          </div>
-        );
-      })}
-
-      <h2 className="savedsec">
-        Saved cohorts <span className="plain">— {OWN}. Tick any to include above; delete here.</span>
+      <h2 className="savedsec flex items-center gap-2.5">
+        <span>Saved cohorts <span className="plain">— {OWN}. Tick any to include above; delete here.</span></span>
+        <Button variant="outline" size="sm" className={cn(TB, "newlistcohort ml-auto")} onClick={() => setNewList(true)}
+          title="make a cohort from a pasted list of sample or patient ids, saved straight to your library">
+          <Plus />New cohort from a list of ids…</Button>
       </h2>
       <ListStatus state={saved.cohortsState} what="saved cohorts" isEmpty={!Object.keys(saved.cohorts).length}
-        empty="Nothing saved yet — save an example above, build one on the Explore page, or ask chat." />
+        empty="Nothing saved yet — build one on the Explore page, make one from a list of ids, save one from an analysis, or ask chat." />
       {byNewest(saved.cohorts).map(([n, c]) => (
         <div key={n} className="listrow">
           <div className="listrow-head">
@@ -208,6 +192,11 @@ export function SavedTab({
       </div>}
     </div>}
 
+    {newList && <ListCohortDialog title="New cohort from a list of ids" chooseFrom={studies} saved="ready"
+      doneLabel={<><Save />Save to your library</>} doneTitle={(as) => "save “" + as + "” to your library"}
+      nameFor={(n) => { if (!saved.cohorts[n]) return n; for (let i = 2; ; i++) if (!saved.cohorts[n + " (" + i + ")"]) return n + " (" + i + ")"; }}
+      onDone={onNewFromList} onLogin={onLogin} onClose={() => setNewList(false)} />}
+
     {sharing && <ShareDialog kind={sharing.kind === "workspace" ? "analysis" : "cohort"} name={sharing.name} sharing={sharing.sharing}
       groups={groups.groups} groupsError={groups.error}
       onSave={(s) => saved.share(sharing.kind, sharing.id, s)}
diff --git a/app/lab/use-library.ts b/app/lab/use-library.ts
index b6f8b69f..2573b81d 100644
--- a/app/lab/use-library.ts
+++ b/app/lab/use-library.ts
@@ -15,7 +15,6 @@ import type { SavedCohort, Shared } from "./use-saved.ts";
 const IMMUNO_EVENT: any = { kind: "event", a: { eventType: "Treatment", attrs: [{ key: "SUBTYPE", value: "Immuno" }] }, rel: { type: "NONE" } };
 
 interface Example { name: string; desc: string; def: CohortDef }
-/** The Saved tab's example cohorts: definitions to preview, save or analyse, one per kind of clause. */
 /** A document as a ?doc= value: base64url of its UTF-8 JSON, as the page reads it back. */
 export function docParam(d: AnalysisDoc | TemplateDoc): string {
   return btoa(String.fromCharCode(...new TextEncoder().encode(JSON.stringify(d))))
@@ -83,9 +82,7 @@ export function useLibrary(page: LibraryPage) {
       const rest = key.slice(key.indexOf(":") + 1);
       const other = key.startsWith("shared:") ? sharedSaved.find((x) => x.id === rest) : undefined;
       let name = other ? other.name : rest;
-      const def = key.startsWith("ex:") ? (EXAMPLES.find((e) => e.name === name) || {}).def
-        : other ? other.item.def
-        : (saved[name] || {}).def;
+      const def = other ? other.item.def : (saved[name] || {}).def;
       // someone else's cohort may share a name with one already chosen: say whose it is
       if (other && chosen.some(([n]) => n === name)) name += " (" + (other.owner.name || other.owner.email) + ")";
       if (def) chosen.push([name, def]);
@@ -105,6 +102,15 @@ export function useLibrary(page: LibraryPage) {
   const togglePick = (key: string) =>
     setPicked((p) => p.includes(key) ? p.filter((x) => x !== key) : [...p, key]);
 
+  /** A fresh analysis of one example cohort, as Analyze does for the explored cohort: no views yet. */
+  const analyzeExampleCohort = (ex: { name: string; def: CohortDef }) => {
+    const s = ex.def.study || ex.def.studies?.[0] || study;
+    docs.replace({ dsl: DOC_VERSION, study: s, cohorts: { [ex.name]: ex.def }, views: [] });
+    setStudy(s);
+    setError(null);
+    goTab("analysis");
+  };
+
   /** Load a documented example into the Analysis tab and run it. */
   const runDocExample = (ex: DslExample) => {
     const d = JSON.parse(JSON.stringify(ex.doc)) as AnalysisDoc;   // never hand the shared object to the editor
@@ -131,5 +137,5 @@ export function useLibrary(page: LibraryPage) {
     try { await persist(ex.name, ex.def, lastEval); } catch { /* the Examples tab has no error banner of its own */ }
   };
 
-  return { cohortsSubTab, setCohortsSubTab, exTag, setExTag, exQuery, setExQuery, picked, setPicked, exEvals, setExEvals, analyzePicked, togglePick, runDocExample, docLink, previewExample, saveExample };
+  return { cohortsSubTab, setCohortsSubTab, exTag, setExTag, exQuery, setExQuery, picked, setPicked, exEvals, setExEvals, analyzePicked, togglePick, runDocExample, docLink, previewExample, saveExample, analyzeExampleCohort };
 }
diff --git a/e2e-saved.cjs b/e2e-saved.cjs
index 12c15a38..7742eb6b 100644
--- a/e2e-saved.cjs
+++ b/e2e-saved.cjs
@@ -43,7 +43,7 @@ async function savedLists(browser, ok, BASE, LOGIN) {
       await page.goto(BASE + "/lab?tab=cohorts", { waitUntil: "domcontentloaded" });
       await page.getByText("loading saved cohorts").waitFor({ timeout: 120000 });
       const claimsEmpty = await page.getByText("Nothing saved yet").count();
-      const usable = await page.getByRole("button", { name: "preview" }).first().isEnabled();
+      const usable = await page.locator(".newlistcohort").isEnabled();
       release(); await page.unroute(LIST);
       await page.getByText("loading saved cohorts").waitFor({ state: "detached", timeout: 60000 });
       ok("a saved list that is loading says so, and the tab stays usable", claimsEmpty === 0 && usable,
@@ -66,16 +66,20 @@ async function savedLists(browser, ok, BASE, LOGIN) {
       ok("a saved list that failed names the error and retries", claimsEmpty === 0, "claims empty: " + !!claimsEmpty);
     }
 
-    // saving an example twice under its name: one stored cohort, listed once
+    // saving an example cohort (Examples page, Cohorts) twice under its name: one stored cohort, listed once
     {
-      const first = page.locator("label.pick").first();
-      const name = (await first.innerText()).trim();
-      const row = first.locator("xpath=../..");
-      await row.getByRole("button", { name: "save" }).click();
-      await page.locator("label.pick", { hasText: name }).nth(1).waitFor({ timeout: 120000 });
-      await row.getByRole("button", { name: "save" }).click();
+      await page.goto(BASE + "/lab?tab=examples", { waitUntil: "domcontentloaded" });
+      await page.getByRole("tab", { name: "Cohorts", exact: true }).click();
+      const row = page.locator(".excohorts .listrow").first();
+      const name = (await row.locator("strong").first().innerText()).trim();
+      await row.getByRole("button", { name: "save to library" }).click();
+      for (let i = 0; i < 120 && (await savedCount(name)) < 1; i++) await page.waitForTimeout(500);
+      await row.getByRole("button", { name: "save to library" }).click();
       await page.waitForTimeout(2500);
-      const stored = await savedCount(name), listed = await page.locator("label.pick", { hasText: name }).count() - 1;
+      const stored = await savedCount(name);
+      await page.goto(BASE + "/lab?tab=cohorts", { waitUntil: "domcontentloaded" });
+      await page.locator("label.pick", { hasText: name }).first().waitFor({ timeout: 120000 });
+      const listed = await page.locator("label.pick", { hasText: name }).count();
       ok("saving a cohort under a name it has updates it", stored === 1 && listed === 1, "stored " + stored + ", listed " + listed);
     }
 
diff --git a/e2e.cjs b/e2e.cjs
index 603ce511..fe3df4f0 100644
--- a/e2e.cjs
+++ b/e2e.cjs
@@ -718,7 +718,10 @@ async function main() {
       ok("an explicit ?tab= beats the document's default tab",
         (await page.locator("[aria-label='lab sections'] [role=tab][aria-selected=true]").innerText()).trim() === "Examples");
 
-      // Cohorts tab: tick cohorts, submit them together. No per-row "add" links.
+      // Cohorts tab: tick cohorts, submit them together. No per-row "add" links. The example
+      // cohorts live on the Examples page, so two saved cohorts are what get ticked here.
+      for (const [n, q] of [["e2e pick KRAS " + scheme, "KRAS: MUT"], ["e2e pick TP53 " + scheme, "TP53: MUT"]])
+        await page.context().request.post(BASE + "/api/artifacts", { data: { kind: "cohort", name: n, definition: { study: "msk_chord_2024", all: [{ kind: "oql", q }] } } });
       await page.goto(BASE + "/lab");
       await page.getByRole("tab", { name: "Saved", exact: true }).click();
       await page.waitForSelector(".pick [role=checkbox]", { timeout: 240000 });
@@ -1509,6 +1512,66 @@ async function main() {
       steps.matched && steps.named && steps.counted && steps.noIds && steps.signedOut && steps.otherUser && steps.deleted, JSON.stringify(steps));
     await ctx.close();
   }
+  // A cohort from a list of ids can be made in the library (choosing its study) and from the
+  // analysis's cohort panel (no view needed); example cohorts live only on the Examples page.
+  if (LOGIN) {
+    const ctx = await browser.newContext({ viewport: { width: 1400, height: 1000 } });
+    const sp = await ctx.newPage();
+    let steps = {};
+    try {
+      await signIn(ctx, "lists2." + LOGIN);
+      const ex = await (await ctx.request.get(BASE + "/api/custom-data/example?study=msk_chord_2024")).json();
+      const patients = ex.patients || [];
+      const fill = async (dlg, name) => {
+        await dlg.getByRole("tab", { name: "patients" }).click();
+        await dlg.locator("textarea").fill(patients.join("\n"));
+        await dlg.locator("input[aria-label='set name']").fill(name);
+        await dlg.locator(".idsetsave").click();
+        await dlg.locator(".idsetresult").waitFor({ timeout: 60000 });
+        await dlg.locator(".idsetdone").click();
+        await dlg.waitFor({ state: "detached", timeout: 60000 });
+      };
+      // the library: no analysis around it, so the study is chosen
+      await sp.goto(BASE + "/lab?tab=cohorts", { waitUntil: "domcontentloaded" });
+      await sp.locator(".newlistcohort").click();
+      const lib = sp.locator("[role=dialog].listcohortdialog");
+      await lib.waitFor({ timeout: 30000 });
+      steps.needsStudy = await lib.locator(".idsetsave").isDisabled();
+      await lib.getByRole("combobox").click();
+      await sp.getByRole("option", { name: /\(msk_chord_2024\)/ }).click();
+      const libName = "e2e library list " + Date.now();
+      await fill(lib, libName);
+      const art = ((await (await ctx.request.get(BASE + "/api/artifacts?kind=cohort")).json()).artifacts || []).find((a) => a.name === libName);
+      const leaf = art?.definition?.all?.[0] || {};
+      steps.inLibrary = !!art && leaf.kind === "patientList" && /^[0-9a-f-]{36}$/.test(leaf.set || "") && art.definition.study === "msk_chord_2024";
+      steps.noExamplesInSaved = (await sp.locator("h2.savedsec", { hasText: /^Examples/ }).count()) === 0;
+      // the analysis's cohort panel, with no view yet
+      await sp.goto(BASE + "/lab?tab=analysis&doc=" + Buffer.from(JSON.stringify({ dsl: "2.8", study: "msk_chord_2024", cohorts: {}, views: [] })).toString("base64url"), { waitUntil: "domcontentloaded" });
+      await sp.locator(".fromlist").click();
+      const pane = sp.locator("[role=dialog].listcohortdialog");
+      await pane.waitFor({ timeout: 30000 });
+      await fill(pane, "e2e panel list");
+      await sp.waitForSelector(".cohortbox .cohortbox-head strong", { timeout: 120000 });
+      const d = JSON.parse(await sp.locator("#docjson").inputValue());
+      steps.inAnalysis = d.cohorts["e2e panel list"]?.all?.[0]?.kind === "patientList" && (d.views || []).length === 0
+        && (await sp.locator(".cohortbox-head").first().innerText()).replace(/\s+/g, "").includes(String(patients.length));
+      // example cohorts: on the Examples page's Cohorts tab, and not in "+ Add cohort"'s library
+      // (an analysis with no cohorts, so a new view waits for one)
+      await sp.goto(BASE + "/lab?tab=analysis&doc=" + Buffer.from(JSON.stringify({ dsl: "2.8", study: "msk_chord_2024", cohorts: {}, views: [] })).toString("base64url"), { waitUntil: "domcontentloaded" });
+      await sp.locator(".addview button:has-text('Survival')").click();
+      await sp.locator(".emptyview .emptyview-body button").first().click();
+      await sp.getByRole("tab", { name: "Library" }).click();
+      steps.noExamplesInDialog = (await sp.locator(".addcohortdialog .acd-row", { hasText: "STK11-driver" }).count()) === 0;
+      await sp.keyboard.press("Escape");
+      await sp.goto(BASE + "/lab?tab=examples", { waitUntil: "domcontentloaded" });
+      await sp.getByRole("tab", { name: "Cohorts", exact: true }).click();
+      steps.examplesTab = (await sp.locator(".excohorts .listrow", { hasText: "STK11-driver" }).count()) > 0;
+      if (art) await ctx.request.delete(BASE + "/api/artifacts/" + art.id);
+    } catch (e) { steps.error = String(e.message || e).slice(0, 160); }
+    ok("a cohort from a list of ids can be made in the library (study chosen) and from the cohort panel; example cohorts are only on the Examples page",
+      steps.needsStudy && steps.inLibrary && steps.noExamplesInSaved && steps.inAnalysis && steps.noExamplesInDialog && steps.examplesTab, JSON.stringify(steps));
+    await ctx.close();
+  }
   // Nothing is saved with an inline id list: saving a cohort that carries one stores the list as an
   // id set first, the analysis's copy takes the same set, and saving again stores nothing new.
   if (LOGIN) {

From b24b5a9c60267981c61e0cf70de65276282cd968 Mon Sep 17 00:00:00 2001
From: Aaron Lisman <lisman.aaron@gmail.com>
Date: Mon, 19 Oct 2026 15:05:17 +0000
Subject: [PATCH 7/7] A locked cohort is one id_set row: patients, samples and
 arms together

db/migrations/0007 adds id_set.kind ('list' | 'lock'), parts (sizes) and
parts_gz (members), covered by the immutability trigger. A lock keeps the
cohort's patients in ids_gz as before, and beside them, as named parts, those
patients' samples ("samples") and each split arm's patients
("arm:<split> / <arm>"). The cohort's `lock` names that one set; an arm names
its part (`part`), and compiles to a ClickHouse external table of its own,
uploaded only where the set's ids may go. Locks made before parts (separate
sample and arm sets) are still read as they were (lockSamples, applyLocks).

Verified against the live warehouse: locking KRAS NSCLC (with a split) and
EGFR made exactly one id_set row each (KRAS: 2,194 patients, parts samples
2,225 and three arms); counts, views, drift (+4,921 when widened) and an arm
added after locking (conserved) unchanged. Unit tests for parts (table names,
uploads, drift against the samples part, older locks); store contract for a
lock's parts and their immutability; the e2e lock check asserts one row per
locked cohort. 0007 applied to the shared Supabase (additive; production
unaffected). Gate (GATE_PORT=4111 scripts/gate.sh) passes: 257 e2e checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvdfHurd9t63GK2ToazMti
---
 db/migrations/0007_id_set_parts.sql | 34 +++++++++++++++++
 docs/dsl.md                         | 10 +++--
 e2e.cjs                             |  9 +++--
 lib/analysis.ts                     |  6 +--
 lib/cohort-lock-server.ts           | 32 +++++++++-------
 lib/cohort-lock.ts                  | 12 +++++-
 lib/cohort2.ts                      | 12 +++---
 lib/dsl-reference.ts                | 10 +++--
 lib/federation.ts                   |  4 +-
 lib/id-set-store.ts                 | 57 ++++++++++++++++++++---------
 lib/id-sets.ts                      | 44 +++++++++++++++-------
 lib/types.ts                        | 20 +++++++---
 test/cohort-lock.test.ts            | 43 +++++++++++++++-------
 test/postgres.db-test.ts            |  2 +-
 test/support/store-contracts.ts     | 13 +++++++
 15 files changed, 220 insertions(+), 88 deletions(-)
 create mode 100644 db/migrations/0007_id_set_parts.sql

diff --git a/db/migrations/0007_id_set_parts.sql b/db/migrations/0007_id_set_parts.sql
new file mode 100644
index 00000000..b468fe85
--- /dev/null
+++ b/db/migrations/0007_id_set_parts.sql
@@ -0,0 +1,34 @@
+-- A locked cohort's members in one id_set row (lib/cohort-lock-server.ts): its patients, as any
+-- set's, in ids_gz; and beside them the other lists the lock froze, as named parts — "samples"
+-- (those patients' samples then) and "arm:<split> / <arm>" (each split arm's patients) — so a lock
+-- is one row, not one per list.
+--
+--   kind      'list' (a list of ids someone gave) or 'lock' (what a cohort selected when locked)
+--   parts     the parts' sizes, {"samples": n, "arm:sex / Female": n, ...}; null for a list
+--   parts_gz  the parts' members as gzipped JSON ({part: {study: [bare id, ...]}}); null for a list
+--
+-- The parts are members, so they are as immutable as ids_gz (the trigger below).
+--
+-- Applied by `npm run db:migrate` (lib/migrate.ts), after 0006. Re-runnable.
+
+alter table id_set add column if not exists kind text not null default 'list';
+alter table id_set drop constraint if exists id_set_kind;
+alter table id_set add constraint id_set_kind check (kind in ('list', 'lock'));
+alter table id_set add column if not exists parts jsonb;
+alter table id_set add column if not exists parts_gz bytea;
+
+create or replace function id_set_members_immutable() returns trigger as $$
+begin
+  if tg_op = 'DELETE' then
+    raise exception 'id sets are never deleted: they are soft-deleted (deleted_at), so a document naming one is refused rather than reading nothing';
+  end if;
+  if new.level is distinct from old.level or new.studies is distinct from old.studies
+     or new.id_count is distinct from old.id_count or new.per_study is distinct from old.per_study
+     or new.ids_gz is distinct from old.ids_gz or new.sha256 is distinct from old.sha256
+     or new.kind is distinct from old.kind or new.parts is distinct from old.parts or new.parts_gz is distinct from old.parts_gz
+     or new.owner_id is distinct from old.owner_id or new.created_at is distinct from old.created_at then
+    raise exception 'an id set''s members are immutable: save a new set instead';
+  end if;
+  return new;
+end;
+$$ language plpgsql;
diff --git a/docs/dsl.md b/docs/dsl.md
index 14523ff9..1637396c 100644
--- a/docs/dsl.md
+++ b/docs/dsl.md
@@ -37,8 +37,8 @@ cohortDef := { "all": [clause × 0-8],         // ANDed; [] means every patient
                "notes"?:   "<prose>",         // the analyst's own note on this cohort; never compiled
                "from"?:    { "saved": "<id>", "name": "<name>", "hash": "<sha256>", "savedAt"?: "<when>" },  // set by the page: the saved cohort this was copied from, and the hash of what was copied; never compiled
                "splits"?:  { "<name>": splitDef },  // divisions of this cohort into arms that add up to it
-               "lock"?:    { "set": "<id set>", "n": N, "samples"?: "<id set>", "nSamples"?: N, "at": "<ISO time>",
-                             "dataVersion"?: "…", "oncokbPin"?: "…", "children"?: { "<split> / <arm>": { "set", "n" } } } }
+               "lock"?:    { "set": "<id set>", "n": N, "nSamples"?: N, "at": "<ISO time>", "dataVersion"?: "…", "oncokbPin"?: "…",
+                             "children"?: { "<split> / <arm>": { "set", "part": "arm:<split> / <arm>", "n" } } } }
                                               // frozen to the patients it selected at "at" — see "Locked cohorts" below
 splitDef  := { "arms": [ { "name": "<label>", "where": clause, "splits"?: {…} } × 1-8 ],  // tested in order; first match wins; an arm may be split again
                "other"?: "<label>",            // the remainder's name, default "Other"
@@ -133,8 +133,10 @@ describes for every other identifier-bearing path.
 
 **Locked cohorts.** A cohort can be frozen to the patients its definition selects at one moment,
 so an analysis stops drifting as patients are added to the data: `lock` names the stored id set
-of those patients (and of their samples), when it was taken, the data version and OncoKB release
-then, and, under `children`, the frozen patients of each of its split arms by name. The engine
+holding those patients, when it was taken, the data version and OncoKB release then, and, under
+`children`, each split arm by name. The lock is ONE set: beside the patients it keeps, as named
+parts, their samples (`"samples"`, `nSamples` of them) and each arm's patients (`part`:
+`"arm:<split> / <arm>"`). The engine
 evaluates the set, not the definition; the definition stays as the record of how the cohort was
 made, and is still run beside the set, so the result's `cohorts[name].lock` says how far the
 data has moved: what the definition selects `now`, who it would add (`entered`) or drop
diff --git a/e2e.cjs b/e2e.cjs
index fe3df4f0..b809989c 100644
--- a/e2e.cjs
+++ b/e2e.cjs
@@ -1635,13 +1635,16 @@ async function main() {
       await sp.goto(BASE + "/lab?tab=analysis&doc=" + Buffer.from(JSON.stringify(doc)).toString("base64url"), { waitUntil: "domcontentloaded" });
       await sp.waitForFunction(() => document.querySelectorAll(".cohortbox-head strong").length === 2, null, { timeout: 180000 });
       const before = await counts();
+      const setsBefore = ((await (await ctx.request.get(BASE + "/api/id-sets")).json()).sets || []).length;
       await sp.locator(".lockall").click();
       await sp.waitForSelector(".lockdrift", { timeout: 180000 });
       await sp.waitForFunction(() => document.querySelectorAll(".lockdrift").length === 2, null, { timeout: 180000 });
       const d = await docOf();
       const k = d.cohorts["KRAS NSCLC"].lock || {};
-      steps.locked = !!d.locked?.at && /^[0-9a-f-]{36}$/.test(k.set || "") && /^[0-9a-f-]{36}$/.test(k.samples || "") && k.at === d.locked.at && d.cohorts.EGFR.lock?.at === d.locked.at;
-      steps.arms = Object.keys(k.children || {}).some((c) => c.startsWith("g12c / "));
+      steps.locked = !!d.locked?.at && /^[0-9a-f-]{36}$/.test(k.set || "") && k.nSamples > 0 && !k.samples && k.at === d.locked.at && d.cohorts.EGFR.lock?.at === d.locked.at;
+      // its arms are parts of its one set, not sets of their own: one row per locked cohort
+      steps.arms = Object.entries(k.children || {}).some(([c, m]) => c.startsWith("g12c / ") && m.set === k.set && m.part === "arm:" + c);
+      steps.oneRowEach = ((await (await ctx.request.get(BASE + "/api/id-sets")).json()).sets || []).length === setsBefore + 2;
       steps.sameCounts = JSON.stringify(await counts()) === JSON.stringify(before);
       const lines = await sp.$$eval(".lockline", (ls) => ls.map((l) => l.innerText.replace(/\s+/g, " ")));
       steps.unchanged = lines.length === 2 && lines.every((l) => /locked \d+ \w+ \d{4}/.test(l) && /unchanged since/.test(l));
@@ -1655,7 +1658,7 @@ async function main() {
       steps.lockAllBack = await sp.locator(".lockall").isVisible();
     } catch (e) { steps.error = String(e.message || e).slice(0, 160); }
     ok("locking all cohorts freezes them and their arms at one moment, keeps the counts, says nothing moved since; one cohort unlocks on its own",
-      steps.locked && steps.arms && steps.sameCounts && steps.unchanged && steps.header && steps.unlockedOne && steps.lockAllBack, JSON.stringify(steps));
+      steps.locked && steps.arms && steps.oneRowEach && steps.sameCounts && steps.unchanged && steps.header && steps.unlockedOne && steps.lockAllBack, JSON.stringify(steps));
     await ctx.close();
   }
   // A cohort with something to save — never saved, or re-split since — offers "save" in its gear
diff --git a/lib/analysis.ts b/lib/analysis.ts
index 50cd47d4..2f70140b 100644
--- a/lib/analysis.ts
+++ b/lib/analysis.ts
@@ -6,7 +6,7 @@
 // oncoprint — the one view whose output is patients — carries the cohort SQL and
 // re-derives its columns inside the owning database.
 // Deliberately deferred: cross-study patient dedup and attribute harmonization.
-import { applyLocks, lockDate } from "./cohort-lock.ts";
+import { applyLocks, lockDate, lockSamples } from "./cohort-lock.ts";
 import { chQuery, STUDY, PRIMARY, type ChConn } from "./ch.ts";
 import { sq } from "./compiler.ts";
 import { describeCohortDef } from "./cohort2.ts";
@@ -322,12 +322,12 @@ export async function runAnalysis(template: AnalysisDoc | TemplateDoc, opts: Run
     if (!cohorts[name] || !live) continue;
     const liveDef = live.cohorts[name];
     const d: LockDrift = { cohort: l.cohort, at: l.lock.at, ...(l.lock.dataVersion ? { dataVersion: l.lock.dataVersion } : {}),
-      n: l.members.n, present: 0, now: 0, entered: 0, left: 0, newSamples: l.members.samples ? 0 : null };
+      n: l.members.n, present: 0, now: 0, entered: 0, left: 0, newSamples: lockSamples(l.members) ? 0 : null };
     try {
       for (const s of cohorts[name].studies) {
         const res = resolvers[s];
         if (!(res instanceof PatientLevelResolver)) throw new Error(s + " is not held at patient level here");
-        const r = await res.lockDrift(doc.cohorts[name], liveDef, l.members.samples ?? null);
+        const r = await res.lockDrift(doc.cohorts[name], liveDef, lockSamples(l.members));
         d.present += r.present; d.now += r.now; d.entered += r.entered; d.left += r.left;
         if (d.newSamples != null) d.newSamples = r.newSamples == null ? null : d.newSamples + r.newSamples;
       }
diff --git a/lib/cohort-lock-server.ts b/lib/cohort-lock-server.ts
index 0f185610..064723d2 100644
--- a/lib/cohort-lock-server.ts
+++ b/lib/cohort-lock-server.ts
@@ -60,8 +60,8 @@ export async function lockCohorts(principal: string, input: { doc: unknown; coho
     }
     return { study, res };
   };
-  /** one cohort's or arm's members now, per study, saved as a stored set (and its samples, when asked) */
-  const freeze = async (name: string, owner: string, withSamples: boolean): Promise<LockedMembers> => {
+  /** one cohort's or arm's members now, per study: its patients, and their samples when asked */
+  const members = async (name: string, withSamples: boolean) => {
     const def = doc.cohorts[name];
     const patients: Record<string, string[]> = {}, samples: Record<string, string[]> = {};
     for (const s of cohortStudies(def, docStudy)) {
@@ -69,23 +69,29 @@ export async function lockCohorts(principal: string, input: { doc: unknown; coho
       patients[study] = await res.members(def);
       if (withSamples) samples[study] = await res.memberSamples(def);
     }
-    const label = name + " — locked " + lockDate(at);
-    const count = (m: Record<string, string[]>) => Object.values(m).reduce((n, x) => n + x.length, 0);
-    const source = (ids: number) => ({ idsIn: ids, unmatched: 0, duplicates: 0, multiStudy: 0, lockOf: lockOf(owner) });
-    const p = await saveIdSet(principal, { name: label, level: "patient", perStudy: patients, source: source(count(patients)) }, { allowEmpty: true });
-    if (!withSamples) return { set: p.id, n: p.count };
-    const sm = await saveIdSet(principal, { name: label + " (samples)", level: "sample", perStudy: samples, source: source(count(samples)) }, { allowEmpty: true });
-    return { set: p.id, n: p.count, samples: sm.id, nSamples: sm.count };
+    return { patients, samples };
   };
+  const size = (m: Record<string, string[]>) => Object.values(m).reduce((n, x) => n + new Set(x).size, 0);
 
   const locks: Record<string, CohortLock> = {};
   for (const name of names) {
-    const top = await freeze(name, name, true);
+    // ONE stored set per locked cohort: its patients, and as parts their samples and each arm's patients
+    const top = await members(name, true);
+    const parts: Record<string, Record<string, string[]>> = { samples: top.samples };
     const children: Record<string, LockedMembers> = {};
     // its split arms, at every depth: "<name> / <split> / <arm>[ / <split> / <arm> …]"
-    for (const child of Object.keys(doc.cohorts).filter((n) => n.startsWith(name + " / ") && !authored.includes(n)))
-      children[child.slice(name.length + 3)] = await freeze(child, name, false);
-    locks[name] = { ...top, at, dataVersion: version, oncokbPin: pin ?? null, ...(Object.keys(children).length ? { children } : {}) };
+    for (const child of Object.keys(doc.cohorts).filter((n) => n.startsWith(name + " / ") && !authored.includes(n))) {
+      const rel = child.slice(name.length + 3), part = "arm:" + rel;
+      parts[part] = (await members(child, false)).patients;
+      children[rel] = { set: "", part, n: size(parts[part]) };
+    }
+    const set = await saveIdSet(principal, {
+      name: name + " — locked " + lockDate(at), level: "patient", perStudy: top.patients, parts,
+      source: { idsIn: size(top.patients), unmatched: 0, duplicates: 0, multiStudy: 0, lockOf: lockOf(name) },
+    }, { allowEmpty: true });
+    for (const c of Object.values(children)) c.set = set.id;
+    locks[name] = { set: set.id, n: set.count, nSamples: set.parts?.samples ?? 0, at, dataVersion: version, oncokbPin: pin ?? null,
+      ...(Object.keys(children).length ? { children } : {}) };
   }
   return { at, dataVersion: version, oncokbPin: pin ?? null, locks };
 }
diff --git a/lib/cohort-lock.ts b/lib/cohort-lock.ts
index 5c53248e..e2a5f406 100644
--- a/lib/cohort-lock.ts
+++ b/lib/cohort-lock.ts
@@ -16,8 +16,15 @@
 import type { AnalysisDoc, CohortDef, CohortLock, LockedMembers } from "./types.ts";
 
 /** The clause a locked cohort or arm compiles to: its patients when it was locked. */
-export function lockClause(m: LockedMembers): { kind: "patientList"; set: string } {
-  return { kind: "patientList", set: m.set };
+export function lockClause(m: LockedMembers): { kind: "patientList"; set: string; part?: string } {
+  return { kind: "patientList", set: m.set, ...(m.part ? { part: m.part } : {}) };
+}
+
+/** Where a lock's samples are, to measure new samples against: its set's "samples" part, a separate
+ *  set (locks made before parts), or nowhere (an arm's lock records none). */
+export function lockSamples(m: LockedMembers): { set: string; part: string } | null {
+  if (m.samples) return { set: m.samples, part: "" };
+  return m.nSamples != null && !m.part ? { set: m.set, part: "samples" } : null;
 }
 
 /** What a locked name is evaluated from, and what its definition still says. */
@@ -65,6 +72,7 @@ function validMembers(m: unknown, name: string): LockedMembers {
   const x = (m && typeof m === "object" ? m : {}) as Partial<LockedMembers>;
   if (typeof x.set !== "string" || !UUID.test(x.set)) throw new Error("cohort “" + name + "” is locked, but its lock names no stored set of patients");
   if (!Number.isInteger(x.n) || (x.n as number) < 0) throw new Error("cohort “" + name + "” is locked, but its lock does not say how many patients it froze");
+  if (x.part !== undefined && (typeof x.part !== "string" || !x.part)) throw new Error("cohort “" + name + "” is locked, but its lock names a part that is not a name");
   return x as LockedMembers;
 }
 
diff --git a/lib/cohort2.ts b/lib/cohort2.ts
index 2a0da726..94d00247 100644
--- a/lib/cohort2.ts
+++ b/lib/cohort2.ts
@@ -376,9 +376,11 @@ function listMembership(leaf: SampleListLeaf | PatientListLeaf, ctx: Ctx, col: s
   const { kind } = leaf;
   if (leaf.set !== undefined && leaf.ids !== undefined) throw new Error(kind + " clause takes ids or a stored set, not both");
   const level = kind === "sampleList" ? "sample" : "patient";
+  if (leaf.part !== undefined && leaf.set === undefined) throw new Error(kind + " clause: part names a part of a stored set, so it needs set");
   if (leaf.set !== undefined) {
     if (typeof leaf.set !== "string" || !ID_SET_UUID.test(leaf.set)) throw new Error(kind + " clause: set must be a stored id set's id (a uuid)");
-    const table = idSetTable(leaf.set, ctx.study, level);
+    if (leaf.part !== undefined && (typeof leaf.part !== "string" || !leaf.part)) throw new Error(kind + " clause: part must name a part of the set");
+    const table = idSetTable(leaf.set, ctx.study, level, leaf.part ?? "");
     return table && PID(col, ctx.study) + " IN (SELECT id FROM " + table + ")";
   }
   requireQualifiedIds(leaf.ids, kind);
@@ -422,13 +424,13 @@ export function memberSamplesSql(patientsSql: string, study: string, db: string)
  * How far the data has moved from a locked cohort, in `study`: of the frozen patients
  * (`lockedSql`) how many the data still holds, what the definition (`liveSql`) selects now, who it
  * would add and who it would drop, and how many samples the frozen patients have that were not
- * theirs when locked (`samplesSet`, the lock's sample set; null when the lock recorded none).
+ * theirs when locked (`samples`, where the lock keeps them; null when it recorded none).
  */
-export function lockDriftSql(lockedSql: string, liveSql: string, study: string, db: string, samplesSet: string | null): string {
+export function lockDriftSql(lockedSql: string, liveSql: string, study: string, db: string, samples: { set: string; part: string } | null): string {
   const pid = PID("patient_unique_id", study), sid = PID("sample_unique_id", study);
   let newSamples = "toInt64(-1)";
-  if (samplesSet) {
-    const table = idSetTable(samplesSet, study, "sample");
+  if (samples) {
+    const table = idSetTable(samples.set, study, "sample", samples.part);
     newSamples = "(SELECT count() FROM " + db + ".sample_derived WHERE cancer_study_identifier = " + sq(study) +
       " AND " + pid + " IN (SELECT pid FROM locked)" + (table ? " AND " + sid + " NOT IN (SELECT id FROM " + table + ")" : "") + ")";
   }
diff --git a/lib/dsl-reference.ts b/lib/dsl-reference.ts
index f0b42dd7..7955609f 100644
--- a/lib/dsl-reference.ts
+++ b/lib/dsl-reference.ts
@@ -1284,8 +1284,8 @@ cohortDef := { "all": [clause × 0-8],         // ANDed; [] means every patient
                "notes"?:   "<prose>",         // the analyst's own note on this cohort; never compiled
                "from"?:    { "saved": "<id>", "name": "<name>", "hash": "<sha256>", "savedAt"?: "<when>" },  // set by the page: the saved cohort this was copied from, and the hash of what was copied; never compiled
                "splits"?:  { "<name>": splitDef },  // divisions of this cohort into arms that add up to it
-               "lock"?:    { "set": "<id set>", "n": N, "samples"?: "<id set>", "nSamples"?: N, "at": "<ISO time>",
-                             "dataVersion"?: "…", "oncokbPin"?: "…", "children"?: { "<split> / <arm>": { "set", "n" } } } }
+               "lock"?:    { "set": "<id set>", "n": N, "nSamples"?: N, "at": "<ISO time>", "dataVersion"?: "…", "oncokbPin"?: "…",
+                             "children"?: { "<split> / <arm>": { "set", "part": "arm:<split> / <arm>", "n" } } } }
                                               // frozen to the patients it selected at "at" — see "Locked cohorts" below
 splitDef  := { "arms": [ { "name": "<label>", "where": clause, "splits"?: {…} } × 1-8 ],  // tested in order; first match wins; an arm may be split again
                "other"?: "<label>",            // the remainder's name, default "Other"
@@ -1380,8 +1380,10 @@ describes for every other identifier-bearing path.
 
 **Locked cohorts.** A cohort can be frozen to the patients its definition selects at one moment,
 so an analysis stops drifting as patients are added to the data: \`lock\` names the stored id set
-of those patients (and of their samples), when it was taken, the data version and OncoKB release
-then, and, under \`children\`, the frozen patients of each of its split arms by name. The engine
+holding those patients, when it was taken, the data version and OncoKB release then, and, under
+\`children\`, each split arm by name. The lock is ONE set: beside the patients it keeps, as named
+parts, their samples (\`"samples"\`, \`nSamples\` of them) and each arm's patients (\`part\`:
+\`"arm:<split> / <arm>"\`). The engine
 evaluates the set, not the definition; the definition stays as the record of how the cohort was
 made, and is still run beside the set, so the result's \`cohorts[name].lock\` says how far the
 data has moved: what the definition selects \`now\`, who it would add (\`entered\`) or drop
diff --git a/lib/federation.ts b/lib/federation.ts
index 905dc981..9dae5189 100644
--- a/lib/federation.ts
+++ b/lib/federation.ts
@@ -2005,8 +2005,8 @@ export class PatientLevelResolver extends BaseResolver implements PatientLevelCa
    * How far the data has moved from a locked cohort (lib/cohort-lock.ts): counts only, but over the
    * frozen patients' ids, so patient-level only, as members() is.
    */
-  async lockDrift(locked: CohortDef, live: CohortDef, samplesSet: string | null): Promise<{ present: number; now: number; entered: number; left: number; newSamples: number | null; sql: string }> {
-    const sql = lockDriftSql(this.cohortSql(locked), this.cohortSql(live), this.study, this.instance.conn.db, samplesSet);
+  async lockDrift(locked: CohortDef, live: CohortDef, samples: { set: string; part: string } | null): Promise<{ present: number; now: number; entered: number; left: number; newSamples: number | null; sql: string }> {
+    const sql = lockDriftSql(this.cohortSql(locked), this.cohortSql(live), this.study, this.instance.conn.db, samples);
     const r = (await this.runLogged<ChRow>("lock: drift since locked", sql, this.instance.conn)).data[0];
     const ns = Number(r.newSamples);
     return { present: Number(r.present), now: Number(r.now), entered: Number(r.entered), left: Number(r.left), newSamples: ns < 0 ? null : ns, sql };
diff --git a/lib/id-set-store.ts b/lib/id-set-store.ts
index cef27f52..e6e4e3a1 100644
--- a/lib/id-set-store.ts
+++ b/lib/id-set-store.ts
@@ -25,6 +25,10 @@ export interface IdSetSource {
 
 export interface IdSetMeta {
   id: string; name: string; owner: string; ownerEmail: string; level: IdSetLevel;
+  /** "list": ids someone gave; "lock": what a cohort selected when locked, with its other parts */
+  kind: "list" | "lock";
+  /** a lock's other lists and their sizes: "samples", "arm:<split> / <arm>" */
+  parts: Record<string, number> | null;
   studies: string[]; count: number; perStudy: Record<string, number>; sha256: string; source: IdSetSource;
   createdAt: string; updatedAt: string; deletedAt: string | null;
   sharing: Sharing & { groupName: string | null };
@@ -33,7 +37,7 @@ export interface IdSetMeta {
 }
 
 interface SetRow extends Shareable {
-  id: string; name: string; level: IdSetLevel; studies: string[]; id_count: number; per_study: Record<string, number>;
+  id: string; name: string; level: IdSetLevel; kind: "list" | "lock"; parts: Record<string, number> | null; studies: string[]; id_count: number; per_study: Record<string, number>;
   sha256: string; source: IdSetSource; created_at: string; updated_at: string; deleted_at: string | null;
   owner_email: string; group_name: string | null;
 }
@@ -41,7 +45,7 @@ interface SetRow extends Shareable {
 /** The most ids one set holds: what one upload may hold (lib/custom-data-server.ts RESOLVE_LIMIT). */
 export const ID_SET_MAX = 250_000;
 
-const ROW = "select s.id, s.name, s.owner_id, s.level, s.studies, s.id_count, s.per_study, s.sha256, s.source, s.visibility, s.group_id," +
+const ROW = "select s.id, s.name, s.owner_id, s.level, s.kind, s.parts, s.studies, s.id_count, s.per_study, s.sha256, s.source, s.visibility, s.group_id," +
   " s.group_can_edit, s.created_at, s.updated_at, s.deleted_at, u.email as owner_email, g.name as group_name from id_set s" +
   " left join app_user u on u.id = s.owner_id left join user_group g on g.id = s.group_id";
 
@@ -49,7 +53,7 @@ const ROW = "select s.id, s.name, s.owner_id, s.level, s.studies, s.id_count, s.
 const iso = (x: unknown): string => x instanceof Date ? x.toISOString() : String(x);
 
 const metaOf = (r: SetRow, principal: string, groups: Set<string>): IdSetMeta => ({
-  id: r.id, name: r.name, owner: r.owner_id ?? "", ownerEmail: r.owner_email ?? "", level: r.level,
+  id: r.id, name: r.name, owner: r.owner_id ?? "", ownerEmail: r.owner_email ?? "", level: r.level, kind: r.kind ?? "list", parts: r.parts ?? null,
   studies: r.studies, count: r.id_count, perStudy: r.per_study, sha256: r.sha256, source: r.source,
   createdAt: iso(r.created_at), updatedAt: iso(r.updated_at), deletedAt: r.deleted_at ? iso(r.deleted_at) : null,
   sharing: { ...sharingOf(r), groupName: r.group_name }, rights: rightsOf(principal, r, groups)
@@ -82,42 +86,58 @@ export async function getIdSet(principal: string, id: string): Promise<IdSetMeta
   return metaOf(r, principal, groups);
 }
 
-/** One set's members, per study. Refuses a deleted set; logged. */
-export async function readIdSet(principal: string, id: string): Promise<{ meta: IdSetMeta; perStudy: Record<string, string[]> }> {
+type PerStudy = Record<string, string[]>;
+const unpack = <T,>(gz: Buffer | null): T | null => gz ? JSON.parse(gunzipSync(Buffer.from(gz)).toString("utf8")) : null;
+
+/** One set's members, per study, and a lock's other parts. Refuses a deleted set; logged. */
+export async function readIdSet(principal: string, id: string): Promise<{ meta: IdSetMeta; perStudy: PerStudy; parts: Record<string, PerStudy> | null }> {
   const { r, groups } = await readable(principal, id);
   if (r.deleted_at) throw new AccessError("stored id set “" + r.name + "” was deleted on " + iso(r.deleted_at).slice(0, 10), 410);
-  const [{ ids_gz }] = await dbQuery<{ ids_gz: Buffer }>("select ids_gz from id_set where id = $1", [r.id]);
+  const [{ ids_gz, parts_gz }] = await dbQuery<{ ids_gz: Buffer; parts_gz: Buffer | null }>("select ids_gz, parts_gz from id_set where id = $1", [r.id]);
   await log(principal, "read", r.id);
-  return { meta: metaOf(r, principal, groups), perStudy: JSON.parse(gunzipSync(Buffer.from(ids_gz)).toString("utf8")) };
+  return { meta: metaOf(r, principal, groups), perStudy: unpack<PerStudy>(ids_gz)!, parts: unpack<Record<string, PerStudy>>(parts_gz) };
 }
 
+/** Distinct, sorted ids per study, empty studies dropped. */
+function tidy(m: PerStudy): PerStudy {
+  const out: PerStudy = {};
+  for (const study of Object.keys(m).sort()) {
+    const ids = [...new Set(m[study].map(String))].sort();
+    if (ids.length) out[study] = ids;
+  }
+  return out;
+}
+const sizeOf = (m: PerStudy) => Object.values(m).reduce((n, x) => n + x.length, 0);
+
 /**
  * Save a set: members already matched to the studies' own ids (lib/id-set-import.ts), as bare
  * ids per study. Empty studies are dropped; a set with no members at all is refused unless
  * `allowEmpty` (a lock freezing a cohort or arm that held nobody).
  */
-export async function saveIdSet(principal: string, input: { name: string; level: IdSetLevel; perStudy: Record<string, string[]>; source: IdSetSource },
+export async function saveIdSet(principal: string, input: { name: string; level: IdSetLevel; perStudy: Record<string, string[]>; source: IdSetSource;
+  /** a lock's other lists, kept in the same row (db/migrations/0007) */
+  parts?: Record<string, PerStudy> },
   opts: { allowEmpty?: boolean } = {}): Promise<IdSetMeta> {
   const name = String(input.name ?? "").trim().slice(0, 200);
   if (!name) throw new Error("a stored id set needs a name");
   if (input.level !== "patient" && input.level !== "sample") throw new Error("level must be 'patient' or 'sample'");
-  const perStudy: Record<string, string[]> = {};
-  for (const study of Object.keys(input.perStudy).sort()) {
-    const ids = [...new Set(input.perStudy[study].map(String))].sort();
-    if (ids.length) perStudy[study] = ids;
-  }
+  const perStudy = tidy(input.perStudy);
   const studies = Object.keys(perStudy);
-  const count = studies.reduce((n, s) => n + perStudy[s].length, 0);
+  const count = sizeOf(perStudy);
+  const parts = input.parts ? Object.fromEntries(Object.entries(input.parts).map(([k, m]) => [k, tidy(m)])) : null;
   // a pasted list that matched nothing is a mistake; a locked arm that held nobody is a fact (lib/cohort-lock-server.ts)
   if (!count && !opts.allowEmpty) throw new Error("none of the ids matched a " + input.level + " of the studies given; nothing to save");
   if (count > ID_SET_MAX) throw new Error("a stored id set holds at most " + ID_SET_MAX.toLocaleString("en-US") + " ids; this one has " + count.toLocaleString("en-US"));
   const json = JSON.stringify(perStudy);
   const id = randomUUID();
+  const partsJson = parts ? JSON.stringify(parts) : null;
   await dbQuery(
-    "insert into id_set (id, name, owner_id, level, studies, id_count, per_study, ids_gz, sha256, source)" +
-    " values ($1::uuid, $2, $3::uuid, $4, $5::text[], $6::int, $7::jsonb, $8::bytea, $9, $10::jsonb)",
+    "insert into id_set (id, name, owner_id, level, studies, id_count, per_study, ids_gz, sha256, source, kind, parts, parts_gz)" +
+    " values ($1::uuid, $2, $3::uuid, $4, $5::text[], $6::int, $7::jsonb, $8::bytea, $9, $10::jsonb, $11, $12::jsonb, $13::bytea)",
     [id, name, principal, input.level, studies, count, JSON.stringify(Object.fromEntries(studies.map((s) => [s, perStudy[s].length]))),
-      gzipSync(json, { level: 6 }), createHash("sha256").update(json).digest("hex"), JSON.stringify(input.source)]);
+      gzipSync(json, { level: 6 }), createHash("sha256").update(json + (partsJson ?? "")).digest("hex"), JSON.stringify(input.source),
+      parts ? "lock" : "list", parts ? JSON.stringify(Object.fromEntries(Object.entries(parts).map(([k, m]) => [k, sizeOf(m)]))) : null,
+      partsJson ? gzipSync(partsJson, { level: 6 }) : null]);
   await log(principal, "create", id);
   return metaOf((await one(id))!, principal, await groupsOf(principal));
 }
@@ -177,7 +197,8 @@ export async function loadIdSetForRequest(principal: string, id: string): Promis
   if (hit && (accessSeen.get(who) ?? 0) > now - ACCESS_TTL_MS) return hit;
   const r = await readIdSet(principal, id);   // checks access, refuses a deleted set, logs
   accessSeen.set(who, now);
-  const entry: LoadedIdSet = hit ?? { id: r.meta.id, name: r.meta.name, level: r.meta.level, count: r.meta.count, perStudy: r.perStudy };
+  const entry: LoadedIdSet = hit ?? { id: r.meta.id, name: r.meta.name, level: r.meta.level, count: r.meta.count, perStudy: r.perStudy,
+    ...(r.parts ? { parts: r.parts } : {}) };
   cache.delete(id); cache.set(id, entry);
   while (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value!);
   return entry;
diff --git a/lib/id-sets.ts b/lib/id-sets.ts
index 98082767..f569db3e 100644
--- a/lib/id-sets.ts
+++ b/lib/id-sets.ts
@@ -29,30 +29,43 @@ export interface LoadedIdSet {
   level: IdSetLevel;
   count: number;
   perStudy: Record<string, string[]>;
+  /** a lock's other lists in the same set: "samples" (sample ids), "arm:<split> / <arm>" (patient ids) */
+  parts?: Record<string, Record<string, string[]>>;
 }
 
+/** The level of a set's part: the set's own for its main list, samples for "samples", patients for an arm. */
+function partLevel(s: LoadedIdSet, part: string): IdSetLevel {
+  return !part ? s.level : part === "samples" ? "sample" : "patient";
+}
+const membersOf = (s: LoadedIdSet, part: string): Record<string, string[]> | undefined => part ? s.parts?.[part] : s.perStudy;
+
 interface IdSetCtx {
   sets: Map<string, LoadedIdSet>;
   /** study -> the connection id of the patient-level instance holding it */
   studyConn: Map<string, string>;
-  /** external table name -> what it uploads, and where it may go */
-  tables: Map<string, { set: string; study: string; data?: string }>;
+  /** external table name -> what it uploads (a set's main list or one of its parts), and where it may go */
+  tables: Map<string, { set: string; study: string; part: string; data?: string }>;
 }
 const store = new AsyncLocalStorage<IdSetCtx>();
 
 export const ID_SET_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 export const ID_SET_STRUCTURE = "id String";
 
-/** The external table holding one set's ids for one study. Stable, so its SQL can be read and cached by name. */
-export function idSetTableName(set: string, study: string): string {
-  return "_idset_" + set.replace(/-/g, "") + "_" + createHash("sha256").update(study).digest("hex").slice(0, 10);
+/** The external table holding one set's ids (or one part's) for one study. Stable, so its SQL can be read and cached by name. */
+export function idSetTableName(set: string, study: string, part = ""): string {
+  const h = (x: string, n: number) => createHash("sha256").update(x).digest("hex").slice(0, n);
+  return "_idset_" + set.replace(/-/g, "") + "_" + h(study, 10) + (part ? "_" + h(part, 8) : "");
 }
 
 /** Run `fn` with these sets readable by the compiler. */
 export function withIdSets<T>(sets: LoadedIdSet[], studyConn: Map<string, string>, fn: () => Promise<T>): Promise<T> {
   if (!sets.length) return fn();
-  const tables = new Map<string, { set: string; study: string }>();
-  for (const s of sets) for (const study of Object.keys(s.perStudy)) tables.set(idSetTableName(s.id, study), { set: s.id, study });
+  const tables = new Map<string, { set: string; study: string; part: string }>();
+  for (const s of sets) {
+    for (const study of Object.keys(s.perStudy)) tables.set(idSetTableName(s.id, study), { set: s.id, study, part: "" });
+    for (const [part, m] of Object.entries(s.parts || {}))
+      for (const study of Object.keys(m)) tables.set(idSetTableName(s.id, study, part), { set: s.id, study, part });
+  }
   return store.run({ sets: new Map(sets.map((s) => [s.id, s])), studyConn, tables }, fn);
 }
 
@@ -79,14 +92,17 @@ export function idSetIfLoaded(set: string): LoadedIdSet | null {
 }
 
 /**
- * The table a compiled statement reads one set's ids for `study` from, or null when the set holds
- * no ids for that study (most of a cross-study set belongs to the other studies of the fan-out).
+ * The table a compiled statement reads one set's ids — or one of its parts' — for `study` from, or
+ * null when it holds no ids for that study (most of a cross-study set belongs to the other studies
+ * of the fan-out).
  */
-export function idSetTable(set: string, study: string, level: IdSetLevel): string | null {
+export function idSetTable(set: string, study: string, level: IdSetLevel, part = ""): string | null {
   const s = loadedIdSet(set);
-  if (s.level !== level)
-    throw new Error("stored id set “" + s.name + "” holds " + s.level + " ids; name it in a " + s.level + "List clause, not a " + level + "List");
-  return s.perStudy[study]?.length ? idSetTableName(set, study) : null;
+  if (part && !s.parts?.[part]) throw new Error("stored id set “" + s.name + "” has no part “" + part + "”");
+  const l = partLevel(s, part);
+  if (l !== level)
+    throw new Error("stored id set “" + s.name + "”" + (part ? " (" + part + ")" : "") + " holds " + l + " ids; name it in a " + l + "List clause, not a " + level + "List");
+  return membersOf(s, part)?.[study]?.length ? idSetTableName(set, study, part) : null;
 }
 
 const tsv = (s: string) => s.replace(/\\/g, "\\\\").replace(/\t/g, "\\t").replace(/\n/g, "\\n").replace(/\r/g, "\\r");
@@ -100,7 +116,7 @@ export function idSetExternalsFor(query: string, connId: string): { name: string
     if (!new RegExp("(^|[^A-Za-z0-9_])" + name + "([^A-Za-z0-9_]|$)").test(query)) continue;
     if (s.studyConn.get(t.study) !== connId)
       throw new Error("stored id set " + t.set + " holds patient-level ids for " + t.study + ", which cannot be sent to instance '" + connId + "'");
-    t.data ??= s.sets.get(t.set)!.perStudy[t.study].map(tsv).join("\n") + "\n";
+    t.data ??= membersOf(s.sets.get(t.set)!, t.part)![t.study].map(tsv).join("\n") + "\n";
     out.push({ name, structure: ID_SET_STRUCTURE, data: t.data });
   }
   return out;
diff --git a/lib/types.ts b/lib/types.ts
index 224cd9c7..f14a341c 100644
--- a/lib/types.ts
+++ b/lib/types.ts
@@ -61,10 +61,11 @@ export interface ClinicalLeaf {
  * `set` instead of `ids` names a stored id set (lib/id-set-store.ts) by its id: the same list,
  * kept on the server, so the document carries a uuid however many ids the set holds. `label` and
  * `n` are its name and size as the page wrote them, for the cohort's pill; never compiled — the
- * readback names the set from the store.
+ * readback names the set from the store. `part` names one of a lock's other lists in that set
+ * (a split arm's patients, "arm:<split> / <arm>"); the engine writes it, from a cohort's `lock`.
  */
-export interface SampleListLeaf { kind: "sampleList"; ids?: string[]; set?: string; label?: string; n?: number }
-export interface PatientListLeaf { kind: "patientList"; ids?: string[]; set?: string; label?: string; n?: number }
+export interface SampleListLeaf { kind: "sampleList"; ids?: string[]; set?: string; part?: string; label?: string; n?: number }
+export interface PatientListLeaf { kind: "patientList"; ids?: string[]; set?: string; part?: string; label?: string; n?: number }
 /**
  * A fixed, engine-owned half of the study's patients: a salted hash of the study-qualified
  * patient id decides the half, so the partition is reproducible, identical for every caller,
@@ -233,12 +234,19 @@ export interface CohortDef {
 
 export interface CohortSource { saved: string; name: string; hash: string; savedAt?: string }
 
-/** A cohort's (or a split arm's) members when it was locked: stored id sets (lib/id-set-store.ts). */
+/**
+ * A cohort's (or a split arm's) members when it was locked, in a stored id set (lib/id-set-store.ts).
+ * A lock is one set: the cohort's patients are its main list, and beside them, as named parts, the
+ * patients' samples ("samples") and each arm's patients (`part`, "arm:<split> / <arm>").
+ */
 export interface LockedMembers {
-  /** a patient-level stored set: the patients it selected */
+  /** the stored set holding the patients */
   set: string;
+  /** the part of `set` holding them, for an arm; absent for the cohort itself */
+  part?: string;
   n: number;
-  /** a sample-level stored set: those patients' samples then, what "new samples since" is measured against */
+  /** how many samples those patients had then, kept in the set's "samples" part — what "new samples
+   *  since" is measured against. Locks made before parts name a separate sample-level set here. */
   samples?: string;
   nSamples?: number;
 }
diff --git a/test/cohort-lock.test.ts b/test/cohort-lock.test.ts
index 989eedaa..435c683e 100644
--- a/test/cohort-lock.test.ts
+++ b/test/cohort-lock.test.ts
@@ -3,17 +3,20 @@
 // frozen cohort; the sets a lock names are read for its request, and never go where ids may not.
 import { test, describe } from "node:test";
 import assert from "node:assert/strict";
-import { applyLocks, lockDate } from "../lib/cohort-lock.ts";
+import { applyLocks, lockDate, lockSamples } from "../lib/cohort-lock.ts";
 import { resolveExtends } from "../lib/cohort-extends.ts";
 import { compileCohortDef } from "../lib/cohort2.ts";
-import { withIdSets, idSetRefsIn, idSetTableName } from "../lib/id-sets.ts";
+import { withIdSets, idSetRefsIn, idSetTableName, idSetExternalsFor } from "../lib/id-sets.ts";
 import { carriesPatientIds } from "../lib/federation.ts";
 import { lockDriftSql } from "../lib/cohort2.ts";
 import type { AnalysisDoc, CohortLock } from "../lib/types.ts";
 
 const P = "11111111-1111-4111-8111-111111111111", S = "22222222-2222-4222-8222-222222222222", F = "33333333-3333-4333-8333-333333333333";
-const lock: CohortLock = { set: P, n: 3, samples: S, nSamples: 4, at: "2026-10-18T16:30:00.000Z", dataVersion: "v1", oncokbPin: "v7.5",
-  children: { "sex / Female": { set: F, n: 1 } } };
+// a lock is ONE set: the patients, and as parts their samples and each arm's patients
+const lock: CohortLock = { set: P, n: 3, nSamples: 4, at: "2026-10-18T16:30:00.000Z", dataVersion: "v1", oncokbPin: "v7.5",
+  children: { "sex / Female": { set: P, part: "arm:sex / Female", n: 1 } } };
+// one made before parts: its samples and its arm in sets of their own
+const oldLock: CohortLock = { set: P, n: 3, samples: S, nSamples: 4, at: "2026-10-18T16:30:00.000Z", children: { "sex / Female": { set: F, n: 1 } } };
 const KRAS = { kind: "oql" as const, q: "KRAS: MUT" };
 const female = { kind: "clinical" as const, attribute: "SEX", values: ["Female"] };
 // a document as runAnalysis has it after splits are expanded: the arms `extends` their cohort
@@ -28,7 +31,7 @@ describe("applyLocks", () => {
   test("a locked cohort, and its locked arm, become their sets; the rest keep their definitions", () => {
     const { doc, locked } = applyLocks(expanded());
     assert.deepEqual(doc.cohorts.A.all, [{ kind: "patientList", set: P }]);
-    assert.deepEqual(doc.cohorts["A / sex / Female"].all, [{ kind: "patientList", set: F }]);
+    assert.deepEqual(doc.cohorts["A / sex / Female"].all, [{ kind: "patientList", set: P, part: "arm:sex / Female" }]);
     assert.equal(doc.cohorts["A / sex / Female"].extends, undefined, "a frozen arm does not inherit its cohort's clauses");
     assert.deepEqual(doc.cohorts.B.all, [KRAS]);
     assert.deepEqual(Object.keys(locked).sort(), ["A", "A / sex / Female"]);
@@ -44,6 +47,10 @@ describe("applyLocks", () => {
     assert.equal(live.cohorts.A.lock, undefined);
     assert.deepEqual(live.cohorts["A / sex / Female"].all, [KRAS, female]);
   });
+  test("a lock made before parts, with its arm in a set of its own, still applies", () => {
+    const d = expanded(); d.cohorts.A.lock = oldLock;
+    assert.deepEqual(applyLocks(d).doc.cohorts["A / sex / Female"].all, [{ kind: "patientList", set: F }]);
+  });
   test("a document with no lock is handed back untouched", () => {
     const d: AnalysisDoc = { cohorts: { B: { all: [KRAS] } } };
     const r = applyLocks(d);
@@ -58,25 +65,35 @@ describe("applyLocks", () => {
 });
 
 describe("a locked cohort compiled anywhere", () => {
-  const sets = (fn: () => string) => withIdSets([{ id: P, name: "A — locked", level: "patient", count: 3, perStudy: { s1: ["P-1", "P-2", "P-3"] } }],
-    new Map([["s1", "a"]]), async () => fn());
+  const lockSet = { id: P, name: "A — locked", level: "patient" as const, count: 3, perStudy: { s1: ["P-1", "P-2", "P-3"] },
+    parts: { samples: { s1: ["S-1", "S-2", "S-3", "S-4"] }, "arm:sex / Female": { s1: ["P-2"] } } };
+  const sets = (fn: () => string) => withIdSets([lockSet], new Map([["s1", "a"]]), async () => fn());
   test("compiles to its frozen set even outside runAnalysis (Explore, an oncoprint spec)", async () => {
     const sql = await sets(() => compileCohortDef({ all: [KRAS], lock }, { study: "s1", db: "db" }));
     assert.match(sql, new RegExp("IN \\(SELECT id FROM " + idSetTableName(P, "s1") + "\\)"));
     assert.doesNotMatch(sql, /KRAS/);
   });
-  test("the drift query measures the frozen set against the definition, and new samples against the frozen samples", async () => {
-    const sql = await withIdSets([{ id: S, name: "A — samples", level: "sample", count: 4, perStudy: { s1: ["S-1"] } }], new Map([["s1", "a"]]),
-      async () => lockDriftSql("SELECT 'P-1' AS pid", "SELECT 'P-9' AS pid", "s1", "db", S));
+  test("a locked arm compiles to its part of the lock's one set, a table of its own", async () => {
+    const sql = await sets(() => compileCohortDef({ all: [{ kind: "patientList", set: P, part: "arm:sex / Female" }] }, { study: "s1", db: "db" }));
+    assert.match(sql, new RegExp("IN \\(SELECT id FROM " + idSetTableName(P, "s1", "arm:sex / Female") + "\\)"));
+    assert.notEqual(idSetTableName(P, "s1", "arm:sex / Female"), idSetTableName(P, "s1"));
+    const ext = await sets(() => JSON.stringify(idSetExternalsFor("SELECT id FROM " + idSetTableName(P, "s1", "arm:sex / Female"), "a")));
+    assert.deepEqual(JSON.parse(ext).map((e: { data: string }) => e.data), ["P-2\n"], "only that arm's patients are uploaded");
+  });
+  test("the drift query measures the frozen set against the definition, and new samples against the lock's samples part", async () => {
+    const sql = await sets(() => lockDriftSql("SELECT 'P-1' AS pid", "SELECT 'P-9' AS pid", "s1", "db", lockSamples(lock)));
     assert.match(sql, /AS entered/);
     assert.match(sql, /AS left/);
-    assert.match(sql, new RegExp("NOT IN \\(SELECT id FROM " + idSetTableName(S, "s1") + "\\)"));
+    assert.match(sql, new RegExp("NOT IN \\(SELECT id FROM " + idSetTableName(P, "s1", "samples") + "\\)"));
+    assert.deepEqual(lockSamples(oldLock), { set: S, part: "" }, "a lock made before parts measures against its own sample set");
+    assert.equal(lockSamples(lock.children!["sex / Female"]), null, "an arm records no samples");
   });
 });
 
 describe("a lock's sets travel with its request, and nowhere ids may not", () => {
-  test("idSetRefsIn finds the patients, samples and arm sets a lock names", () => {
-    assert.deepEqual(idSetRefsIn({ cohorts: { A: { all: [KRAS], lock } } }).sort(), [P, S, F].sort());
+  test("idSetRefsIn finds the one set a lock names, and every set an older lock names", () => {
+    assert.deepEqual(idSetRefsIn({ cohorts: { A: { all: [KRAS], lock } } }), [P]);
+    assert.deepEqual(idSetRefsIn({ cohorts: { A: { all: [KRAS], lock: oldLock } } }).sort(), [P, S, F].sort());
   });
   test("carriesPatientIds counts a locked cohort as ids", () => {
     assert.equal(carriesPatientIds({ all: [KRAS], lock }), true);
diff --git a/test/postgres.db-test.ts b/test/postgres.db-test.ts
index 994d6bcf..89d377f4 100644
--- a/test/postgres.db-test.ts
+++ b/test/postgres.db-test.ts
@@ -17,7 +17,7 @@ const db: PGlite = await startPostgres();
 
 describe("migrations", () => {
   test("apply in order to an empty database, and again without harm", async () => {
-    assert.deepEqual(migrationFiles(), ["0001_saved_artifacts.sql", "0002_campaigns.sql", "0003_custom_datasets.sql", "0004_users.sql", "0005_sharing.sql", "0006_id_sets.sql"]);
+    assert.deepEqual(migrationFiles(), ["0001_saved_artifacts.sql", "0002_campaigns.sql", "0003_custom_datasets.sql", "0004_users.sql", "0005_sharing.sql", "0006_id_sets.sql", "0007_id_set_parts.sql"]);
     const tables = async () => (await db.query<{ t: string }>(
       "select table_name as t from information_schema.tables where table_schema = 'public' order by 1")).rows.map((r) => r.t);
     const before = await tables();
diff --git a/test/support/store-contracts.ts b/test/support/store-contracts.ts
index d3eccee0..40591472 100644
--- a/test/support/store-contracts.ts
+++ b/test/support/store-contracts.ts
@@ -129,6 +129,19 @@ export function idSetContract(backend: string): void {
       await assert.rejects(readIdSet(P, meta.id), /was deleted on \d{4}-\d{2}-\d{2}/);
     });
 
+    test("a lock is one row: its patients, and its samples and arms as parts, read back exactly", async () => {
+      const meta = await saveIdSet(P, { ...input("locked"), parts: { samples: { s1: ["S-1-T", "S-2-T"] }, "arm:sex / Female": { s1: ["S-1"] }, "arm:sex / Male": {} } }, { allowEmpty: true });
+      assert.equal(meta.kind, "lock");
+      assert.deepEqual(meta.parts, { samples: 2, "arm:sex / Female": 1, "arm:sex / Male": 0 });
+      const r = await readIdSet(P, meta.id);
+      assert.deepEqual(r.parts?.samples, { s1: ["S-1-T", "S-2-T"] });
+      assert.deepEqual(r.parts?.["arm:sex / Female"], { s1: ["S-1"] });
+      assert.equal((await loadIdSetForRequest(P, meta.id)).parts?.["arm:sex / Female"]?.s1?.[0], "S-1");
+      assert.equal((await saveIdSet(P, input("plain"))).kind, "list");
+      await assert.rejects(dbQuery("update id_set set parts_gz = null where id = $1", [meta.id]), /members are immutable/);
+      await assert.rejects(dbQuery("update id_set set parts = '{}'::jsonb where id = $1", [meta.id]), /members are immutable/);
+    });
+
     test("its members cannot be changed or the row deleted, though its sharing can", async () => {
       const meta = await saveIdSet(P, input("frozen"));
       await assert.rejects(dbQuery("update id_set set id_count = 99 where id = $1", [meta.id]), /members are immutable/);