@needmoretruth/nmts-cli 0.17.2

package/dist/shared/lib/drive/manifest-index.js

@@ -0,0 +1,235 @@
+/** Folder items use kind 0, files kind 1 — the same numbers the items API uses. */
+export const KIND_FOLDER = 0;
+export const KIND_FILE = 1;
+/** Parent key for the drive root. `parentId: null` is stored; this is its map key. */
+const ROOT = "\u0000root";
+/** Build the lookup structures for one version of the list. Cost is linear; do it once. */
+export function buildIndex(entries) {
+    const byId = new Map();
+    const childrenByParent = new Map();
+    for (const e of entries) {
+        byId.set(e.id, e);
+        const key = e.parentId ?? ROOT;
+        const bucket = childrenByParent.get(key);
+        if (bucket)
+            bucket.push(e);
+        else
+            childrenByParent.set(key, [e]);
+    }
+    return { all: entries, byId, childrenByParent };
+}
+/**
+ * The instant this item became trash — its own, or the nearest trashed ancestor's.
+ * `null` means live. A parent chain that is broken or looping counts as live at the point it
+ * breaks: showing an item whose parent vanished is recoverable, hiding it silently is not.
+ */
+export function trashedAt(index, entry) {
+    let cursor = entry;
+    const seen = new Set();
+    while (cursor) {
+        if (cursor.deletedAt !== undefined)
+            return cursor.deletedAt;
+        if (cursor.parentId === null)
+            return null;
+        if (seen.has(cursor.id))
+            return null;
+        seen.add(cursor.id);
+        cursor = index.byId.get(cursor.parentId);
+    }
+    return null;
+}
+/** Live = not trashed itself and under no trashed ancestor. */
+export function isLive(index, entry) {
+    return trashedAt(index, entry) === null;
+}
+/**
+ * Does the ACCOUNT hold a file that whole-account export could actually write out?
+ *
+ * Asked by the export card, which offers itself on this and nothing else. The two wrong answers it
+ * replaces are both easy to reach: counting the CURRENT LEVEL hides the card from an account whose
+ * files all sit inside folders, and counting entries of any kind offers a download to a drive of
+ * empty folders — one that can only answer "there is nothing to download".
+ *
+ * ⚠ Trashed files are excluded on purpose. They are still stored and still paid for, but export
+ * writes the live drive, so a drive whose every file is in the trash has nothing to export.
+ */
+export function hasLiveFile(index) {
+    return index.all.some((e) => e.kind === KIND_FILE && isLive(index, e));
+}
+/**
+ * Live children of a folder (`null` = drive root), in list order.
+ * Sorting belongs to the view: the same folder is shown by name, size and date in different places.
+ */
+export function childrenOf(index, parentId) {
+    const bucket = index.childrenByParent.get(parentId ?? ROOT);
+    if (!bucket)
+        return [];
+    return bucket.filter((e) => isLive(index, e));
+}
+/**
+ * What the trash view shows: items the person deleted directly, newest first.
+ * A child whose parent is also trashed is deliberately absent — it is restored with its parent.
+ */
+export function trashRoots(index) {
+    const roots = index.all.filter((e) => {
+        if (e.deletedAt === undefined)
+            return false;
+        if (e.parentId === null)
+            return true;
+        const parent = index.byId.get(e.parentId);
+        // Parent gone entirely: this is the top of what remains, so it is its own root.
+        return parent === undefined || trashedAt(index, parent) === null;
+    });
+    return roots.slice().sort((a, b) => (b.deletedAt ?? 0) - (a.deletedAt ?? 0));
+}
+/**
+ * Folder names from the root down to (and excluding) this item.
+ * An entry whose chain is broken returns what could be resolved — callers render that as a
+ * partial path rather than claiming the item sits at the root.
+ */
+export function pathOf(index, entry) {
+    const names = [];
+    const seen = new Set([entry.id]);
+    let parentId = entry.parentId;
+    while (parentId !== null) {
+        if (seen.has(parentId))
+            break;
+        seen.add(parentId);
+        const parent = index.byId.get(parentId);
+        if (!parent)
+            break;
+        names.push(parent.name);
+        parentId = parent.parentId;
+    }
+    names.reverse();
+    return names;
+}
+/** Every descendant of a folder, live and trashed, depth-first. The folder itself is excluded. */
+export function descendantsOf(index, folderId) {
+    const out = [];
+    const seen = new Set([folderId]);
+    const stack = [folderId];
+    while (stack.length > 0) {
+        const id = stack.pop();
+        for (const child of index.childrenByParent.get(id) ?? []) {
+            if (seen.has(child.id))
+                continue;
+            seen.add(child.id);
+            out.push(child);
+            if (child.kind === KIND_FOLDER)
+                stack.push(child.id);
+        }
+    }
+    return out;
+}
+/**
+ * True when `folderId` is `candidateId` or sits underneath it.
+ * Move targets are checked with this: dropping a folder into its own subtree would detach that
+ * whole branch from the root, and nothing in the UI could reach it afterwards.
+ */
+export function isSelfOrDescendant(index, candidateId, folderId) {
+    if (candidateId === folderId)
+        return true;
+    let cursor = index.byId.get(candidateId);
+    const seen = new Set();
+    while (cursor && cursor.parentId !== null) {
+        if (cursor.parentId === folderId)
+            return true;
+        if (seen.has(cursor.id))
+            return false;
+        seen.add(cursor.id);
+        cursor = index.byId.get(cursor.parentId);
+    }
+    return false;
+}
+/**
+ * Live items whose name contains `query`, case-insensitively.
+ *
+ * This search is COMPLETE — it reads the whole list from memory. That is a change worth knowing
+ * about: the old server-backed listing could only match what had been fetched, so "no results"
+ * was a claim the UI had to hedge. Here it is simply true.
+ */
+export function searchByName(index, query, limit = 500) {
+    const needle = query.trim().toLocaleLowerCase();
+    if (needle === "")
+        return [];
+    const out = [];
+    for (const e of index.all) {
+        if (out.length >= limit)
+            break;
+        if (!e.name.toLocaleLowerCase().includes(needle))
+            continue;
+        if (!isLive(index, e))
+            continue;
+        out.push(e);
+    }
+    return out;
+}
+/**
+ * Live files the person starred, newest first.
+ *
+ * Files only: a folder is already reachable in the panel's tree, so starring one would put the same
+ * thing in two places and make "favourites" mean two different kinds of row.
+ */
+export function favoriteFiles(index) {
+    return index.all
+        .filter((e) => e.kind === KIND_FILE && e.favorite === true && isLive(index, e))
+        .slice()
+        .sort((a, b) => b.updatedAt - a.updatedAt);
+}
+/**
+ * Every label in use, with how many live files wear it, ordered by the person's own locale.
+ *
+ * Counting here rather than in the panel matters: the count is what tells someone a label still has
+ * files in it before they rename or clear it, and it must agree with what opening it shows.
+ */
+export function labelCounts(index) {
+    const counts = new Map();
+    for (const e of index.all) {
+        if (e.kind !== KIND_FILE || !e.labels || e.labels.length === 0)
+            continue;
+        if (!isLive(index, e))
+            continue;
+        for (const label of e.labels)
+            counts.set(label, (counts.get(label) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([label, count]) => ({ label, count }))
+        .sort((a, b) => a.label.localeCompare(b.label));
+}
+/** Live files wearing one label, newest first. */
+export function filesWithLabel(index, label) {
+    return index.all
+        .filter((e) => e.kind === KIND_FILE &&
+        (e.labels ?? []).includes(label) &&
+        isLive(index, e))
+        .slice()
+        .sort((a, b) => b.updatedAt - a.updatedAt);
+}
+/** Whole-drive counts. Exact, because the list is complete by construction. */
+export function totalsOf(index) {
+    const totals = {
+        files: 0,
+        folders: 0,
+        bytes: 0,
+        trashedFiles: 0,
+        trashedBytes: 0,
+    };
+    for (const e of index.all) {
+        const live = isLive(index, e);
+        if (e.kind === KIND_FOLDER) {
+            if (live)
+                totals.folders += 1;
+            continue;
+        }
+        if (live) {
+            totals.files += 1;
+            totals.bytes += e.size;
+        }
+        else {
+            totals.trashedFiles += 1;
+            totals.trashedBytes += e.size;
+        }
+    }
+    return totals;
+}

package/dist/shared/lib/drive/manifest-ops.js

@@ -0,0 +1,267 @@
+// Runtime import (relative + .ts — the header's node --test rule) for the bounds the patch obeys.
+import { TEXT_SCALE_DEFAULT_PCT, TEXT_SCALE_MAX_PCT, TEXT_SCALE_MIN_PCT, } from "./manifest-codec.js";
+/**
+ * Apply one intent, returning a new list. The input is never mutated: the store keeps the
+ * pre-save snapshot around to rebuild from after a version conflict.
+ *
+ * Returns the SAME array reference when nothing changed, so callers can skip a re-render and a
+ * save for an intent that turned out to be a no-op (a rename to the name it already had, a trash
+ * of something another device already purged).
+ */
+export function applyIntent(entries, intent) {
+    switch (intent.op) {
+        case "add":
+            return upsert(entries, intent.entry);
+        case "rename":
+            return patchOne(entries, intent.id, (e) => e.name === intent.name ? e : { ...e, name: intent.name, updatedAt: intent.at });
+        case "move":
+            return patchOne(entries, intent.id, (e) => e.parentId === intent.parentId
+                ? e
+                : { ...e, parentId: intent.parentId, updatedAt: intent.at });
+        case "trash": {
+            const ids = new Set(intent.ids);
+            // `deletedAt` is left alone when already set: it is the start of the retention window the
+            // UI promises ("restorable for 30 days"), and re-stamping it would quietly extend that.
+            return patchMany(entries, ids, (e) => e.deletedAt !== undefined ? e : { ...e, deletedAt: intent.at, updatedAt: intent.at });
+        }
+        case "restore": {
+            const ids = new Set(intent.ids);
+            return patchMany(entries, ids, (e) => {
+                if (e.deletedAt === undefined)
+                    return e;
+                const { deletedAt: _dropped, ...rest } = e;
+                return { ...rest, updatedAt: intent.at };
+            });
+        }
+        case "purge": {
+            const ids = new Set(intent.ids);
+            const kept = entries.filter((e) => !ids.has(e.id));
+            return kept.length === entries.length ? entries : kept;
+        }
+        case "favorite": {
+            const ids = new Set(intent.ids);
+            return patchMany(entries, ids, (e) => setMark(e, "favorite", intent.on, intent.at));
+        }
+        case "pin": {
+            const ids = new Set(intent.ids);
+            return patchMany(entries, ids, (e) => setMark(e, "pinned", intent.on, intent.at));
+        }
+        case "label": {
+            const label = intent.label.trim();
+            if (label === "")
+                return entries;
+            const ids = new Set(intent.ids);
+            return patchMany(entries, ids, (e) => {
+                const has = (e.labels ?? []).includes(label);
+                if (has === intent.on)
+                    return e;
+                const next = intent.on
+                    ? [...(e.labels ?? []), label]
+                    : (e.labels ?? []).filter((l) => l !== label);
+                return withLabels(e, next, intent.at);
+            });
+        }
+        case "labelRename": {
+            const from = intent.from.trim();
+            const to = intent.to.trim();
+            if (from === "" || to === "" || from === to)
+                return entries;
+            return patchAll(entries, (e) => {
+                if (!(e.labels ?? []).includes(from))
+                    return e;
+                // Renaming ONTO an existing label merges the two rather than leaving one item wearing the
+                // same label twice — which would show a doubled row and count every file twice.
+                const next = (e.labels ?? []).filter((l) => l !== from);
+                if (!next.includes(to))
+                    next.push(to);
+                return withLabels(e, next, intent.at);
+            });
+        }
+        case "labelDelete": {
+            const label = intent.label.trim();
+            if (label === "")
+                return entries;
+            return patchAll(entries, (e) => {
+                if (!(e.labels ?? []).includes(label))
+                    return e;
+                return withLabels(e, (e.labels ?? []).filter((l) => l !== label), intent.at);
+            });
+        }
+        case "shareRecord": {
+            const address = intent.address.trim();
+            if (address === "")
+                return entries;
+            return patchOne(entries, intent.id, (e) => {
+                const existing = (e.shares ?? []).find((r) => r.address === address);
+                // A re-share of the same file to the same person REVIVES the receipt: the row is live
+                // again, so a revoked mark left over from before would report a lingering row that is now
+                // exactly what the sender asked for.
+                if (existing && existing.revoked !== true)
+                    return e;
+                const others = (e.shares ?? []).filter((r) => r.address !== address);
+                return withShares(e, [...others, { address, at: intent.at }], intent.at);
+            });
+        }
+        case "shareRevoked": {
+            const address = intent.address.trim();
+            if (address === "")
+                return entries;
+            return patchOne(entries, intent.id, (e) => {
+                const receipts = e.shares ?? [];
+                if (!receipts.some((r) => r.address === address && r.revoked !== true))
+                    return e;
+                return withShares(e, receipts.map((r) => (r.address === address ? { ...r, revoked: true } : r)), intent.at);
+            });
+        }
+        case "sharePrune": {
+            const addresses = new Set(intent.addresses);
+            if (addresses.size === 0)
+                return entries;
+            return patchOne(entries, intent.id, (e) => {
+                const receipts = e.shares ?? [];
+                const kept = receipts.filter((r) => !(r.revoked === true && addresses.has(r.address)));
+                return kept.length === receipts.length ? e : withShares(e, kept, intent.at);
+            });
+        }
+    }
+}
+/**
+ * Set or clear one boolean mark, keeping "absent" as the only spelling of false.
+ *
+ * Writing `favorite: false` would be a second spelling of the same fact, and it would ride in
+ * every save for every item the person ever un-starred.
+ */
+function setMark(e, key, on, at) {
+    if (on === (e[key] === true))
+        return e;
+    if (on)
+        return { ...e, [key]: true, updatedAt: at };
+    const next = { ...e, updatedAt: at };
+    delete next[key];
+    return next;
+}
+/** Replace an item's label list, dropping the field entirely when nothing is left. */
+function withLabels(e, labels, at) {
+    if (labels.length === 0) {
+        const next = { ...e, updatedAt: at };
+        delete next.labels;
+        return next;
+    }
+    return { ...e, labels, updatedAt: at };
+}
+/** Replace an item's share receipts, dropping the field entirely when nothing is left. */
+function withShares(e, shares, at) {
+    if (shares.length === 0) {
+        const next = { ...e, updatedAt: at };
+        delete next.shares;
+        return next;
+    }
+    return { ...e, shares, updatedAt: at };
+}
+/**
+ * Apply one settings patch, returning new settings. Returns the SAME reference when nothing
+ * changed, so callers can skip a save (a version bump every other device must download).
+ *
+ * A text scale is CLAMPED into the codec's bounds here — this is the one write path, so a value
+ * the slider or the typed field lets through never reaches the wire out of range.
+ */
+export function applySettingsPatch(settings, patch) {
+    const next = { ...settings };
+    if (patch.developerMode !== undefined) {
+        if (patch.developerMode)
+            next.developerMode = true;
+        else
+            delete next.developerMode;
+    }
+    if (patch.paddingMode !== undefined) {
+        // The default is spelled as absence, like every other field here — so two devices that both
+        // "choose the default" write the same bytes and neither bumps the list's version.
+        if (patch.paddingMode === "pow2")
+            next.paddingMode = "pow2";
+        else
+            delete next.paddingMode;
+    }
+    if (patch.textScalePct !== undefined && Number.isFinite(patch.textScalePct)) {
+        const pct = Math.round(Math.min(TEXT_SCALE_MAX_PCT, Math.max(TEXT_SCALE_MIN_PCT, patch.textScalePct)));
+        if (pct === TEXT_SCALE_DEFAULT_PCT)
+            delete next.textScalePct;
+        else
+            next.textScalePct = pct;
+    }
+    const same = (next.developerMode === true) === (settings.developerMode === true) &&
+        next.paddingMode === settings.paddingMode &&
+        next.textScalePct === settings.textScalePct;
+    return same ? settings : next;
+}
+/** Replay a whole queue in order. Used to rebuild after a version conflict. */
+export function applyIntents(entries, intents) {
+    return intents.reduce(applyIntent, entries);
+}
+/**
+ * True when the intent touches storage the server also tracks, so a save must not be deferred.
+ *
+ * A queued save that dies with the tab is recoverable for a rename (the name is only in the
+ * manifest, and losing it leaves the old name — annoying, not damaging). It is NOT recoverable
+ * when a file was just committed or just deleted: the storage record moved, and a manifest that
+ * disagrees leaves a file that is paid for but invisible, or one that shows but is gone.
+ *
+ * Stars, pins and labels are deliberately NOT in this list: they exist only in the manifest, so the
+ * worst a lost save can do is leave a file unstarred — the same recoverable loss as a rename.
+ *
+ * SHARE RECEIPTS ARE, for the same reason a commit is: they describe a row the server now
+ * holds, and nothing else on this side records it. A receipt lost with the tab does not degrade to
+ * a wrong colour — it degrades to a share this device can never again hold the server to.
+ * `sharePrune` stays out: losing it leaves a settled receipt that the next listing prunes again.
+ */
+export function mustSaveNow(intent) {
+    return (intent.op === "add" ||
+        intent.op === "trash" ||
+        intent.op === "purge" ||
+        intent.op === "shareRecord" ||
+        intent.op === "shareRevoked");
+}
+function upsert(entries, entry) {
+    const at = entries.findIndex((e) => e.id === entry.id);
+    if (at < 0)
+        return [...entries, entry];
+    const next = entries.slice();
+    next[at] = entry;
+    return next;
+}
+function patchOne(entries, id, patch) {
+    // ⚠ FOUND BY VALUE, NOT BY INDEX. `entries[at]` after a `findIndex` is provably present and the
+    //    compiler cannot know it — which is fine here and NOT fine in the copy of this file that
+    //    ships inside the `nmts` command, where `noUncheckedIndexedAccess` is on. Reaching for the
+    //    element itself needs no assertion in either build.
+    const found = entries.find((e) => e.id === id);
+    // Absent = another device removed it. Adding it back would undo a deletion the person made.
+    if (found === undefined)
+        return entries;
+    const updated = patch(found);
+    if (updated === found)
+        return entries;
+    return entries.map((e) => (e === found ? updated : e));
+}
+/** Patch every entry the callback changes. Used by the label sweeps, which are not id-addressed. */
+function patchAll(entries, patch) {
+    let changed = false;
+    const next = entries.map((e) => {
+        const updated = patch(e);
+        if (updated !== e)
+            changed = true;
+        return updated;
+    });
+    return changed ? next : entries;
+}
+function patchMany(entries, ids, patch) {
+    let changed = false;
+    const next = entries.map((e) => {
+        if (!ids.has(e.id))
+            return e;
+        const updated = patch(e);
+        if (updated !== e)
+            changed = true;
+        return updated;
+    });
+    return changed ? next : entries;
+}

package/dist/shared/lib/drive/manifest-settings.js

@@ -0,0 +1,65 @@
+// The account-level settings that ride inside the sealed file list, and how they travel.
+//
+// ⛔ THEY ARE IN THE SEALED LIST BECAUSE THE SERVER MUST NOT LEARN THEM. Each one would otherwise
+//    be a small per-account fingerprint a server could keep, and each follows the account rather
+//    than the device, so two machines behave the same way for one person.
+//
+// ⛔ A SETTING IS NOT SAVED BECAUSE IT IS DECLARED — it is saved because both functions below name
+//    it. One shipped declared, written by its own screen and read by the uploader, and carried by
+//    NEITHER direction: every save dropped it silently, on every device, and the test standing
+//    beside it listed the fields it checked and so could only check what somebody remembered to
+//    list. That test is now typed so a field added here and not added there does not compile.
+/** The sanity bounds a stored text scale must sit in to be USED. One place; codec and UI agree. */
+export const TEXT_SCALE_MIN_PCT = 80;
+export const TEXT_SCALE_MAX_PCT = 160;
+/** Follow the device. Not written to the wire — absence is the only spelling of it. */
+export const TEXT_SCALE_DEFAULT_PCT = 100;
+/** Settings → wire, or null when every field is at its default (then nothing is written). */
+export function settingsToWire(s) {
+    if (!s)
+        return null;
+    const w = {};
+    if (s.developerMode)
+        w.dm = 1;
+    if (typeof s.textScalePct === "number" &&
+        Number.isFinite(s.textScalePct) &&
+        s.textScalePct !== TEXT_SCALE_DEFAULT_PCT &&
+        s.textScalePct >= TEXT_SCALE_MIN_PCT &&
+        s.textScalePct <= TEXT_SCALE_MAX_PCT) {
+        w.tx = Math.round(s.textScalePct);
+    }
+    if (s.paddingMode === "pow2")
+        w.pd = "pow2";
+    return w.dm !== undefined || w.tx !== undefined || w.pd !== undefined ? w : null;
+}
+/**
+ * Wire → settings, dropping anything unusable. A text scale outside the bounds is DROPPED, not
+ * clamped: rendering a whole app at a number some other build miswrote is worse than falling back
+ * to the device's own size, which is always readable.
+ */
+export function settingsFromWire(w) {
+    if (!w || typeof w !== "object")
+        return undefined;
+    // Read field by field rather than asserting the shape: this arrives from a sealed blob some
+    // other build wrote, and every field below is checked before it is used anyway.
+    const dm = Reflect.get(w, "dm");
+    const tx = Reflect.get(w, "tx");
+    const pd = Reflect.get(w, "pd");
+    const s = {};
+    if (dm === 1)
+        s.developerMode = true;
+    if (typeof tx === "number" &&
+        Number.isFinite(tx) &&
+        tx !== TEXT_SCALE_DEFAULT_PCT &&
+        tx >= TEXT_SCALE_MIN_PCT &&
+        tx <= TEXT_SCALE_MAX_PCT) {
+        s.textScalePct = Math.round(tx);
+    }
+    // An unknown rule is DROPPED, not guessed at: padding a file by a rule this build does not know
+    // would give it a size no reader here can undo. Falling back to the default is always readable.
+    if (pd === "pow2")
+        s.paddingMode = "pow2";
+    return s.developerMode !== undefined || s.textScalePct !== undefined || s.paddingMode !== undefined
+        ? s
+        : undefined;
+}

package/dist/shared/lib/drive/name-conflict.js

@@ -0,0 +1,121 @@
+// What to do when an upload's name is already in use in its destination folder. ⚠ PUBLISHED —
+// copied byte-for-byte into the `nmts` command-line package; keep comments self-contained English.
+//
+// UNTIL 2026-08-25 NOTHING WAS ASKED: a taken name silently became `report (2).pdf`. The owner
+//   changed that — "there is a file with this name" and two choices, the way a desktop does it,
+//   with "do this for all of them" when several files arrive at once.
+//
+// WHY THIS FILE IS PURE AND SEPARATE FROM THE DIALOG. Three callers need the same answer and only
+//   one of them has a screen: the browser asks a person, the S3 gateway and the command line
+//   follow a setting chosen once at setup. Putting the rule in the dialog would mean the headless
+//   paths either duplicate it or drift from it.
+//
+// ⛔ OVERWRITE IS NOT UNDOABLE AND THIS FILE DOES NOT SOFTEN THAT. NMTS keeps no previous versions
+//    (an automatic version history would spend the person's own storage on every generation), so
+//    the old file is gone. What this returns is the intent; the caller is what destroys anything.
+//
+// ⛔ EXACT-MATCH COMPARISON, matching `unique-name.ts`: the drive holds `A.txt` and `a.txt` as two
+//    files, so a case-insensitive collision here would offer to replace a file the person can see
+//    is named differently.
+import { uniqueFileName } from "./unique-name.js";
+/**
+ * Which of these collide, in batch order.
+ *
+ * ⛔ THE TAKEN SET GROWS AS THIS WALKS. Two files called `report.pdf` in one drop collide with each
+ *    other, not only with the drive — and a caller that asked only about the drive would give both
+ *    the same name. So a name that has been handed out here counts as taken from then on, and the
+ *    second one is reported as a conflict too.
+ */
+export function findConflicts(batch, takenIn) {
+    const extra = new Map();
+    const seen = (parentId) => {
+        let set = extra.get(parentId);
+        if (!set) {
+            set = new Set();
+            extra.set(parentId, set);
+        }
+        return set;
+    };
+    const out = [];
+    batch.forEach((item, at) => {
+        const already = takenIn(item.parentId).has(item.name) || seen(item.parentId).has(item.name);
+        if (already)
+            out.push({ at, name: item.name, parentId: item.parentId });
+        seen(item.parentId).add(item.name);
+    });
+    return out;
+}
+/**
+ * Apply the choices and hand back what each file becomes.
+ *
+ * `choiceFor` is asked only about names that actually collide, one at a time and in batch order, so
+ * a screen can put the question to a person and this walk waits. Anything it is not asked about
+ * keeps its name. A batch answer ("do this for all") is the caller returning the same value from
+ * then on without asking again — this file does not need to know that happened.
+ *
+ * ⛔ A RENAME CONSUMES THE NAME IT WAS GIVEN, an overwrite does not. Two files called `report.pdf`
+ *    both overwriting would otherwise be two writes to one name — the second wins and the first is
+ *    lost with nothing said. So the second one is renamed regardless of the choice, and the caller
+ *    can see that because the name it gets back is not the name it asked for.
+ */
+export async function settle(batch, takenIn, choiceFor, 
+/**
+ * Can the thing holding this name be replaced at all?
+ *
+ * ⛔ A FOLDER CAN HOLD THE NAME. Offering "overwrite" then would offer to delete a folder and
+ *    everything under it in order to store one file, from a dialog that names a file. Nothing
+ *    asks; those are renamed, which is what happened before anything was asked at all.
+ * ⚠ Left out means everything is replaceable, which is right for callers whose names are all
+ *   files (the S3 gateway has no folders).
+ */
+overwritable = () => true) {
+    const conflicts = new Map();
+    const found = findConflicts(batch, takenIn);
+    for (const c of found)
+        conflicts.set(c.at, c);
+    const handedOut = new Map();
+    const given = (parentId) => {
+        let set = handedOut.get(parentId);
+        if (!set) {
+            set = new Set();
+            handedOut.set(parentId, set);
+        }
+        return set;
+    };
+    const takenNow = (parentId) => new Set([...takenIn(parentId), ...given(parentId)]);
+    const overwrittenHere = new Map();
+    const overwritten = (parentId) => {
+        let set = overwrittenHere.get(parentId);
+        if (!set) {
+            set = new Set();
+            overwrittenHere.set(parentId, set);
+        }
+        return set;
+    };
+    const out = [];
+    let asked = 0;
+    for (const [at, item] of batch.entries()) {
+        const conflict = conflicts.get(at);
+        if (conflict === undefined) {
+            given(item.parentId).add(item.name);
+            out.push({ name: item.name, parentId: item.parentId });
+            continue;
+        }
+        const renamedTo = uniqueFileName(item.name, takenNow(item.parentId));
+        if (!overwritable(conflict)) {
+            given(item.parentId).add(renamedTo);
+            out.push({ name: renamedTo, parentId: item.parentId });
+            continue;
+        }
+        asked += 1;
+        const choice = await choiceFor({ ...conflict, renamedTo, remaining: found.length - asked });
+        if (choice === "overwrite" && !overwritten(item.parentId).has(item.name)) {
+            overwritten(item.parentId).add(item.name);
+            out.push({ name: item.name, parentId: item.parentId, replaces: item.name });
+            continue;
+        }
+        given(item.parentId).add(renamedTo);
+        out.push({ name: renamedTo, parentId: item.parentId });
+    }
+    return out;
+}