@milaboratories/pl-middle-layer 1.71.16 → 1.73.0

package/src/mutator/sharing.ts

@@ -1,24 +1,28 @@
 import type { PlTransaction, ResourceRef, SignedResourceId } from "@milaboratories/pl-client";
-import { field, isNotNullSignedResourceId, resourceIdToString } from "@milaboratories/pl-client";
+import { field, isNotNullSignedResourceId } from "@milaboratories/pl-client";
 import { randomUUID } from "node:crypto";
-import type { ProjectMeta } from "@milaboratories/pl-model-middle-layer";
-import type { ProjectId, ProjectTemplateV1 } from "@milaboratories/pl-model-common";
+import type { FolderId, ProjectMeta } from "@milaboratories/pl-model-middle-layer";
+import { normalizeDescription } from "@milaboratories/pl-model-middle-layer";
+import type { ProjectId, ProjectTemplateV1, TemplateId } from "@milaboratories/pl-model-common";
 import { ProjectMetaKey } from "../model/project_model";
 import { duplicateProject } from "./project";
 import type {
   EnvelopeData,
-  EnvelopeAcceptance,
+  EnvelopeFolder,
+  EnvelopeFolderId,
+  EnvelopeFolderProject,
+  EnvelopeFolderTemplate,
   EnvelopeMode,
   EnvelopeProject,
   ProjectFieldUuid,
   ShareId,
-  SharingDecision,
+  ShareHidden,
 } from "../model/sharing_model";
 import {
   EnvelopeSchemaVersionCurrent,
   SharedEnvelopeResourceType,
-  acceptanceField,
-  decisionField,
+  hiddenField,
+  newProjectFieldUuid,
   newShareId,
 } from "../model/sharing_model";
 
@@ -41,20 +45,8 @@ export function envelopeProjectFieldUuid(name: string): ProjectFieldUuid {
 // Donor side
 //
 
-/**
- * One project going into an envelope: `fresh` snapshots a live source (normal path); `carry`
- * re-attaches an existing snapshot (change's "keep", or an "update" whose source is gone).
- */
-export type EnvelopeProjectSource =
-  | { kind: "fresh"; projectId: ProjectId; sourceRid: SignedResourceId }
-  | {
-      kind: "carry";
-      projectId: ProjectId;
-      label: string;
-      snapshotRid: SignedResourceId;
-      /** ms epoch the carried snapshot was last taken; preserved so "keep" keeps its timestamp. */
-      updatedAt: number;
-    };
+/** One live project going into an envelope; it is snapshotted as the envelope is built. */
+export type EnvelopeProjectSource = { projectId: ProjectId; sourceRid: SignedResourceId };
 
 /**
  * Builds one {@link SharedEnvelopeResourceType} on the donor side inside the given write
@@ -75,35 +67,17 @@ export async function buildShareEnvelope(
     title: string;
     /** ms epoch; sharedAt + ttl for a targeted share, null for share-with-everybody. */
     expiresAt: number | null;
-    /** Existing shareId for a change; a fresh one is minted when omitted. */
-    shareId?: ShareId;
-    sharedAt?: number;
   },
 ): Promise<{ envelope: ResourceRef; data: EnvelopeData }> {
-  const shareId = params.shareId ?? newShareId();
-  const sharedAt = params.sharedAt ?? Date.now();
+  const sharedAt = Date.now();
+  const snapshots = await snapshotEnvelopeProjects(tx, sources, sharedAt);
 
-  // Snapshot (fresh) or re-attach (carry) each project, collecting its metadata for the pack.
   const projects: Record<ProjectFieldUuid, EnvelopeProject> = {};
-  const snapshots: { uuid: ProjectFieldUuid; ref: ResourceRef | SignedResourceId }[] = [];
-  for (const src of sources) {
-    const uuid = randomUUID() as ProjectFieldUuid;
-    if (src.kind === "fresh") {
-      const meta = await tx.getKValueJson<ProjectMeta>(src.sourceRid, ProjectMetaKey);
-      const ref = await duplicateProject(tx, src.sourceRid, { label: meta.label });
-      projects[uuid] = { label: meta.label, source: src.projectId, updatedAt: sharedAt }; // (re)snapshotted now
-      snapshots.push({ uuid, ref });
-    } else {
-      // Re-attach the prior snapshot; the new envelope references it before the old one is
-      // detached in the same tx, so it stays alive. Label and timestamp carry unchanged.
-      projects[uuid] = { label: src.label, source: src.projectId, updatedAt: src.updatedAt };
-      snapshots.push({ uuid, ref: src.snapshotRid });
-    }
-  }
+  for (const { uuid, project } of snapshots) projects[uuid] = project;
 
   const data: EnvelopeData = {
     schemaVersion: EnvelopeSchemaVersionCurrent,
-    shareId,
+    shareId: newShareId(),
     sharedAt,
     expiresAt: params.expiresAt,
     mode: params.mode,
@@ -112,20 +86,7 @@ export async function buildShareEnvelope(
     payload: { kind: "projects", projects },
   };
 
-  // Immutable data set once at creation, never altered.
-  const envelope = tx.createEphemeral(SharedEnvelopeResourceType, JSON.stringify(data));
-
-  // Attach the project snapshots as Input fields, then seal the input set one-way.
-  for (const { uuid, ref } of snapshots) {
-    tx.createField(field(envelope, envelopeProjectField(uuid)), "Input", ref);
-  }
-  tx.lockInputs(envelope);
-
-  // Attach to the outbox under {shareId} in the same transaction so the held-resource rule
-  // keeps the ephemeral envelope alive.
-  tx.createField(field(outboxRid, shareId), "Dynamic", envelope);
-
-  return { envelope, data };
+  return { envelope: sealEnvelope(tx, outboxRid, data, snapshots), data };
 }
 
 /**
@@ -142,21 +103,23 @@ export async function buildShareEnvelope(
 export function buildTemplateShareEnvelope(
   tx: PlTransaction,
   outboxRid: SignedResourceId,
-  template: { document: ProjectTemplateV1; label: string },
+  template: {
+    document: ProjectTemplateV1;
+    label: string;
+    description?: string;
+    source: TemplateId;
+  },
   params: {
     sender: string;
     title: string;
     /** ms epoch; sharedAt + ttl for a targeted share, null for share-with-everybody. */
     expiresAt: number | null;
-    /** Existing shareId for a change; a fresh one is minted when omitted. */
-    shareId?: ShareId;
-    sharedAt?: number;
   },
 ): { envelope: ResourceRef; data: EnvelopeData } {
   const data: EnvelopeData = {
     schemaVersion: EnvelopeSchemaVersionCurrent,
-    shareId: params.shareId ?? newShareId(),
-    sharedAt: params.sharedAt ?? Date.now(),
+    shareId: newShareId(),
+    sharedAt: Date.now(),
     expiresAt: params.expiresAt,
     mode: "read-only",
     sender: params.sender,
@@ -164,105 +127,215 @@ export function buildTemplateShareEnvelope(
     payload: {
       kind: "template",
       document: template.document,
+      source: template.source,
       label: template.label,
+      ...(template.description === undefined ? {} : { description: template.description }),
       from: params.sender,
     },
   };
 
-  // Immutable data set once at creation, never altered.
-  const envelope = tx.createEphemeral(SharedEnvelopeResourceType, JSON.stringify(data));
-
-  // Attach to the outbox under {shareId} in the same transaction so the held-resource rule
-  // keeps the ephemeral envelope alive.
-  tx.createField(field(outboxRid, data.shareId), "Dynamic", envelope);
-
-  return { envelope, data };
+  return { envelope: sealEnvelope(tx, outboxRid, data, []), data };
 }
 
 /**
- * Records a response onto the envelope as a dynamic `acceptance/{login}` field: the acceptor
- * writing their own decision (their writable grant permits it), or the donor transferring an
- * existing record onto a changed envelope. Accepts the envelope by ref or id.
+ * Builds one {@link SharedEnvelopeResourceType} carrying a folder subtree: the folders, every
+ * project in them snapshotted as a `project/{uuid}` field, and every template's document inline.
+ * Attaches it under `{shareId}` on the donor's outbox. The caller issues the grant — writable,
+ * because the recipient copies the project snapshots out — and commits.
+ *
+ * Folder ids are minted here and mean nothing outside this envelope: the recipient's own document
+ * mints its own. What travels is the shape of the subtree.
+ *
+ * @returns the new envelope resource and the generated `EnvelopeData`.
  */
-export function writeEnvelopeAcceptance(
+export async function buildFolderShareEnvelope(
   tx: PlTransaction,
-  envelopeRid: ResourceRef | SignedResourceId,
-  login: string,
-  action: EnvelopeAcceptance["action"],
-  timestamp: number,
-): void {
-  const acceptance: EnvelopeAcceptance = { action, timestamp };
-  const value = tx.createJsonValue(acceptance);
-  tx.createField(field(envelopeRid, acceptanceField(login)), "Dynamic", value);
+  outboxRid: SignedResourceId,
+  subtree: EnvelopeFolderSubtree,
+  params: {
+    sender: string;
+    title: string;
+    /** ms epoch; sharedAt + ttl for a targeted share, null for share-with-everybody. */
+    expiresAt: number | null;
+  },
+): Promise<{ envelope: ResourceRef; data: EnvelopeData }> {
+  const sharedAt = Date.now();
+  const snapshots = await snapshotEnvelopeProjects(tx, subtree.projects, sharedAt);
+
+  const projects: Record<ProjectFieldUuid, EnvelopeFolderProject> = {};
+  for (const { uuid, project, source } of snapshots)
+    projects[uuid] = { ...project, folder: source.folder };
+
+  const data: EnvelopeData = {
+    schemaVersion: EnvelopeSchemaVersionCurrent,
+    shareId: newShareId(),
+    sharedAt,
+    expiresAt: params.expiresAt,
+    mode: "copy",
+    sender: params.sender,
+    title: params.title,
+    payload: {
+      kind: "folder",
+      source: subtree.source,
+      folders: subtree.folders,
+      projects,
+      templates: subtree.templates,
+      from: params.sender,
+    },
+  };
+
+  return { envelope: sealEnvelope(tx, outboxRid, data, snapshots), data };
+}
+
+/** A folder subtree ready to be sealed into an envelope: the folders under their envelope-local
+ *  ids, the live projects to snapshot, and the templates to carry whole. */
+export interface EnvelopeFolderSubtree {
+  /** Donor's own id of the shared folder, carried so a later share of it finds this one. */
+  source: FolderId;
+  folders: Record<EnvelopeFolderId, EnvelopeFolder>;
+  projects: (EnvelopeProjectSource & { folder: EnvelopeFolderId })[];
+  templates: EnvelopeFolderTemplate[];
 }
 
 //
-// Acceptor side
+// Recipient side
 //
 
 /**
- * Records the acceptor's decision for a handled share on the acceptor's SharingState as a
- * dynamic `decision/{shareId}` field. Keyed on the logical shareId so discovery dedups on the
- * share, not on the envelope instance.
+ * Puts a share out of this recipient's sight, as a dynamic field on their own SharingState.
+ * Keyed on the shareId, so a share that replaces this one — a new shareId — is shown again.
  */
-export function writeSharingDecision(
+export function writeShareHidden(
+  tx: PlTransaction,
+  stateRid: SignedResourceId,
+  shareId: ShareId,
+  timestamp: number,
+): void {
+  const value = tx.createJsonValue({ hidden: true, timestamp } satisfies ShareHidden);
+  tx.createField(field(stateRid, hiddenField(shareId)), "Dynamic", value);
+}
+
+/** Brings a hidden share back into this recipient's list. */
+export function clearShareHidden(
   tx: PlTransaction,
   stateRid: SignedResourceId,
   shareId: ShareId,
-  decision: SharingDecision,
 ): void {
-  const value = tx.createJsonValue(decision);
-  tx.createField(field(stateRid, decisionField(shareId)), "Dynamic", value);
+  tx.removeField(field(stateRid, hiddenField(shareId)));
 }
 
 /**
- * Copies every project snapshot inside an envelope into the acceptor's own project list — a
- * cross-color attach the backend permits. Mirrors {@link duplicateProject}'s `rename` contract,
- * but resolves the source against the envelope tree (not the acceptor's own list), so the
- * wrapper cannot be reused.
+ * Copies every project snapshot inside an envelope into the recipient's own project list — a
+ * cross-color attach the backend permits. The source is resolved against the envelope tree, not
+ * the recipient's own list.
+ *
+ * `label` names each copy from its snapshot's label. The caller picks the names against the
+ * destination the copies land in, because that is where they have to be free; left out, each copy
+ * keeps its snapshot's label.
  *
- * @returns ids of the projects created in the acceptor's list.
+ * Each result carries the envelope field uuid it was copied from, because that uuid is what the
+ * payload names a project by — a folder share reads the folder of each copy off it. Pairing by
+ * position would happen to work today and quietly stop working the moment the order does.
+ *
+ * @returns one entry per copied project: the envelope uuid it came from and its new id.
  */
 export async function copyEnvelopeProjectsIntoList(
   tx: PlTransaction,
   envelopeRid: SignedResourceId,
   projectListRid: SignedResourceId,
-  rename?: (previousLabel: string, existingLabels: string[]) => string,
-): Promise<SignedResourceId[]> {
-  // Read the acceptor's existing project labels once (own color, no relaxation).
-  const projectListData = await tx.getResourceData(projectListRid, true);
-  const existingRids = projectListData.fields.map((f) => f.value).filter(isNotNullSignedResourceId);
-  const existingLabels = (
-    await Promise.all(existingRids.map((rid) => tx.getKValueJson<ProjectMeta>(rid, ProjectMetaKey)))
-  ).map((m) => m.label);
-
-  // Enumerate the envelope's project/{uuid} input field values (signed envelope-colored ids).
+  label?: (sourceLabel: string) => string,
+): Promise<{ uuid: ProjectFieldUuid; rid: SignedResourceId }[]> {
+  // Enumerate the envelope's project/{uuid} input fields (signed envelope-colored ids).
   const envelopeData = await tx.getResourceData(envelopeRid, true);
-  const sourceRids = envelopeData.fields
+  const sources = envelopeData.fields
     .filter((f) => isEnvelopeProjectField(f.name))
-    .map((f) => f.value)
-    .filter(isNotNullSignedResourceId);
+    .flatMap((f) =>
+      isNotNullSignedResourceId(f.value)
+        ? [{ uuid: envelopeProjectFieldUuid(f.name), sourceRid: f.value }]
+        : [],
+    );
 
-  const created: SignedResourceId[] = [];
-  for (const sourceRid of sourceRids) {
+  const created: { uuid: ProjectFieldUuid; rid: SignedResourceId }[] = [];
+  for (const { uuid, sourceRid } of sources) {
     const sourceMeta = await tx.getKValueJson<ProjectMeta>(sourceRid, ProjectMetaKey);
-    const newLabel = rename ? rename(sourceMeta.label, existingLabels) : sourceMeta.label;
-    existingLabels.push(newLabel);
+    const newLabel = label === undefined ? sourceMeta.label : label(sourceMeta.label);
 
-    // Cross-color attach: a new UserProject in the acceptor's color whose fields point at
+    // Cross-color attach: a new UserProject in the recipient's color whose fields point at
     // envelope-colored resources. Fails with PermissionDenied: color mismatch on a backend
     // that lacks crossTreeRefs:v1.
-    const newPrj = await duplicateProject(tx, sourceRid, { label: newLabel });
+    const newPrj = await duplicateProject(tx, sourceRid, { ...sourceMeta, label: newLabel });
     tx.createField(field(projectListRid, randomUUID()), "Dynamic", newPrj);
 
-    const signedRid = await newPrj.globalId;
-    created.push(signedRid);
+    created.push({ uuid, rid: await newPrj.globalId });
   }
 
   return created;
 }
 
-/** String-form ids of the projects created by {@link copyEnvelopeProjectsIntoList}. */
-export function resourceIdsToStrings(ids: SignedResourceId[]): string[] {
-  return ids.map((id) => resourceIdToString(id));
+//
+// Internals
+//
+
+/** One source project snapshotted for an envelope: the field uuid it rides under, the snapshot
+ *  itself, and what the payload says about it. */
+type EnvelopeSnapshot<Source extends EnvelopeProjectSource> = {
+  uuid: ProjectFieldUuid;
+  ref: ResourceRef;
+  source: Source;
+  project: EnvelopeProject;
+};
+
+/**
+ * Snapshots each source project by reference, in the given order, under a freshly minted field
+ * uuid. The payload entry carries the project's label and description as they were at `sharedAt`,
+ * so a share list renders without traversing into the snapshot.
+ */
+async function snapshotEnvelopeProjects<Source extends EnvelopeProjectSource>(
+  tx: PlTransaction,
+  sources: readonly Source[],
+  sharedAt: number,
+): Promise<EnvelopeSnapshot<Source>[]> {
+  const snapshots: EnvelopeSnapshot<Source>[] = [];
+  for (const source of sources) {
+    const meta = await tx.getKValueJson<ProjectMeta>(source.sourceRid, ProjectMetaKey);
+    const ref = await duplicateProject(tx, source.sourceRid, meta);
+    const description = normalizeDescription(meta.description);
+    snapshots.push({
+      uuid: newProjectFieldUuid(),
+      ref,
+      source,
+      project: {
+        label: meta.label,
+        source: source.projectId,
+        updatedAt: sharedAt,
+        ...(description === undefined ? {} : { description }),
+      },
+    });
+  }
+  return snapshots;
+}
+
+/**
+ * Creates the envelope with its immutable `data`, attaches each snapshot as a `project/{uuid}`
+ * input field, and hangs the envelope on the donor's outbox under its shareId.
+ *
+ * A payload that carries project snapshots has its input set sealed one-way, even when the
+ * subtree it describes holds none, because such an envelope is granted writable. A template
+ * payload has no input set to seal. The outbox attach happens in the same transaction, so the
+ * held-resource rule keeps the ephemeral envelope alive.
+ */
+function sealEnvelope(
+  tx: PlTransaction,
+  outboxRid: SignedResourceId,
+  data: EnvelopeData,
+  snapshots: readonly { uuid: ProjectFieldUuid; ref: ResourceRef }[],
+): ResourceRef {
+  const envelope = tx.createEphemeral(SharedEnvelopeResourceType, JSON.stringify(data));
+
+  for (const { uuid, ref } of snapshots)
+    tx.createField(field(envelope, envelopeProjectField(uuid)), "Input", ref);
+  if (data.payload.kind !== "template") tx.lockInputs(envelope);
+
+  tx.createField(field(outboxRid, data.shareId), "Dynamic", envelope);
+  return envelope;
 }

package/src/mutator/template.ts

@@ -1,12 +1,20 @@
-import type { PlTransaction, ResourceRef, SignedResourceId } from "@milaboratories/pl-client";
-import { field, isNullSignedResourceId, resourceIdToString } from "@milaboratories/pl-client";
+import type {
+  AnyResourceRef,
+  PlTransaction,
+  ResourceRef,
+  SignedResourceId,
+} from "@milaboratories/pl-client";
+import { field } from "@milaboratories/pl-client";
+import { normalizeDescription } from "@milaboratories/pl-model-middle-layer";
 import { randomUUID } from "node:crypto";
 import type { StoredTemplateData, TemplateId } from "../middle_layer/template_list";
 import {
   TemplateCreatedTimestamp,
+  TemplateDescriptionKey,
   TemplateLabelKey,
   TemplateResourceType,
 } from "../middle_layer/template_list";
+import { listedById, notListedError } from "./list";
 
 /**
  * Creates one `UserTemplate` inside the given write transaction and attaches it to the
@@ -15,21 +23,26 @@ import {
  * Create and attach are the same transaction on purpose: an ephemeral resource nothing
  * holds is collectable, so the list field is what keeps the template alive.
  *
- * The document rides in the immutable `data` blob, set once here and never altered; only
- * the label and the creation timestamp go to KV, and only the label is ever written again.
+ * The document rides in the immutable `data` blob, set once here and never altered. The label,
+ * the creation timestamp and the description live in KV beside it; the label and the description
+ * may be written again later, the timestamp never is. A blank description stores nothing, the
+ * same as {@link setTemplateDescription} does.
  *
  * @returns the new template resource; the caller reads its `globalId` after the commit.
  */
 export function createTemplate(
   tx: PlTransaction,
   listRid: SignedResourceId,
-  label: string,
+  meta: { readonly label: string; readonly description?: string },
   data: StoredTemplateData,
 ): ResourceRef {
   const tpl = tx.createEphemeral(TemplateResourceType, JSON.stringify(data));
   tx.lock(tpl);
-  tx.setKValue(tpl, TemplateLabelKey, JSON.stringify(label));
+  tx.setKValue(tpl, TemplateLabelKey, JSON.stringify(meta.label));
   tx.setKValue(tpl, TemplateCreatedTimestamp, String(Date.now()));
+  const description = normalizeDescription(meta.description);
+  if (description !== undefined)
+    tx.setKValue(tpl, TemplateDescriptionKey, JSON.stringify(description));
   tx.createField(field(listRid, randomUUID()), "Dynamic", tpl);
   return tpl;
 }
@@ -40,36 +53,31 @@ export function renameTemplate(tx: PlTransaction, rid: SignedResourceId, label:
   tx.setKValue(rid, TemplateLabelKey, JSON.stringify(label));
 }
 
+/**
+ * Sets what a stored template says about itself. Blank removes the entry rather than storing an
+ * empty one, so a template that was never described and one whose description was cleared are
+ * stored the same way.
+ */
+export function setTemplateDescription(
+  tx: PlTransaction,
+  rid: AnyResourceRef,
+  description: string,
+): void {
+  const wanted = normalizeDescription(description);
+  if (wanted === undefined) tx.deleteKValue(rid, TemplateDescriptionKey);
+  else tx.setKValue(rid, TemplateDescriptionKey, JSON.stringify(wanted));
+}
+
 /**
  * Detaches a template from the templates list, which is what destroys it — the list field is
  * the only thing holding the ephemeral resource.
- *
- * The field name is a uuid unrelated to the template id, so the field carrying the template
- * is found by value, the same way a project is removed from the project list.
  */
 export async function deleteTemplate(
   tx: PlTransaction,
   listRid: SignedResourceId,
   id: TemplateId,
 ): Promise<void> {
-  const fieldName = await findTemplateField(tx, listRid, id);
-  if (fieldName === undefined) throw new Error(`Template ${id} not found in template list.`);
-  tx.removeField(field(listRid, fieldName));
-}
-
-//
-// Internals
-//
-
-async function findTemplateField(
-  tx: PlTransaction,
-  listRid: SignedResourceId,
-  id: TemplateId,
-): Promise<string | undefined> {
-  const data = await tx.getResourceData(listRid, true);
-  for (const f of data.fields) {
-    if (isNullSignedResourceId(f.value)) continue;
-    if (resourceIdToString(f.value) === (id as string)) return f.name;
-  }
-  return undefined;
+  const entry = (await listedById(tx, listRid)).get(id);
+  if (entry === undefined) throw notListedError("Template", id);
+  tx.removeField(field(listRid, entry.fieldName));
 }

package/src/test/with_ml.ts

@@ -2,6 +2,7 @@ import path from "path";
 import { randomUUID } from "node:crypto";
 import type { PlClient } from "@milaboratories/pl-client";
 import { TestHelpers } from "@milaboratories/pl-client";
+import { afterAll } from "vitest";
 import { MiddleLayer } from "../middle_layer/middle_layer";
 
 /**
@@ -14,25 +15,81 @@ import { MiddleLayer } from "../middle_layer/middle_layer";
 export async function withMl(
   cb: (ml: MiddleLayer, workFolder: string) => Promise<void>,
 ): Promise<void> {
-  const workFolder = path.resolve(`work/${randomUUID()}`);
-
   await TestHelpers.withTempRoot(async (pl: PlClient) => {
-    const ml = await MiddleLayer.init(pl, workFolder, {
-      defaultTreeOptions: { pollingInterval: 250, stopPollingDelay: 500 },
-      devBlockUpdateRecheckInterval: 300,
-      localSecret: MiddleLayer.generateLocalSecret(),
-      localProjections: [],
-      openFileDialogCallback: () => {
-        throw new Error("Not implemented.");
-      },
-    });
-    ml.addRuntimeCapability("requiresUIAPIVersion", 1);
-    ml.addRuntimeCapability("requiresUIAPIVersion", 2);
-    ml.addRuntimeCapability("requiresUIAPIVersion", 3);
+    await runMl(pl, cb);
+  });
+}
+
+/**
+ * A {@link withMl} for one test file whose temporary roots all outlive their tests and are deleted
+ * together once the file is done. Call it at the top of the file; each test still gets a root of
+ * its own.
+ *
+ * Deleting a root deletes every project in it, and the backend then cleans up each of their
+ * templates one transaction at a time. That cleanup conflicts with any project being created
+ * meanwhile, anywhere, so a file that deleted its roots test by test kept failing its own next
+ * test's writes. Deferred, the cleanup happens once, after the file's last test.
+ */
+export function withMlKeepingRoots(): (
+  cb: (ml: MiddleLayer, workFolder: string) => Promise<void>,
+) => Promise<void> {
+  const roots: string[] = [];
+
+  afterAll(async () => {
+    const owner = await TestHelpers.getTestClient();
     try {
-      await cb(ml, workFolder);
+      for (const root of roots) await owner.deleteAlternativeRoot(root);
     } finally {
-      await ml.close();
+      await owner.close();
     }
   });
+
+  return async (cb) => {
+    const root = `test_${Date.now()}_${randomUUID()}`;
+    roots.push(root);
+    await runMl(await TestHelpers.getTestClient(root), cb);
+  };
+}
+
+/**
+ * A live {@link MiddleLayer} over the test user's own root, on a client of its own, closed again
+ * when the body returns — what a test restarting the middle layer opens once per run.
+ *
+ * The user's own root rather than a temporary one: a client asking for a temporary root by name
+ * gets a fresh, empty one every time, so a second run would start from nothing. What a test
+ * leaves in this root outlives it, so the test cleans up after itself. The work folder is fresh on
+ * every call, so nothing local carries over from one run to the next.
+ */
+export async function withMlOnUserRoot(
+  cb: (ml: MiddleLayer, workFolder: string) => Promise<void>,
+): Promise<void> {
+  await runMl(await TestHelpers.getTestClient(), cb);
+}
+
+//
+// Internals
+//
+
+async function runMl(
+  pl: PlClient,
+  cb: (ml: MiddleLayer, workFolder: string) => Promise<void>,
+): Promise<void> {
+  const workFolder = path.resolve(`work/${randomUUID()}`);
+  const ml = await MiddleLayer.init(pl, workFolder, {
+    defaultTreeOptions: { pollingInterval: 250, stopPollingDelay: 500 },
+    devBlockUpdateRecheckInterval: 300,
+    localSecret: MiddleLayer.generateLocalSecret(),
+    localProjections: [],
+    openFileDialogCallback: () => {
+      throw new Error("Not implemented.");
+    },
+  });
+  ml.addRuntimeCapability("requiresUIAPIVersion", 1);
+  ml.addRuntimeCapability("requiresUIAPIVersion", 2);
+  ml.addRuntimeCapability("requiresUIAPIVersion", 3);
+  try {
+    await cb(ml, workFolder);
+  } finally {
+    await ml.close();
+  }
 }