@needmoretruth/nmts-cli 0.36.3 → 0.38.0

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 Each version's entry is what changed for the person or the program using `nmts`. The product's own
 update history, which covers the site and the server too, is at https://nmts.me/updates.
 
+## 0.38.0 — 2026-09-19
+
+- The library surface has a new entry, `@needmoretruth/nmts-cli/s3-gateway`: the S3 server `nmts s3`
+  runs, taking a function that says which drive a bucket name means and a list of key pairs that
+  may each be held to named buckets, so a program can put it in front of more than one account and
+  mount it in a server of its own. `nmts s3` is unchanged: the same output, the same bucket, the same
+  refusals. `nmts-sdk` 0.4.0 is built on it.
+
+## 0.37.0 — 2026-09-19
+
+- The library surface has a new entry, `@needmoretruth/nmts-cli/drive-edit`: the list edits behind
+  `mkdir`, `mv`, `rename`, `rm` and `restore` as functions that print nothing and refuse with a
+  `code` (`NOT_FOUND`, `NAME_TAKEN`, `BAD_NAME`, `NOT_IN_TRASH`, `INTO_ITSELF`). The commands call the
+  same functions and print what they printed before. `nmts-sdk` 0.3.0 is built on it.
+- Six command documents called the NMTS key "code", the name it had before; `nmts help extend`
+  carried an empty code block.
+
 ## 0.36.3 — 2026-09-19
 
 - `--help` had the `--on-collision` lines in the middle of the `--part-size` description, so the

package/README.ko.md

@@ -50,7 +50,7 @@ nmts --help
 
 ```sh
 npm install -g github:needmoretruth/nmts-cli            # 기본 브랜치
-npm install -g github:needmoretruth/nmts-cli#v0.36.3    # 버전을 고정할 때
+npm install -g github:needmoretruth/nmts-cli#v0.38.0    # 버전을 고정할 때
 npm install -g https://github.com/needmoretruth/nmts-cli/releases/latest/download/nmts.tgz
 ```
 

package/README.md

@@ -51,7 +51,7 @@ default branch, from a pinned version, or from the tarball attached to the
 
 ```sh
 npm install -g github:needmoretruth/nmts-cli            # the default branch
-npm install -g github:needmoretruth/nmts-cli#v0.36.3    # a pinned version
+npm install -g github:needmoretruth/nmts-cli#v0.38.0    # a pinned version
 npm install -g https://github.com/needmoretruth/nmts-cli/releases/latest/download/nmts.tgz
 ```
 

package/dist/artifact-about.d.ts

@@ -11,7 +11,7 @@ export declare const CRYPTO_SPEC_URL = "https://github.com/needmoretruth/nmts-re
  *   is the field's own contract — what the writer says about itself — and a person holding two
  *   copies of one account's artefacts can then tell which program made each.
  */
-export declare const WRITTEN_BY = "nmts-cli 0.36.3";
+export declare const WRITTEN_BY = "nmts-cli 0.38.0";
 /** Which of the three artefacts a wrapper is. A reader holding several can sort them. */
 export type ArtifactKind = "recovery-list" | "file-list" | "recovery-kit";
 /**

package/dist/commands/erase.js

@@ -26,7 +26,7 @@ import { applyToList, batchTargets } from "../manifest-write.js";
 import { BINARY_NAME } from "../product.js";
 import { promptLine, stdinIsATerminal } from "../prompt.js";
 import { openSession } from "../session.js";
-import { filesUnder } from "./trash.js";
+import { filesUnder } from "../drive-edit.js";
 /** The server takes at most this many ids in one erase (`ERASE_BATCH_MAX`). */
 const BATCH = 200;
 /** The refusal a no-deposit release gets when the balance cannot cover the doubled fee. */

package/dist/commands/organise.d.ts

@@ -1,4 +1,3 @@
-import { openSession } from "../session.ts";
 export interface OrganiseOptions {
     server?: string | undefined;
     network?: string | undefined;
@@ -8,38 +7,17 @@ export interface OrganiseOptions {
 /**
  * Make a folder, and any folder above it that is missing.
  *
- * ⚠ MISSING PARENTS ARE CREATED, and that is a decision rather than a convenience. A folder costs
- *   nothing, holds nothing and can be moved to the trash, so the failure mode of creating one too
- *   many is a tidy-up; the failure mode of refusing is an agent that has to discover the tree one
- *   command at a time. Every folder made is named in the output, so it is never a surprise.
+ * ⚠ MISSING PARENTS ARE CREATED, and that is a decision rather than a convenience — the reason is
+ *   beside the code that does it, in `drive-edit.ts`. Every folder made is named in the output, so
+ *   it is never a surprise.
  */
-/**
- * Make a folder path, and every folder above it that is missing, under an OPEN session.
- *
- * ⛔ SPLIT OUT SO AN UPLOAD OF A WHOLE DIRECTORY CAN USE IT. The rules below are the ones a second
- *    copy would get subtly wrong: a folder that is already there IS the folder asked for (never a
- *    numbered one), the decision is taken inside each attempt so a lost race cannot make two, and
- *    what was made before a failure is named rather than silently kept.
- */
-export declare function ensureFolderPath(session: Awaited<ReturnType<typeof openSession>>, wanted: string): Promise<{
-    parentId: string | null;
-    made: string[];
-}>;
 export declare function mkdir(path: string | undefined, options?: OrganiseOptions): Promise<number>;
 /**
  * Move things into a folder. Every operand but the last is something to move; the last is where
  * they go, and an empty one means the top of the drive.
  *
- * ⛔ ONE WRITE FOR THE WHOLE RUN, however many things are named. The list is rewritten whole on
- *    every save, so a second thing costs nothing extra — while a second WRITE is a second chance
- *    to lose the compare-and-swap, and losing it half way through a run leaves some things moved
- *    and some not, which is a state the caller cannot tell apart from the one it asked for.
- *
- * ⛔ AND THE NAME CHECK RUNS AGAINST WHAT THIS RUN HAS ALREADY MOVED, not against the list as it
- *    was read. Two files called `notes.txt` in two folders, moved into one folder by one command,
- *    would otherwise both be written — two entries at one path, which no command in this tool can
- *    address afterwards: every one of them answers "names 2 things in this account". So the loop
- *    folds each move onto a working copy and asks the working copy the next question.
+ * ⛔ ONE WRITE FOR THE WHOLE RUN, however many things are named, and every guard is re-decided
+ *    inside the attempt. Both reasons are in `drive-edit.ts`, beside the loop that keeps them.
  */
 export declare function mv(operands: readonly string[], options?: OrganiseOptions): Promise<number>;
 /** Give one thing a new name. The path stays the same otherwise. */

package/dist/commands/organise.js

@@ -1,5 +1,9 @@
 // `nmts mkdir`, `nmts mv` and `nmts rename` — the three edits that touch no bytes.
 //
+// ⛔ WHAT THEY DO IS IN `drive-edit.ts`; WHAT IS HERE IS THE TERMINAL. The list editing moved out
+//    the day the SDK needed the same three verbs without one — one implementation, two callers, so
+//    "what does moving onto a taken name do" is answered in a single place.
+//
 // ⛔ NONE OF THESE ASKS THE SERVER TO CHANGE ANYTHING BUT THE SEALED LIST. A folder has no server
 //    row at all, and a name and a parent live only inside the list — the server holds an id, a
 //    size and a time, and was deliberately never given a place to put a name
@@ -10,97 +14,18 @@
 //
 // ⛔ AND NONE OF THEM STOPS TO ASK. Renaming, moving and making a folder are reversible and cost
 //    nothing, which is the whole test for whether this tool interrupts somebody. It does not.
-import { randomUUID } from "node:crypto";
-import { buildIndex, entryAt, folderIdFor, fullPathOf, KIND_FOLDER, namesIn, normaliseName, normalisePath, } from "../drive-paths.js";
+import { makeFolder, moveEntries, renameEntry, requireNewName } from "../drive-edit.js";
+import { normalisePath } from "../drive-paths.js";
 import { NmtsError } from "../errors.js";
-import { readFileList } from "../manifest.js";
-import { applyManyToList, applyToList, batchTargets } from "../manifest-write.js";
 import { openSession } from "../session.js";
-import { applyIntent } from "../shared/lib/drive/manifest-ops.js";
 const say_ = (line) => void process.stdout.write(`${line}\n`);
 /**
  * Make a folder, and any folder above it that is missing.
  *
- * ⚠ MISSING PARENTS ARE CREATED, and that is a decision rather than a convenience. A folder costs
- *   nothing, holds nothing and can be moved to the trash, so the failure mode of creating one too
- *   many is a tidy-up; the failure mode of refusing is an agent that has to discover the tree one
- *   command at a time. Every folder made is named in the output, so it is never a surprise.
- */
-/**
- * Make a folder path, and every folder above it that is missing, under an OPEN session.
- *
- * ⛔ SPLIT OUT SO AN UPLOAD OF A WHOLE DIRECTORY CAN USE IT. The rules below are the ones a second
- *    copy would get subtly wrong: a folder that is already there IS the folder asked for (never a
- *    numbered one), the decision is taken inside each attempt so a lost race cannot make two, and
- *    what was made before a failure is named rather than silently kept.
+ * ⚠ MISSING PARENTS ARE CREATED, and that is a decision rather than a convenience — the reason is
+ *   beside the code that does it, in `drive-edit.ts`. Every folder made is named in the output, so
+ *   it is never a surprise.
  */
-export async function ensureFolderPath(session, wanted) {
-    const made = [];
-    let parentId = null;
-    let walked = "";
-    for (const name of wanted.split("/")) {
-        // ⚠ A name that is only spaces is refused too. `mkdir` used to accept it, and then `rm` and
-        //   `restore` rejected the very path `ls` printed for it as "no path given" — a code-2 message
-        //   blaming the caller for an argument they had supplied (2026-08-23).
-        if (name.trim() === "" || name === "." || name === "..") {
-            throw new NmtsError(`"${wanted}" is not a folder path this tool will make.`, {
-                exitCode: 2,
-                nextStep: `Empty names, "." and ".." are not folder names in a drive. Nothing was made.`,
-            });
-        }
-        walked = walked === "" ? name : `${walked}/${name}`;
-        const under = parentId;
-        const here = walked;
-        const fresh = randomUUID();
-        let landedOn = fresh;
-        // ⛔ ONE WRITE PER FOLDER, and the check that decides whether to write happens INSIDE the
-        //    attempt. Two things went wrong when it sat outside (2026-08-23):
-        //      · running `mkdir` twice at the same moment made `shared` AND `shared (2)`, because the
-        //        loser of the compare-and-swap re-applied a decision taken against the older list;
-        //      · a trashed folder of the same name made the second `mkdir` produce `photos (2)` while
-        //        printing `Made "photos"`, because it went through the upload helper — and picking a
-        //        free name is the right rule for BYTES and the wrong rule for a folder. A folder with
-        //        that name in that parent IS the folder that was asked for.
-        //    Building the whole chain in memory and writing once would be fewer round trips and would
-        //    also mean a lost compare-and-swap threw away folders the ones below already point at.
-        const result = await applyToList(session, (entries) => {
-            const there = entries.find((e) => e.parentId === under &&
-                normaliseName(e.name) === normaliseName(name) &&
-                e.deletedAt === undefined);
-            if (there !== undefined) {
-                if (there.kind !== KIND_FOLDER) {
-                    throw new NmtsError(`"${here}" is a file, so nothing can be made inside it.`, {
-                        exitCode: 4,
-                        nextStep: made.length > 0 ? `The folders made so far are kept: ${made.join(", ")}.` : "Nothing was made.",
-                    });
-                }
-                landedOn = there.id;
-                return null;
-            }
-            landedOn = fresh;
-            const at = Date.now();
-            return {
-                op: "add",
-                entry: { id: fresh, parentId: under, kind: KIND_FOLDER, name, size: 0, createdAt: at, updatedAt: at },
-            };
-        }).catch((error) => {
-            // ⛔ WHAT SURVIVED IS NAMED. A run that stops half way leaves real folders behind, and the
-            //    message that says so was attached only to the "that is a file" refusal.
-            if (error instanceof NmtsError || made.length === 0)
-                throw error;
-            const because = error instanceof Error ? error.message : "the server refused";
-            throw new NmtsError(because, {
-                exitCode: 1,
-                nextStep: `The folders made so far are kept: ${made.join(", ")}. Running the same command again ` +
-                    `makes the rest — nothing is lost.`,
-            });
-        });
-        if (result.changed)
-            made.push(here);
-        parentId = landedOn;
-    }
-    return { parentId, made };
-}
 export async function mkdir(path, options = {}) {
     const say = options.write ?? say_;
     const wanted = normalisePath(path ?? "");
@@ -108,7 +33,7 @@ export async function mkdir(path, options = {}) {
         throw new NmtsError("`nmts mkdir` needs the path of the folder to make.", { exitCode: 2 });
     }
     const session = await openSession(options);
-    const { parentId, made } = await ensureFolderPath(session, wanted);
+    const { parentId, made } = await makeFolder(session, wanted);
     if (options.json) {
         say(JSON.stringify({ path: wanted, id: parentId, made }));
         return 0;
@@ -125,16 +50,8 @@ export async function mkdir(path, options = {}) {
  * Move things into a folder. Every operand but the last is something to move; the last is where
  * they go, and an empty one means the top of the drive.
  *
- * ⛔ ONE WRITE FOR THE WHOLE RUN, however many things are named. The list is rewritten whole on
- *    every save, so a second thing costs nothing extra — while a second WRITE is a second chance
- *    to lose the compare-and-swap, and losing it half way through a run leaves some things moved
- *    and some not, which is a state the caller cannot tell apart from the one it asked for.
- *
- * ⛔ AND THE NAME CHECK RUNS AGAINST WHAT THIS RUN HAS ALREADY MOVED, not against the list as it
- *    was read. Two files called `notes.txt` in two folders, moved into one folder by one command,
- *    would otherwise both be written — two entries at one path, which no command in this tool can
- *    address afterwards: every one of them answers "names 2 things in this account". So the loop
- *    folds each move onto a working copy and asks the working copy the next question.
+ * ⛔ ONE WRITE FOR THE WHOLE RUN, however many things are named, and every guard is re-decided
+ *    inside the attempt. Both reasons are in `drive-edit.ts`, beside the loop that keeps them.
  */
 export async function mv(operands, options = {}) {
     const say = options.write ?? say_;
@@ -148,60 +65,17 @@ export async function mv(operands, options = {}) {
         });
     }
     const session = await openSession(options);
-    const at = Date.now();
-    const outcome = { moved: [], already: [], parentId: null };
-    // ⛔ EVERY GUARD RUNS INSIDE THE ATTEMPT, INCLUDING WHICH ENTRY EACH PATH NAMES. A lost
-    //    compare-and-swap re-applies the intent to a list that changed underneath — and when the
-    //    winner had just taken this name, the loser landed on top of it and produced two entries at
-    //    one path. Meanwhile the tool exited 0 and said the move had been made.
-    const result = await applyManyToList(session, (now) => {
-        const targets = batchTargets(now, paths, { nothingHappened: "Nothing was moved." });
-        const into = folderIdFor(destination, now, "Nothing was moved.");
-        const intents = [];
-        const moved = [];
-        const already = [];
-        let working = now;
-        for (const target of targets) {
-            if (into !== null && (into === target.id || isUnder(working, into, target.id))) {
-                throw new NmtsError(`A folder cannot be moved inside itself.`, {
-                    exitCode: 4,
-                    nextStep: "Nothing was moved.",
-                });
-            }
-            if (into === target.parentId) {
-                already.push(target.name);
-                continue;
-            }
-            if (namesIn(working, into).has(normaliseName(target.name))) {
-                throw new NmtsError(`Something called "${target.name}" is already in that folder.`, {
-                    exitCode: 4,
-                    nextStep: `Nothing was moved. Rename it first: nmts rename "${target.name}" <new name>`,
-                });
-            }
-            const intent = { op: "move", id: target.id, parentId: into, at };
-            intents.push(intent);
-            working = applyIntent(working, intent);
-            moved.push({ id: target.id, name: target.name });
-        }
-        outcome.moved = moved;
-        outcome.already = already;
-        outcome.parentId = into;
-        return intents;
-    });
+    const outcome = await moveEntries(session, paths, destination);
     const shownDestination = normalisePath(destination);
     const where = shownDestination === "" ? "the top of the drive" : `"${shownDestination}"`;
     if (options.json) {
-        const index = buildIndex(result.entries);
         say(JSON.stringify({
-            moved: outcome.moved.map((m) => {
-                const live = result.entries.find((e) => e.id === m.id);
-                return { id: m.id, name: m.name, path: live === undefined ? null : fullPathOf(index, live) };
-            }),
+            moved: outcome.moved.map((m) => ({ id: m.id, name: m.name, path: m.path })),
             already: outcome.already,
             parentId: outcome.parentId,
-            changed: result.changed,
-            reappliedAfterConflict: result.reappliedAfterConflict,
-            seq: result.seq,
+            changed: outcome.changed,
+            reappliedAfterConflict: outcome.reappliedAfterConflict,
+            seq: outcome.seq,
         }));
         return 0;
     }
@@ -214,7 +88,7 @@ export async function mv(operands, options = {}) {
     if (outcome.moved.length > 0 && outcome.already.length > 0) {
         say(`  ${outcome.already.map((n) => `"${n}"`).join(", ")} was already there.`);
     }
-    if (result.changed && result.reappliedAfterConflict) {
+    if (outcome.changed && outcome.reappliedAfterConflict) {
         say(`  Another device wrote the file list first, so this was applied to that version.`);
     }
     return 0;
@@ -228,61 +102,27 @@ export async function rename(path, name, options = {}) {
             nextStep: `For example: nmts rename notes.txt "meeting notes.txt"`,
         });
     }
-    if (name.includes("/")) {
-        throw new NmtsError(`A name cannot contain "/" — that is what makes it a path.`, {
-            exitCode: 2,
-            nextStep: `To move it, use \`nmts mv\`. Nothing was renamed.`,
-        });
-    }
+    // ⛔ ASKED HERE AS WELL AS INSIDE, AND IT IS THE SAME FUNCTION RATHER THAN A SECOND COPY. A name
+    //    with a `/` in it is wrong about the ARGUMENT, so it is refused before a session is opened —
+    //    otherwise a machine with no API key would be told about the key instead of about the name
+    //    that was typed.
+    requireNewName(name);
     const session = await openSession(options);
-    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
-    const entries = list.manifest?.entries ?? [];
-    const target = entryAt(entries, path, { nothingHappened: "Nothing was renamed." });
-    const at = Date.now();
-    const before = fullPathOf(buildIndex(entries), target);
-    // ⛔ REFUSED RATHER THAN NUMBERED, AND THE REFUSAL IS RE-DECIDED ON EVERY ATTEMPT. An upload
-    //    picks `report (2).pdf` because nobody was watching; a rename is somebody typing a name on
-    //    purpose, and silently giving them a different one is how two files end up looking like a
-    //    mistake nobody made. Checking once, before the write, was not enough: when another device
-    //    took the name in between, the retry re-applied the old decision and produced two entries at
-    //    one path, which no command in this tool can address afterwards (2026-08-23).
-    const result = await applyToList(session, (now) => {
-        const live = now.find((e) => e.id === target.id);
-        if (live === undefined)
-            return null;
-        if (normaliseName(name) !== normaliseName(live.name) && namesIn(now, live.parentId).has(normaliseName(name))) {
-            throw new NmtsError(`Something called "${name}" is already in that folder.`, {
-                exitCode: 4,
-                nextStep: "Nothing was renamed.",
-            });
-        }
-        return { op: "rename", id: target.id, name, at };
-    });
-    return report(say, options, result.changed, result.reappliedAfterConflict, {
-        text: result.changed ? `Renamed "${before}" to "${name}".` : `"${before}" is already called that.`,
+    const outcome = await renameEntry(session, path, name);
+    return report(say, options, outcome.changed, outcome.reappliedAfterConflict, {
+        text: outcome.changed
+            ? `Renamed "${outcome.fromPath}" to "${name}".`
+            : `"${outcome.fromPath}" is already called that.`,
         json: {
-            id: target.id,
-            from: target.name,
+            id: outcome.id,
+            from: outcome.from,
             to: name,
-            changed: result.changed,
-            reappliedAfterConflict: result.reappliedAfterConflict,
-            seq: result.seq,
+            changed: outcome.changed,
+            reappliedAfterConflict: outcome.reappliedAfterConflict,
+            seq: outcome.seq,
         },
     });
 }
-/** Is `id` at or under `rootId`? Used to refuse moving a folder into its own subtree. */
-function isUnder(entries, id, rootId) {
-    const byId = buildIndex(entries).byId;
-    const seen = new Set();
-    let at = id;
-    while (at !== null && !seen.has(at)) {
-        if (at === rootId)
-            return true;
-        seen.add(at);
-        at = byId.get(at)?.parentId ?? null;
-    }
-    return false;
-}
 function report(say, options, changed, conflicted, out) {
     if (options.json) {
         say(JSON.stringify(out.json));

package/dist/commands/push.js

@@ -36,7 +36,7 @@ import { createUploadApi } from "../upload-api.js";
 import { clearItemRecord, clearReservation } from "../upload-store.js";
 import { CREDIT_BYTES, partSizeFor, planAndPrice, UPLOAD_EPOCHS } from "../upload-price.js";
 import { createBlobProtocol, readCurrentEpoch } from "../walrus-write.js";
-import { ensureFolderPath } from "./organise.js";
+import { ensureFolderPath } from "../drive-edit.js";
 import { payerOf, refuseWalletOnlyOptions } from "./put.js";
 export async function push(target, options = {}) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));

package/dist/commands/s3.d.ts

@@ -1,15 +1,5 @@
 /** MinIO's port, which is what most S3 tools already have in their examples. */
 export declare const DEFAULT_PORT = 9000;
-/**
- * How long a file list may be reused before it is fetched again.
- *
- * ⛔ THERE IS A CACHE BECAUSE A SYNC IS THOUSANDS OF REQUESTS. Reading the list per request would
- *    mean a server round trip and a decryption for each one, so a listing of a large drive would
- *    take minutes and cost the account's rate budget. ⚠ It also means a file uploaded from another
- *    device can be up to this long in appearing here, which is the trade and is written in the
- *    tool's own words when it starts.
- */
-export declare const LIST_CACHE_MS = 5000;
 export interface S3Options {
     server?: string | undefined;
     network?: string | undefined;

package/dist/commands/s3.js

@@ -13,17 +13,13 @@
 //    machine -- and a gateway cannot ask, because its caller is a program and its stdin is not a
 //    terminal. So the agreement has to exist before it starts: without it the drive is served read
 //    only and every write is refused with the sentence naming the command that grants it.
-import { createWriteStream } from "node:fs";
-import { mkdir as makeDir, rm as removeFile, stat } from "node:fs/promises";
+import { rm as removeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { pipeline } from "node:stream/promises";
 import { randomUUID } from "node:crypto";
-import { createStaging } from "../s3/staging.js";
-import { refusalFor, verdictForKey } from "../s3/same-file.js";
-import { fetchFile } from "../download.js";
+import { createDriveSource, fetchObject, LIST_CACHE_MS } from "../s3/drive.js";
 import { NmtsError } from "../errors.js";
-import { ensureFolderPath } from "./organise.js";
+import { ensureFolderPath } from "../drive-edit.js";
 import { put } from "./put.js";
 import { rm } from "./trash.js";
 import { readFileList } from "../manifest.js";
@@ -34,16 +30,6 @@ import { BUCKET } from "../s3/listing.js";
 import { BIND_ADDRESS, createGateway, newCredential } from "../s3/server.js";
 /** MinIO's port, which is what most S3 tools already have in their examples. */
 export const DEFAULT_PORT = 9000;
-/**
- * How long a file list may be reused before it is fetched again.
- *
- * ⛔ THERE IS A CACHE BECAUSE A SYNC IS THOUSANDS OF REQUESTS. Reading the list per request would
- *    mean a server round trip and a decryption for each one, so a listing of a large drive would
- *    take minutes and cost the account's rate budget. ⚠ It also means a file uploaded from another
- *    device can be up to this long in appearing here, which is the trade and is written in the
- *    tool's own words when it starts.
- */
-export const LIST_CACHE_MS = 5_000;
 function portOf(raw) {
     if (raw === undefined)
         return DEFAULT_PORT;
@@ -59,16 +45,6 @@ export async function s3(options = {}) {
     const session = await openSession({ server: options.server, network: options.network });
     const chain = resolveNetwork(session.server, session.network);
     const credential = newCredential();
-    let cached = [];
-    let cachedAt = 0;
-    const entries = async () => {
-        if (Date.now() - cachedAt < LIST_CACHE_MS)
-            return cached;
-        const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
-        cached = list.manifest === null ? [] : list.manifest.entries;
-        cachedAt = Date.now();
-        return cached;
-    };
     /**
      * Where the pieces of a multipart upload wait until they are one file.
      *
@@ -78,109 +54,58 @@ export async function s3(options = {}) {
      *    takes and afterwards.
      */
     const stagingRoot = join(tmpdir(), `nmts-s3-${randomUUID()}`);
-    /**
-     * Store one local file at a drive key, making the folders above it if they are missing.
-     *
-     * ⛔ THE SAME-FILE QUESTION IS ANSWERED HERE AND NOWHERE ELSE.
-     *    Both ways of uploading — one PUT, or pieces staged and joined — end in this
-     *    function, so a rule written here cannot disagree with itself; written in the protocol layer
-     *    it would have to be written twice, once for each, and the two would differ the first time
-     *    one of them changed. What is compared is the plaintext's SHA-256 against the one this
-     *    account sealed when the file was first stored.
-     *
-     * ⛔ IDENTICAL CONTENT IS NOT AN ERROR. Nothing is sent and nothing is charged, and the caller
-     *    is told the upload finished — because the statement it was making, "that file is at that
-     *    key", is true. Answering 409 there is what made every backup run fail on every file it had
-     *    already stored, and a sync tool writes 409 down as a failure.
-     */
-    const storeFile = async (key, path) => {
-        const at = key.lastIndexOf("/");
-        const folder = at < 0 ? undefined : key.slice(0, at);
-        const name = at < 0 ? key : key.slice(at + 1);
-        const verdict = await verdictForKey(await entries(), key, session.code, path);
-        // ⭐ Already there, byte for byte. This is the whole point: an unchanged file costs nothing to
-        //    re-offer, so a backup that runs nightly stops paying for the nights nothing changed.
-        if (verdict === "same") {
-            say(`same ${key} — already stored, nothing sent`);
-            return;
-        }
-        if (verdict !== "free")
-            throw refusalFor(verdict, key);
-        if (folder !== undefined && folder !== "")
-            await ensureFolderPath(session, folder);
-        await put(path, {
-            server: options.server,
-            network: options.network,
-            ...(folder === undefined || folder === "" ? {} : { to: folder }),
-            name,
-            write: () => undefined,
-        });
-        cachedAt = 0;
-    };
     // ⛔ THE QUESTION WAS ANSWERED BEFORE THIS STARTED. A gateway cannot ask: its caller is a program
     //    and its stdin is not a terminal. `s3` is a medium act (`risk.ts`) — uploads through it spend
     //    credits — so the tier gate asked at the start, or the mode waved it through, and every write
     //    from here on is what was agreed to.
     const writable = true;
-    const server = createGateway({
-        credential,
-        source: {
-            entries,
-            ...(writable
-                ? {
-                    write: {
-                        // ⛔ THE BODY IS SPOOLED TO A FILE FIRST, 0600, and deleted whatever happens. The
-                        //    upload path reserves storage, cuts parts and seals them from a file, and giving
-                        //    it a socket instead would mean either holding whole uploads in memory or
-                        //    writing a second upload path — and a second upload path is a second place for
-                        //    "what if the reservation succeeds and the part fails" to be got right.
-                        put: async (key, body, size) => {
-                            await makeDir(stagingRoot, { recursive: true, mode: 0o700 });
-                            const spool = join(stagingRoot, randomUUID());
-                            try {
-                                await pipeline(body, createWriteStream(spool, { mode: 0o600 }));
-                                const written = (await stat(spool)).size;
-                                if (written !== size) {
-                                    throw new NmtsError(`The upload said ${size} bytes and ${written} arrived. Nothing was stored.`);
-                                }
-                                await storeFile(key, spool);
-                            }
-                            finally {
-                                await removeFile(spool, { force: true });
-                            }
-                        },
-                        multipart: createStaging(stagingRoot, storeFile),
-                        trash: async (object) => {
-                            await rm([`/${object.key}`], {
-                                server: options.server,
-                                network: options.network,
-                                write: () => undefined,
-                            });
-                            cachedAt = 0;
-                        },
-                    },
-                }
-                : {}),
-            // The real reader. The gateway takes it as a function so its own tests can be driven by a
-            // real S3 client without an account, a network or anybody's credits.
-            fetch: async (object, sink) => {
-                const wrapped = object.entry.dekWrapped;
-                if (wrapped === undefined)
-                    throw new NmtsError("That entry has no key in the file list.");
-                await fetchFile({
-                    base: session.server,
-                    apiKey: session.apiKey,
-                    accountCode: session.code,
-                    itemId: object.entry.id,
-                    size: object.size,
-                    dekWrapped: wrapped,
-                    contentHashCt: object.entry.contentHashCt,
-                    chain,
-                    sink,
+    /**
+     * This account, as the shared drive module takes it.
+     *
+     * ⛔ THE SIX FUNCTIONS ARE THE ONLY THING THIS COMMAND CONTRIBUTES. What an upload DOES — the
+     *    same-file verdict, the folders above the key, forgetting the cached list — lives in
+     *    `s3/drive.ts`, so that the gateway a business runs from the SDK and the one a person runs
+     *    here cannot come to disagree about it.
+     */
+    const source = createDriveSource({
+        stagingRoot,
+        writable,
+        onAlreadyStored: (key) => say(`same ${key} — already stored, nothing sent`),
+        account: {
+            readList: async () => {
+                const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
+                return list.manifest === null ? [] : list.manifest.entries;
+            },
+            // The command holds the code for its whole run: a person started it and is standing there.
+            withCode: (use) => use(session.code),
+            makeFolder: async (folder) => {
+                await ensureFolderPath(session, folder);
+            },
+            store: async (path, name, folder) => {
+                await put(path, {
+                    server: options.server,
+                    network: options.network,
+                    ...(folder === undefined ? {} : { to: folder }),
+                    name,
+                    write: () => undefined,
                 });
             },
+            trash: async (path) => {
+                await rm([path], {
+                    server: options.server,
+                    network: options.network,
+                    write: () => undefined,
+                });
+            },
+            fetch: (object, sink) => fetchObject({ server: session.server, bearer: session.apiKey, code: session.code, chain }, object, sink),
         },
     });
+    const server = createGateway({
+        credentials: [credential],
+        // One name, one drive — which is what a bucket is for a person serving their own account.
+        bucketOf: (name) => (name === BUCKET ? source : null),
+        bucketNames: () => [BUCKET],
+    });
     await new Promise((resolve, reject) => {
         server.once("error", (error) => {
             reject(error.code === "EADDRINUSE"