@milaboratories/pl-middle-layer 1.71.16 → 1.72.0

package/dist/middle_layer/folders.js

@@ -0,0 +1,613 @@
+import { ProjectLastModifiedTimestamp, ProjectMetaKey } from "../model/project_model.js";
+import { projectListEntries } from "./project_list.js";
+import { TemplateLabelKey, templateListEntries } from "./template_list.js";
+import { listedById, notListedError } from "../mutator/list.js";
+import { renameTemplate } from "../mutator/template.js";
+import { asFolderId, commitFoldersMove, commitFoldersRemoval, decodeStoredFoldersDocument, emptyFoldersDocument, foldersDocumentFromView, foldersNameBlank, foldersNameTaken, foldersSiblingNames, foldersSubtree, foldersUniqueName, formatFoldersViolation, healFolders, normalizeDescription, planFoldersMove, planFoldersRemoval, validateFoldersDocument } from "@milaboratories/pl-model-middle-layer";
+import { asProjectId, asTemplateId } from "@milaboratories/pl-model-common";
+import { field, isNullSignedResourceId, resourceIdToString, resourceTypesEqual, treeFilter } from "@milaboratories/pl-client";
+import { SynchronizedTreeState } from "@milaboratories/pl-tree";
+import { Computable } from "@milaboratories/computable";
+import { randomUUID } from "node:crypto";
+//#region src/middle_layer/folders.ts
+/** Field on the user's client root holding the folder singleton. */
+const FoldersField = "folders";
+const FoldersResourceType = {
+	name: "Folders",
+	version: "1"
+};
+/**
+* The one field of the singleton. It holds the whole tree as a single immutable JSON value
+* resource; a write mints a new value and re-points this field at it, the way a block's stored
+* state is rewritten.
+*/
+const FoldersDocumentField = "document";
+const FoldersTreePruningFunction = (resource) => {
+	if (!resourceTypesEqual(resource.type, FoldersResourceType)) return [];
+	return resource.fields;
+};
+const foldersFieldFilter = treeFilter.resourceTypeEq(FoldersResourceType.name);
+/**
+* The folder tree plus the computable that joins it with the project list.
+*
+* Both halves are read from one computable context, so the listing is always one consistent
+* snapshot. Nothing is published while either half is still syncing: a project would otherwise
+* render at the top level for a poll or two and then jump into its folder.
+*/
+async function createFolderList(pl, rid, projectsTree, templatesTree, openedProjects, env) {
+	const tree = await SynchronizedTreeState.init(pl, rid, {
+		...env.ops.defaultTreeOptions,
+		pruning: FoldersTreePruningFunction,
+		fieldFilter: foldersFieldFilter
+	}, env.logger);
+	return {
+		computable: Computable.make((ctx) => {
+			const projectsNode = ctx.accessor(projectsTree.entry()).node();
+			const templatesNode = ctx.accessor(templatesTree.entry()).node();
+			const foldersNode = ctx.accessor(tree.entry()).node();
+			if (projectsNode === void 0 || templatesNode === void 0 || foldersNode === void 0) {
+				ctx.markUnstable("folders_not_synced");
+				return;
+			}
+			const result = foldersListing(foldersNode, projectListEntries(projectsNode, openedProjects.getValue(ctx)), templateListEntries(templatesNode));
+			if (result.status === "not-synced") {
+				ctx.markUnstable(result.reason);
+				return;
+			}
+			return result.listing;
+		}).withStableType(),
+		tree
+	};
+}
+/**
+* Joins the folder singleton with an already-read project list.
+*
+* Split out of the computable so that the join, the first-paint rule and the degrade can be
+* exercised without a backend — the same reason {@link projectListEntries} is a function rather
+* than a closure. The interface it takes is the exact slice of the tree accessor it touches, so
+* the real accessor satisfies it structurally.
+*
+* The listing is built by mapping over the **project list**, never over the folder view, so no
+* folder input can drop a project. Do not refactor that into a map over the view.
+*/
+function foldersListing(foldersNode, entries, templateEntries = []) {
+	const documentNode = foldersNode.traverse({
+		field: FoldersDocumentField,
+		stableIfNotFound: true
+	});
+	if (documentNode === void 0 && foldersNode.listDynamicFields().includes("document")) return {
+		status: "not-synced",
+		reason: "folders_document_not_synced"
+	};
+	const view = healFolders(decodeStoredFoldersDocument(documentNode === void 0 ? { present: false } : {
+		present: true,
+		raw: documentNode.getDataAsString()
+	}), entries.map((entry) => ({
+		id: entry.id,
+		name: entry.meta.label
+	})), templateEntries.map((entry) => ({
+		id: entry.id,
+		name: entry.label
+	})));
+	return {
+		status: "ready",
+		listing: {
+			folders: view.folders,
+			projects: withPlacement(entries, view.projects),
+			templates: withPlacement(templateEntries, view.templates),
+			writable: view.writable,
+			...view.problem === void 0 ? {} : { problem: view.problem },
+			healed: view.healed
+		}
+	};
+}
+/**
+* The one way the folder document is written by a folder operation.
+*
+* The whole body runs inside a single write transaction: the document and the project list are
+* re-read there, the edit is computed from what that read found, and only then is a new value
+* resource minted and the field re-pointed. The backend validates read sets, so a racing commit
+* aborts this one and the client replays the body against fresh state — which is only true
+* because the reading happens *inside* the body. Nothing may be carried across attempts, and
+* anything with an identity of its own (a folder id) is minted by the caller beforehand, so a
+* retry cannot hand back an id that was never stored.
+*
+* The advisory lock serialises writers inside one process. It is not a substitute for the
+* backend's conflict detection — it just removes the cheap case, one window racing itself.
+*/
+async function withFolders(pl, name, rids, body) {
+	return await pl.withWriteTx(name, async (tx) => {
+		const read = await readFolders(tx, rids);
+		if (!read.decoded.writable) throw new Error(refusalMessage(read.decoded.problem));
+		const edit = body(read.view);
+		if (edit.document === void 0) return edit.result;
+		rejectNewViolations(read, edit.document, edit.labelRenames ?? [], [...edit.deletedProjects ?? [], ...edit.deletedTemplates ?? []]);
+		writeFoldersDocument(tx, rids, read, edit.document);
+		const timestamp = JSON.stringify(Date.now());
+		for (const rename of edit.labelRenames ?? []) {
+			if (rename.item.kind === "template") {
+				const rid = read.templateRids.get(rename.item.id);
+				if (rid === void 0) throw notListedError("Template", rename.item.id);
+				renameTemplate(tx, rid, rename.name);
+				continue;
+			}
+			const rid = read.projectRids.get(rename.item.id);
+			const meta = read.projectMetas.get(rename.item.id);
+			if (rid === void 0 || meta === void 0) throw notListedError("Project", rename.item.id);
+			tx.setKValue(rid, ProjectMetaKey, JSON.stringify({
+				...meta,
+				label: rename.name
+			}));
+			tx.setKValue(rid, ProjectLastModifiedTimestamp, timestamp);
+		}
+		await removeListedFields(tx, rids.projects, edit.deletedProjects ?? [], "Project");
+		await removeListedFields(tx, rids.templates, edit.deletedTemplates ?? [], "Template");
+		await tx.commit();
+		return edit.result;
+	}, { lockId: foldersLockId(rids.folders) });
+}
+/**
+* The same read the write path performs, in a read transaction — what a preview is computed from,
+* so that a preview and the write that follows it never disagree about how the tree was read.
+*/
+async function readFoldersView(pl, name, rids) {
+	return await pl.withReadTx(name, async (tx) => {
+		return (await readFolders(tx, rids)).view;
+	});
+}
+/** Opens the folder tree inside the caller's transaction; see {@link FoldersTx}. */
+async function openFoldersTx(tx, rids) {
+	const read = await readFolders(tx, rids);
+	const projects = read.view.projects.map(({ id, name }) => ({
+		id,
+		name
+	}));
+	const templates = read.view.templates.map(({ id, name }) => ({
+		id,
+		name
+	}));
+	let view = read.view;
+	let document = foldersDocumentFromView(read.view);
+	let documentFieldExists = read.documentFieldExists;
+	const write = (next) => {
+		writeFoldersDocument(tx, rids, {
+			...read,
+			documentFieldExists
+		}, next);
+		documentFieldExists = true;
+		document = next;
+		view = healFolders({
+			document: next,
+			writable: true
+		}, projects, templates);
+	};
+	const assertFolderExists = (folder) => {
+		if (!view.folders.some((candidate) => candidate.id === folder)) throw new Error(`Folder ${folder} does not exist.`);
+	};
+	const namesTakenIn = (folder) => read.decoded.writable ? foldersSiblingNames(view, folder) : [];
+	const folderOf = (project) => view.projects.find((candidate) => candidate.id === project)?.folder;
+	return {
+		get view() {
+			return view;
+		},
+		projectRids: read.projectRids,
+		templateRids: read.templateRids,
+		namesTakenIn,
+		namesTakenBeside: (project) => namesTakenIn(folderOf(project)),
+		folderOf,
+		assertNameFree(item, name) {
+			if (foldersNameBlank(name) || !read.decoded.writable) return;
+			const placed = item.kind === "project" ? view.projects.find((candidate) => candidate.id === item.id) : view.templates.find((candidate) => candidate.id === item.id);
+			if (placed === void 0) return;
+			if (foldersNameTaken(name, [placed.name])) return;
+			if (foldersNameTaken(name, foldersSiblingNames(view, placed.folder, [item.id]))) throw new Error(`"${name}" is already used here.`);
+		},
+		place(items, folder) {
+			if (folder === void 0 || items.length === 0 || !read.decoded.writable) return;
+			assertFolderExists(folder);
+			const assignments = { ...document.assignments };
+			const templateAssignments = { ...document.templateAssignments };
+			for (const item of items) if (item.kind === "project") assignments[item.id] = folder;
+			else templateAssignments[item.id] = folder;
+			write({
+				...document,
+				assignments,
+				templateAssignments
+			});
+		},
+		graft(subtree, destination) {
+			if (!read.decoded.writable) return "unwritable";
+			if (destination !== void 0) assertFolderExists(destination);
+			const root = subtree.folders[subtree.root];
+			if (root === void 0) throw new Error(`The subtree holds no folder ${subtree.root}.`);
+			const rootName = foldersUniqueName(root.name, foldersSiblingNames(view, destination));
+			const incoming = Object.keys(subtree.folders);
+			const minted = /* @__PURE__ */ new Map();
+			for (const key of incoming) minted.set(key, asFolderId(randomUUID()));
+			const folders = [...document.folders];
+			for (const key of incoming) {
+				const incomingFolder = subtree.folders[key];
+				const parent = key === subtree.root ? destination : mustGet(minted, incomingFolder.parent ?? subtree.root);
+				const description = normalizeDescription(incomingFolder.description);
+				folders.push({
+					id: mustGet(minted, key),
+					name: key === subtree.root ? rootName : incomingFolder.name,
+					...parent === void 0 ? {} : { parent },
+					...description === void 0 ? {} : { description }
+				});
+			}
+			const assignments = { ...document.assignments };
+			const templateAssignments = { ...document.templateAssignments };
+			for (const item of subtree.items) {
+				const folder = minted.get(item.folder);
+				if (folder === void 0) continue;
+				if (item.kind === "project") assignments[item.id] = folder;
+				else templateAssignments[item.id] = folder;
+			}
+			write({
+				...document,
+				folders,
+				assignments,
+				templateAssignments
+			});
+			return "grafted";
+		}
+	};
+}
+/**
+* Creates a folder and returns its id.
+*
+* The name is typed by a human, so a name already used in the destination is rejected rather than
+* quietly suffixed — a text field that disagrees with what was typed is worse than one that says
+* no.
+*/
+async function createFolder(pl, rids, name, parent) {
+	if (foldersNameBlank(name)) throw new Error("A folder name cannot be empty.");
+	const wanted = name.trim();
+	const id = asFolderId(randomUUID());
+	await withFolders(pl, "MLCreateFolder", rids, (view) => {
+		if (parent !== void 0 && !view.folders.some((folder) => folder.id === parent)) throw new Error(`Folder ${parent} does not exist.`);
+		if (foldersNameTaken(wanted, foldersSiblingNames(view, parent))) throw new Error(`"${wanted}" is already used here.`);
+		const base = foldersDocumentFromView(view);
+		return {
+			result: void 0,
+			document: {
+				...base,
+				folders: [...base.folders, parent === void 0 ? {
+					id,
+					name: wanted
+				} : {
+					id,
+					name: wanted,
+					parent
+				}]
+			}
+		};
+	});
+	return id;
+}
+/** Renames a folder. A human typed this name too, so a collision is rejected, not suffixed. */
+async function renameFolder(pl, rids, folder, name) {
+	if (foldersNameBlank(name)) throw new Error("A folder name cannot be empty.");
+	const wanted = name.trim();
+	await withFolders(pl, "MLRenameFolder", rids, (view) => {
+		const target = view.folders.find((candidate) => candidate.id === folder);
+		if (target === void 0) throw new Error(`Folder ${folder} does not exist.`);
+		if (foldersNameTaken(wanted, foldersSiblingNames(view, target.parent, [folder]))) throw new Error(`"${wanted}" is already used here.`);
+		const base = foldersDocumentFromView(view);
+		return {
+			result: void 0,
+			document: {
+				...base,
+				folders: base.folders.map((candidate) => candidate.id === folder ? {
+					...candidate,
+					name: wanted
+				} : candidate)
+			}
+		};
+	});
+}
+/**
+* Sets what a folder says about itself. Blank clears it.
+*
+* Unlike a name, a description is in no namespace: nothing is checked against the siblings, and
+* two folders may say the same thing about themselves.
+*/
+async function setFolderDescription(pl, rids, folder, description) {
+	const wanted = normalizeDescription(description);
+	await withFolders(pl, "MLSetFolderDescription", rids, (view) => {
+		if (view.folders.find((candidate) => candidate.id === folder) === void 0) throw new Error(`Folder ${folder} does not exist.`);
+		const base = foldersDocumentFromView(view);
+		return {
+			result: void 0,
+			document: {
+				...base,
+				folders: base.folders.map((candidate) => {
+					if (candidate.id !== folder) return candidate;
+					const { description: _dropped, ...rest } = candidate;
+					return wanted === void 0 ? rest : {
+						...rest,
+						description: wanted
+					};
+				})
+			}
+		};
+	});
+}
+/**
+* The shape of a folder subtree under ids local to the caller: a fresh id per folder, the root's
+* own parent left behind so the subtree stands alone, and a lookup from a real folder id to its
+* local one.
+*
+* Both ways of copying a folder need this. A share carries the shape into another user's tree and
+* a duplicate rebuilds it beside the source, and neither may carry the folder ids themselves,
+* because the document that receives the subtree mints its own.
+*/
+function foldersLocalSubtree(view, root, mint) {
+	const inSubtree = new Set(foldersSubtree(view, root));
+	const localIds = /* @__PURE__ */ new Map();
+	for (const id of inSubtree) localIds.set(id, mint());
+	const localId = (id) => {
+		const local = localIds.get(id);
+		if (local === void 0) throw new Error(`Folder ${id} is not under ${root}.`);
+		return local;
+	};
+	const folders = {};
+	for (const candidate of view.folders) {
+		if (!inSubtree.has(candidate.id)) continue;
+		const parent = candidate.id === root ? void 0 : localId(candidate.parent ?? root);
+		folders[localId(candidate.id)] = {
+			name: candidate.name,
+			...parent === void 0 ? {} : { parent },
+			...candidate.description === void 0 ? {} : { description: candidate.description }
+		};
+	}
+	return {
+		inSubtree,
+		localId,
+		folders
+	};
+}
+/**
+* The plan a move would produce, computed from a fresh read — what the confirmation dialog shows.
+* The same planner runs again inside the write, over the same shape of read.
+*/
+async function previewFoldersMove(pl, rids, items, destination) {
+	return planFoldersMove(await readFoldersView(pl, "MLPreviewFoldersMove", rids), items, destination);
+}
+/**
+* Moves any mix of folders, projects and templates into one destination, committing only when
+* the plan recomputed inside the transaction is identical to `confirmedPlan`.
+*/
+async function moveFolderItems(pl, rids, items, destination, confirmedPlan) {
+	return await withFolders(pl, "MLMoveFolderItems", rids, (view) => commitFoldersMove(view, planFoldersMove(view, items, destination), confirmedPlan));
+}
+/** What deleting a folder would destroy: the subtree of folders, and every project and template
+*  in it. */
+async function previewFolderDeletion(pl, rids, folder) {
+	return planFoldersRemoval(await readFoldersView(pl, "MLPreviewFolderDeletion", rids), folder);
+}
+/**
+* Deletes a folder, every folder inside it, and every project and template held anywhere in that
+* subtree.
+*
+* Deletion cannot be undone, so `confirmedRemoval` is required: the removal is recomputed here and
+* the write commits only if it names exactly the same things the caller confirmed. A project
+* dropped into the folder after the dialog opened therefore aborts the deletion rather than being
+* destroyed unseen.
+*/
+async function deleteFolder(pl, rids, folder, confirmedRemoval) {
+	return await withFolders(pl, "MLDeleteFolder", rids, (view) => commitFoldersRemoval(view, planFoldersRemoval(view, folder), confirmedRemoval));
+}
+/**
+* Replaces a folder document this build cannot read with an empty one: no folders and no
+* assignments, so every project and template shows at the top level. Nothing but the document is
+* touched, and what the unreadable tree held is lost for good.
+*
+* It is refused while the document reads fine, so a working tree can never be wiped through it.
+* "Reads fine" is decided by the same decode the listing uses, in the transaction that writes.
+*/
+async function resetFolders(pl, rids) {
+	await pl.withWriteTx("MLResetFolders", async (tx) => {
+		const stored = await readStoredFolders(tx, rids);
+		if (stored.decoded.writable) throw new Error("Folders can only be reset when they cannot be read, and these can be read. Nothing was changed.");
+		writeFoldersDocument(tx, rids, {
+			carriedAssignments: {},
+			documentFieldExists: stored.documentFieldExists
+		}, emptyFoldersDocument());
+		await tx.commit();
+	}, { lockId: foldersLockId(rids.folders) });
+}
+/** A key looked up in a map that was built from those very keys; absent means the code above
+*  changed and the two no longer agree. */
+function mustGet(map, key) {
+	const value = map.get(key);
+	if (value === void 0) throw new Error(`No entry for ${String(key)}.`);
+	return value;
+}
+/** Each entry of a list with its place in the tree, looked up by id; an entry the tree does not
+*  place is at the top level. */
+function withPlacement(entries, placed) {
+	const byId = new Map(placed.map((item) => [item.id, item]));
+	return entries.map((entry) => {
+		const placement = byId.get(entry.id);
+		return {
+			...entry,
+			...placement?.folder === void 0 ? {} : { folder: placement.folder },
+			ancestors: placement?.ancestors ?? [],
+			path: placement?.path ?? []
+		};
+	});
+}
+/**
+* The folder document and both item lists, read inside a transaction.
+*
+* An absent document field is a user with no folders, and is writable. A field that points at
+* something carrying no readable blob is a document that exists and cannot be read here, and must
+* refuse writes, or the first folder edit replaces that tree with an empty one.
+*
+* A list entry counts as a project when it carries project metadata, and as a template when it
+* carries a template label. Nothing else is checked. The listing readers are stricter:
+* {@link projectListEntries} also requires the project resource type by name and both the created
+* and the last-modified timestamps, and {@link templateListEntries} also requires the template
+* resource type by name, the data blob and the created timestamp. So every entry the listing shows
+* is kept here, and so is an entry the listing skips because it has only partly synced or is a
+* foreign resource carrying one of those keys: it still holds its name and its folder assignment,
+* which is the safe side for a write. Telling a foreign resource apart by its type instead would
+* read the state of every resource in the list, and a read of a project's state conflicts with
+* every write that project's own session makes, so a folder edit would keep losing to any project
+* that is open.
+*/
+async function readFolders(tx, rids) {
+	const { decoded, documentFieldExists } = await readStoredFolders(tx, rids);
+	const [listedProjects, listedTemplates] = await Promise.all([listedById(tx, rids.projects), listedById(tx, rids.templates)]);
+	const [metas, labels] = await Promise.all([Promise.all([...listedProjects.values()].map(({ rid }) => tx.getKValueJsonIfExists(rid, ProjectMetaKey))), Promise.all([...listedTemplates.values()].map(({ rid }) => tx.getKValueJsonIfExists(rid, TemplateLabelKey)))]);
+	const projectRids = /* @__PURE__ */ new Map();
+	const projectMetas = /* @__PURE__ */ new Map();
+	const projects = [];
+	const carriedAssignments = {};
+	[...listedProjects.values()].forEach(({ rid }, index) => {
+		const id = asProjectId(resourceIdToString(rid));
+		projectRids.set(id, rid);
+		const meta = metas[index];
+		if (meta === void 0) {
+			const folder = decoded.document.assignments[id];
+			if (folder !== void 0) carriedAssignments[id] = folder;
+			return;
+		}
+		projectMetas.set(id, meta);
+		projects.push({
+			id,
+			name: meta.label
+		});
+	});
+	const templateRids = /* @__PURE__ */ new Map();
+	const templates = [];
+	[...listedTemplates.values()].forEach(({ rid }, index) => {
+		const label = labels[index];
+		if (label === void 0) return;
+		const id = asTemplateId(resourceIdToString(rid));
+		templateRids.set(id, rid);
+		templates.push({
+			id,
+			name: label
+		});
+	});
+	return {
+		view: healFolders(decoded, projects, templates),
+		decoded,
+		projectRids,
+		projectMetas,
+		templateRids,
+		documentFieldExists,
+		carriedAssignments
+	};
+}
+/** The folder document alone, decoded, and whether its field exists at all. */
+async function readStoredFolders(tx, rids) {
+	const documentField = await tx.getFieldIfExists(field(rids.folders, FoldersDocumentField));
+	return {
+		decoded: decodeStoredFoldersDocument(documentField === void 0 || isNullSignedResourceId(documentField.value) ? { present: false } : {
+			present: true,
+			raw: await readDocumentText(tx, documentField.value)
+		}),
+		documentFieldExists: documentField !== void 0
+	};
+}
+/** The stored JSON of a document value, or undefined when the value carries no blob. */
+async function readDocumentText(tx, rid) {
+	const data = await tx.getResourceData(rid, false);
+	return data.data === void 0 ? void 0 : Buffer.from(data.data).toString("utf-8");
+}
+/**
+* Persists a folder document: the assignments the read had to carry are added back, a new value
+* resource is minted, and the one document field is created or re-pointed at it.
+*/
+function writeFoldersDocument(tx, rids, read, document) {
+	const ref = tx.createJsonValue(withCarriedAssignments(document, read.carriedAssignments));
+	const documentField = field(rids.folders, FoldersDocumentField);
+	if (read.documentFieldExists) tx.setField(documentField, ref);
+	else tx.createField(documentField, "Dynamic", ref);
+}
+/**
+* A document written by a newer build, or one nothing here can parse, reads as no folders so that
+* the project list still renders — and every write is refused, because degrading the read while
+* still writing would silently replace that tree with this build's truncated view of it.
+*/
+function refusalMessage(problem) {
+	return `Folders cannot be changed: ${problem.message}. Update the application to a version that understands this folder document.`;
+}
+function withCarriedAssignments(document, carried) {
+	const entries = Object.entries(carried).filter(([, folder]) => document.folders.some((candidate) => candidate.id === folder));
+	if (entries.length === 0) return document;
+	return {
+		...document,
+		assignments: {
+			...document.assignments,
+			...Object.fromEntries(entries)
+		}
+	};
+}
+/**
+* Refuses a write that would put a *new* rule violation into the document.
+*
+* Only new ones: accounts predating folders may already hold two projects with the same name in
+* one place, because nothing enforced uniqueness before, and a write that merely carries such a
+* collision along must not be blocked by it. What the folder machinery must never do is create
+* one.
+*
+* What the write deletes is left out of the document it leaves behind. A deleted project or
+* template has no folder any more, and counted anyway it would stand at the top level under its
+* old name — where it clashes with whatever is really there, and refuses the deletion.
+*/
+function rejectNewViolations(read, document, renames, deleted) {
+	const renamed = new Map(renames.map((rename) => [rename.item.id, rename.name]));
+	const gone = new Set(deleted);
+	const templates = read.view.templates.map(({ id, name }) => ({
+		id,
+		name
+	}));
+	const before = validateFoldersDocument(foldersDocumentFromView(read.view), [...read.projectMetas].map(([id, meta]) => ({
+		id,
+		name: meta.label
+	})), templates);
+	const after = validateFoldersDocument(document, [...read.projectMetas].filter(([id]) => !gone.has(id)).map(([id, meta]) => ({
+		id,
+		name: renamed.get(id) ?? meta.label
+	})), templates.filter(({ id }) => !gone.has(id)).map(({ id, name }) => ({
+		id,
+		name: renamed.get(id) ?? name
+	})));
+	const known = new Set(before.map(violationKey));
+	const introduced = after.filter((violation) => !known.has(violationKey(violation)));
+	if (introduced.length === 0) return;
+	throw new Error(`Folder change refused: ${introduced.map(formatFoldersViolation).join("; ")}.`);
+}
+/**
+* Deletes the named items from one of the root's lists. Every id must be there: an id the list
+* does not hold means the write is deleting something other than what was planned, and the
+* transaction is abandoned rather than allowed to destroy a guess.
+*/
+async function removeListedFields(tx, listRid, ids, kind) {
+	if (ids.length === 0) return;
+	const listed = await listedById(tx, listRid);
+	for (const id of new Set(ids)) {
+		const entry = listed.get(id);
+		if (entry === void 0) throw notListedError(kind, id);
+		tx.removeField(field(listRid, entry.fieldName));
+	}
+}
+function violationKey(violation) {
+	return JSON.stringify(violation);
+}
+/**
+* Scoped to the singleton rather than to the process, so that two middle layers over two users'
+* roots — an impersonating admin session and the admin's own — do not queue behind each other.
+*/
+function foldersLockId(foldersRid) {
+	return `folders:${foldersRid}`;
+}
+//#endregion
+export { FoldersDocumentField, FoldersField, FoldersResourceType, FoldersTreePruningFunction, createFolder, createFolderList, deleteFolder, foldersFieldFilter, foldersListing, foldersLocalSubtree, moveFolderItems, openFoldersTx, previewFolderDeletion, previewFoldersMove, readFoldersView, renameFolder, resetFolders, setFolderDescription, withFolders };
+
+//# sourceMappingURL=folders.js.map