@needmoretruth/nmts-cli 0.38.1 → 0.40.0

package/AGENTS.md

@@ -42,25 +42,12 @@ once, for an unlock (`nmts help login`).
 
 ## What is built on it today
 
-Each of these works with what is published now. None of it is a plan.
-
-- **Storage for an agent.** Notes, datasets and build outputs that outlive a session or a machine,
-  encrypted before they leave it. This command does it, and so does [its MCP server](#if-your-client-speaks-mcp).
-- **Encrypted storage inside someone's product.** The [SDK](https://github.com/needmoretruth/nmts-sdk)
-  opens an NMTS account for each person who uses a product and keeps that person's files in it. The
-  NMTS key is held by the person (the product cannot read the files) or by the product
-  (`Nmts.managed`), and every SDK method works the same either way. The
-  [terms](https://nmts.me/terms) provide for it in 3.7, for commercial products too.
-- **An S3 endpoint.** `@needmoretruth/nmts-sdk/gateway` speaks S3 with a bucket and a key pair per
-  customer, so django-storages, Rails Active Storage, rclone and backup tools store into NMTS
-  unchanged.
-- **Files that come back without NMTS.** [nmts-recovery](https://github.com/needmoretruth/nmts-recovery)
-  rebuilds an account's files from Walrus with the NMTS key and the recovery list the person saved.
-  No NMTS server takes part.
-
-An account pays with credits or straight from its own wallet. From the wallet, WAL goes to Walrus
-and SUI to the chain, and NMTS takes no fee. NMTS does not inspect or certify products built with the SDK: who holds the
-keys in such a product is that product's own statement.
+- **Storage for an agent**, outliving a session or a machine: this command, or [its MCP server](#if-your-client-speaks-mcp).
+- **Encrypted storage inside a product.** The [SDK](https://github.com/needmoretruth/nmts-sdk) (`npm install @needmoretruth/nmts-sdk`; it has an `AGENTS.md` of its own) opens an account per user. The user holds the NMTS key, or the product does (`Nmts.managed`); every method works either way, and [terms](https://nmts.me/terms) 3.7 provides for it, commercially too.
+- **An S3 endpoint**, `@needmoretruth/nmts-sdk/gateway`: a bucket and a key pair per customer, so django-storages, Rails Active Storage, rclone and backup tools store into NMTS unchanged.
+- **Files that come back without NMTS.** [nmts-recovery](https://github.com/needmoretruth/nmts-recovery) rebuilds them from Walrus with the NMTS key and the recovery list the person saved. No NMTS server takes part.
+
+All of it works with what is published now. An account pays with credits or from its own wallet — WAL to Walrus, SUI to the chain, no fee to NMTS. NMTS does not inspect or certify products built with the SDK: who holds the keys in one is that product's own statement.
 
 ## What only a person can do, once
 
@@ -189,12 +176,10 @@ work around it. Setup and the sealed-code rule: `nmts help mcp`.
 
 ## Remembering this across sessions
 
-You will lose this context. The person has to put it somewhere your next session reads: the file
-your client loads from a repository root, holding the first section above and the two
-environment variable names; a saved instruction saying *the `nmts` command manages files in an
-NMTS account; run `nmts env` first, then `nmts --help`, and `nmts help <command>` before a command
-you have not used*; or, for an MCP client, the server entry. The smallest thing that works is one
-line pointing at this file.
+You will lose this context. The person has to put it somewhere your next session reads: the file your client
+loads from a repository root, holding the first section above and the two environment variable names; a saved
+instruction saying *the `nmts` command manages files in an NMTS account; run `nmts env` first, then `nmts --help`,
+and `nmts help <command>` before a command you have not used*; or, for an MCP client, the server entry. One line pointing at this file is the smallest thing that works.
 
 ## Reporting a problem or an idea
 
@@ -204,17 +189,11 @@ run at all, write to `nmts@nmts.me` with what you ran and what it said.
 
 ## Exit codes
 
-`0` done · `1` something went wrong · `2` the command line was wrong · `3` not signed in ·
-`4` the command exists but could not do it · `5` waiting on the person's agreement ·
-`130` cancelled.
+`0` done · `1` something went wrong · `2` the command line was wrong · `3` not signed in · `4` the command exists
+but could not do it · `5` waiting on the person's agreement · `130` cancelled.
 
-## Licence
+## Licence and source
 
 Apache-2.0 (it was AGPL-3.0-only until 2026-08-30). **Calling this program from your own code puts
 no obligation on your code at all.** See [LICENSING.md](https://github.com/needmoretruth/nmts-cli/blob/main/LICENSING.md) if you are asked.
-
-## Source
-
-<https://github.com/needmoretruth/nmts-cli> · The same operations as a library, for a program that calls
-NMTS from its own code: `npm install @needmoretruth/nmts-sdk` · <https://github.com/needmoretruth/nmts-sdk>
-(its own document for agents is `AGENTS.md` there).
+Source: <https://github.com/needmoretruth/nmts-cli>.

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.40.0 — 2026-09-20
+
+- The library surface has a new entry, `@needmoretruth/nmts-cli/storage-control`: what `nmts extend`
+  and `nmts wallet storage` (the listing, `split`, `merge`, `transfer`) do, without the prompts or the
+  printing. The commands are unchanged: the same reviews, the same `--yes`, the same unlock, the same
+  exit codes. `nmts-sdk` 0.6.0 is built on it.
+
+## 0.39.0 — 2026-09-20
+
+- The library surface has a new entry, `@needmoretruth/nmts-cli/drive-erase`: what `nmts erase` does,
+  without the prompt or the printing, so a program can erase files for good with the same order of
+  operations. `nmts erase` is unchanged: the same sentence to type, the same output, the same exit
+  codes. `nmts-sdk` 0.5.0 is built on it.
+- A delegation token can carry a fifth scope, `files_erase`. The server still asks for the NMTS
+  key's own proof on the two erase requests.
+
 ## 0.38.1 — 2026-09-20
 
 - The folder and trash functions behind `@needmoretruth/nmts-cli/drive-edit` no longer import

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.38.1    # 버전을 고정할 때
+npm install -g github:needmoretruth/nmts-cli#v0.40.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.38.1    # a pinned version
+npm install -g github:needmoretruth/nmts-cli#v0.40.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.38.1";
+export declare const WRITTEN_BY = "nmts-cli 0.40.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

@@ -9,28 +9,21 @@
 //    with credits, `--release-storage` asks the server to destroy the treasury's storage under
 //    each file first, which it does on the chain one blob at a time and reports per file.
 //
-// ⛔ THE SERVER GOES FIRST, THE LIST LAST. A row erased before the list entry leaves a file the
-//    person can see and never open; that is the same order the trash keeps, for the same reason.
-//    A release that fails leaves the file whole — nothing is erased behind a failed release.
+// ⛔ THE ORDER, AND WHAT IT PROTECTS, ARE IN `drive-erase.ts` — the server first, the list last, a
+//    failed release erasing nothing behind it. This file is the terminal over that: the sentence
+//    that has to be typed, the lines a person reads, and the exit code. Nothing about what is
+//    destroyed is decided twice.
 //
 // ⛔ THE SENTENCE IS TYPED IN EVERY MODE BUT SKIP-PERMISSIONS, where the tier gate's `--reason`
 //    and `--yes` stand for it — the same rule as `delete-account`, because it is the same tier.
 import { accountProofFor } from "../account-proof.js";
-import { request, ServerError } from "../api.js";
 import { currentMode } from "../autonomy.js";
 import { CONFIRM_SENTENCE } from "./delete-account.js";
-import { buildIndex, fullPathOf, KIND_FILE } from "../drive-paths.js";
+import { eraseFiles, planErase } from "../drive-erase.js";
 import { NmtsError } from "../errors.js";
-import { readFileList } from "../manifest.js";
-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 "../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. */
-const FEE_INSUFFICIENT = "DEPOSIT_FEE_INSUFFICIENT";
 export async function erase(paths, options = {}) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
     if (paths.length === 0) {
@@ -48,20 +41,11 @@ export async function erase(paths, options = {}) {
         });
     }
     const session = await openSession(options);
-    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
-    const entries = list.manifest?.entries ?? [];
-    const index = buildIndex(entries);
-    const targets = batchTargets(entries, paths, { includeTrashed: true, nothingHappened: "Nothing was erased." });
-    const files = uniqueById(targets.flatMap((t) => (t.kind === KIND_FILE ? [t] : filesUnder(entries, t.id))));
-    const going = uniqueById([...targets, ...files]);
-    if (files.length === 0) {
-        throw new NmtsError(`Nothing named holds a file; empty folders are removed with \`${BINARY_NAME} rm\`.`, {
-            exitCode: 4,
-        });
-    }
+    const plan = await planErase(session, paths);
+    const files = plan.files;
     say(`This erases ${files.length} file${files.length === 1 ? "" : "s"} for good. It cannot be undone, and not by the trash.`);
     for (const f of files)
-        say(`  ${fullPathOf(index, f)}`);
+        say(`  ${f.path}`);
     say(``);
     say(`  Erased:       the server's record of each file and this account's key to it, and its shares.`);
     if (options.releaseStorage === true) {
@@ -81,65 +65,12 @@ export async function erase(paths, options = {}) {
     }
     // ⛔ THE PROOF IS BUILT FOR THIS ONE RUN AND NOTHING KEEPS IT.
     const accountProof = await accountProofFor({ code: session.code, source: session.source });
-    const releases = [];
-    if (options.releaseStorage === true) {
-        for (const f of files) {
-            const path = fullPathOf(index, f);
-            try {
-                const reply = await request(session.server, `/v1/items/${encodeURIComponent(f.id)}/release-storage`, {
-                    method: "POST",
-                    body: {},
-                    token: session.apiKey,
-                    accountProof,
-                });
-                releases.push({ path, refused: null, ...counts(reply), ...fee(reply) });
-            }
-            catch (error) {
-                // ⛔ THE ONE REFUSAL THAT STOPS THE RUN. A file with no deposit pays twice the chain fee
-                //    out of the balance, and a balance that cannot cover it means the release did not
-                //    happen — erasing behind it would destroy the account's key to bytes that are still
-                //    being served and still being paid for. Nothing is erased, and the two numbers say
-                //    exactly how far short the balance is.
-                if (error instanceof ServerError && error.code === FEE_INSUFFICIENT) {
-                    throw new NmtsError(`${path}: releasing its storage costs ${amount(error, "needed_credits")} credits and this ` +
-                        `account has ${amount(error, "balance_credits")}. It has no deposit, so the fee comes out of the balance.`, {
-                        exitCode: 4,
-                        nextStep: `Nothing was erased. Buy credits and run this again, or leave --release-storage off ` +
-                            `to erase the file and let its storage run out on its own.`,
-                    });
-                }
-                // ⚠ "Not ours to destroy" is an answer, not a failure: the storage was bought by the
-                //   wallet, and the erase goes on. A refusal of the KEY or the proof, and anything the
-                //   server could not do, stops the run before a row is touched.
-                if (error instanceof ServerError && error.status !== 401 && error.status !== 403 && error.status < 500) {
-                    releases.push({ path, released: 0, alreadyReleased: 0, failed: 0, feeCredits: 0, fromDeposit: false, refused: error.message });
-                    continue;
-                }
-                throw error;
-            }
-        }
-    }
-    let erased = 0;
-    for (let i = 0; i < files.length; i += BATCH) {
-        const reply = await request(session.server, "/v1/items/erase", {
-            method: "POST",
-            body: { item_ids: files.slice(i, i + BATCH).map((f) => f.id) },
-            token: session.apiKey,
-            accountProof,
-        });
-        erased += typeof reply === "object" && reply !== null && typeof Reflect.get(reply, "erased") === "number"
-            ? Number(Reflect.get(reply, "erased"))
-            : 0;
-    }
-    // ⛔ THE LIST GOES LAST, and re-decided against the list as it is on this attempt: only the
-    //    ids this run erased leave it, whatever another device wrote in between.
-    const ids = new Set(going.map((e) => e.id));
-    const result = await applyToList(session, (current) => {
-        const still = current.filter((e) => ids.has(e.id)).map((e) => e.id);
-        return still.length === 0 ? null : { op: "purge", ids: still };
+    const outcome = await eraseFiles({ ...session, accountProof }, plan, {
+        releaseStorage: options.releaseStorage === true,
     });
+    const { erased, releases } = outcome;
     if (options.json) {
-        say(JSON.stringify({ erased, files: files.map((f) => ({ id: f.id, path: fullPathOf(index, f) })), releases, seq: result.seq }));
+        say(JSON.stringify({ erased, files: outcome.files, releases, seq: outcome.seq }));
         return 0;
     }
     say(`Erased ${erased} file${erased === 1 ? "" : "s"}. Their entries are out of the file list.`);
@@ -165,29 +96,3 @@ function feeLine(r) {
         ? `${credits} taken from that file's deposit — nothing came out of the balance`
         : `${credits} taken from the balance — that file had no deposit, so the fee is doubled`;
 }
-/** The three counts a release answers with, read defensively. */
-function counts(reply) {
-    const n = (name) => {
-        const v = typeof reply === "object" && reply !== null ? Reflect.get(reply, name) : undefined;
-        return typeof v === "number" ? v : 0;
-    };
-    return { released: n("released"), alreadyReleased: n("already_released"), failed: n("failed") };
-}
-/** What it cost, read the same defensive way. An older server says neither, which reads as 0. */
-function fee(reply) {
-    const at = (name) => typeof reply === "object" && reply !== null ? Reflect.get(reply, name) : undefined;
-    const charged = at("fee_credits");
-    return {
-        feeCredits: typeof charged === "number" ? charged : 0,
-        fromDeposit: at("from_deposit") === true,
-    };
-}
-/** One credit amount out of a refusal's details, or `?` when the server did not name it. */
-function amount(error, field) {
-    const value = error.details[field];
-    return typeof value === "number" ? String(value) : "?";
-}
-function uniqueById(list) {
-    const seen = new Set();
-    return list.filter((e) => (seen.has(e.id) ? false : (seen.add(e.id), true)));
-}

package/dist/commands/extend.d.ts

@@ -1,4 +1,4 @@
-import { type ExtendReads, type SignExtension } from "../extend-plan.ts";
+import type { ExtendReads, SignExtension } from "../extend-plan.ts";
 import type { StandingTipInput } from "../standing-tip.ts";
 export interface ExtendOptions {
     server?: string | undefined;
@@ -14,8 +14,8 @@ export interface ExtendOptions {
     /**
      * The chain reads.
      *
-     * ⚠ A SEAM, NOT AN OPTION — no flag reaches it. See `ExtendReads`: a test that talked to a live
-     *   storage network could not run offline and could never be asked to be at its own ceiling.
+     * ⚠ A SEAM, NOT AN OPTION — no flag reaches it. A test that talked to a live storage network
+     *   could not run offline and could never be asked to be at its own ceiling.
      */
     readChain?: (network: string) => Promise<ExtendReads> | ExtendReads;
     /**

package/dist/commands/extend.js

@@ -6,9 +6,9 @@
 //    nobody — NMTS included — can reverse it. That difference is said out loud, in the output,
 //    before the agreement is asked for.
 //
-// ⛔ IT PRICES BEFORE IT SPENDS, ALWAYS. The reads and the quote are free and happen first, so
-//    `--dry-run` answers with a real number and never reaches the key. Nothing below the quote can
-//    run without `requireWalletGrant("extend", …)` having passed.
+// ⛔ IT PRICES BEFORE IT SPENDS, ALWAYS. The reads and the quote are free and happen first
+//    (`planExtension`), so `--dry-run` answers with a real number and never reaches the key.
+//    Nothing below the quote can run without `requireWalletGrant("extend", …)` having passed.
 //
 // ⛔ THE SERVER DOES NOT EXTEND ANYTHING, and this command is shaped by that. `POST
 //    /v1/items/{id}/extended` means "record an extension the device already signed": the storage is
@@ -19,21 +19,19 @@
 // ⛔ AND A FILE THAT IS NOT RUNNING OUT IS NOT EXTENDED BY ACCIDENT. Extending early loses nothing
 //    — epochs are added to what is left — so this is not a refusal on principle; it is a refusal
 //    to spend money on a deadline nobody is near, unless somebody says so with `--yes`.
+//
+// ⚠ WHAT IS DECIDED HERE AND WHAT IS NOT. The reads, the arithmetic, the price, the balances, the
+//   signature and the recording are `storage-control.ts`, which the SDK calls as well; this file is
+//   the terminal over them — the sentences, the agreement, the standing gift and the exit code.
 import { recordWalletSpend, requireWalletGrant } from "../wallet-grant.js";
-import { request } from "../api.js";
-import { buildIndex, entryAt, fullPathOf, KIND_FILE, normalisePath } from "../drive-paths.js";
 import { NmtsError } from "../errors.js";
-import { daysLeftInWords, daysLeftUntilEpoch, stageOf, } from "../expiry.js";
-import { asExtendPreview, chooseEpochs, headroom, soonestEnd, } from "../extend-plan.js";
-import { isRecord } from "../guards.js";
-import { readFileList } from "../manifest.js";
+import { daysLeftInWords } from "../expiry.js";
+import { describeBudget, shortfallNextStep } from "../extend-budget.js";
 import { resolveNetwork } from "../network.js";
 import { BINARY_NAME } from "../product.js";
 import { openSession } from "../session.js";
-import { coinAmount, walletAddress } from "../wallet.js";
-import { payingWalletIndex } from "../wallet-pay-index.js";
-import { activeWalletOf } from "../shared/lib/drive/manifest-settings.js";
-import { budgetFacts, describeBudget, readBudget, shortfallNextStep } from "../extend-budget.js";
+import { applyExtension, planExtension } from "../storage-control.js";
+import { walletIndexOf } from "../wallet-pay-index.js";
 export async function extend(target, options = {}) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
     const now = options.now ?? Date.now();
@@ -44,129 +42,50 @@ export async function extend(target, options = {}) {
         });
     }
     const session = await openSession(options);
-    const list = await readFileList(session.server, session.apiKey, session.code, session.accountId);
-    if (list.manifest === null) {
-        throw new NmtsError("This account has no file list, so there is nothing to extend.", { exitCode: 4 });
-    }
-    const entries = list.manifest.entries;
-    // The standing share is the person's, and it is read from the same sealed list this file came from.
-    const settings = list.manifest.settings;
-    const entry = entryAt(entries, normalisePath(target), {
-        nothingHappened: "Nothing was signed and nothing was charged.",
-    });
-    if (entry.kind !== KIND_FILE) {
-        throw new NmtsError(`No file at "${fullPathOf(buildIndex(entries), entry)}".`, {
-            exitCode: 4,
-            nextStep: "That is a folder. Nothing was signed and nothing was charged — storage is bought per " +
-                "file, so this takes one file at a time.",
-        });
-    }
-    const path = fullPathOf(buildIndex(entries), entry);
-    // ⛔ THE SERVER SAYS WHICH BLOBS, AND NOTHING ELSE. Its `expiry_epoch` is client-reported and
-    //    advisory; a command that spends money reads the chain's own answer below.
-    const preview = asExtendPreview(await request(session.server, `/v1/items/${encodeURIComponent(entry.id)}/extend-preview`, {
-        token: session.apiKey,
-    }));
-    if (preview.targets.length === 0) {
-        throw new NmtsError(`Nothing on "${path}" can be extended from here.`, {
-            exitCode: 4,
-            nextStep: nothingToExtend(preview),
-        });
-    }
-    const reads = await (options.readChain ?? defaultReads)(session.network);
-    const window = await reads.readWindow();
-    if (window === null) {
-        // ⛔ Not "nothing needs extending". The two look identical from outside and mean opposite things.
-        throw new NmtsError(`The ${session.network} storage network could not be read.`, {
-            exitCode: 1,
-            nextStep: `Nothing was signed and nothing was charged. Which epoch the network is in, and how far ` +
-                `ahead it will sell, are facts only the chain has — this tool will not spend against a ` +
-                `guess. Try again, or name a different Sui node in NMTS_SUI_RPC.`,
-        });
-    }
-    const clock = window.clock;
-    const leases = await reads.readLeases(preview.targets.map((t) => t.objectId));
-    const endEpoch = soonestEnd(leases);
-    if (endEpoch === null) {
-        throw new NmtsError(`The chain holds no storage term for "${path}".`, {
-            exitCode: 4,
-            nextStep: nothingToExtend(preview),
-        });
-    }
-    const stage = stageOf(clock, endEpoch, now);
-    if (stage === "lapsed") {
-        throw new NmtsError(`The storage term for "${path}" has already ended.`, {
-            exitCode: 4,
-            nextStep: `Nothing was signed and nothing was charged. A lease is extended before it ends — once it ` +
+    // ⛔ A NUMBER THAT IS NOT ONE IS REFUSED BEFORE ANYTHING IS READ. Absent, the account's own number
+    //    comes out of the sealed list the plan reads — one read, so the address that is priced and
+    //    the address that signs cannot differ.
+    const named = options.wallet === undefined || options.wallet === "" ? undefined : walletIndexOf(options.wallet);
+    const plan = await planExtension(session, target, {
+        now,
+        epochs: options.epochs,
+        wallet: named,
+        readChain: options.readChain,
+        // ⚠ THE LAST SENTENCE IS THIS FILE'S: `nmts get` is a command at a prompt.
+        hints: {
+            lapsed: `Nothing was signed and nothing was charged. A lease is extended before it ends — once it ` +
                 `is over there is no storage object left to extend, and the bytes may already be gone. ` +
                 `\`${BINARY_NAME} get\` says whether they can still be read.`,
-        });
-    }
-    const epochs = chooseEpochs(options.epochs, headroom(leases, clock.current, window.maxAhead));
-    const newEndEpoch = endEpoch + epochs;
-    const before = daysLeftUntilEpoch(clock, endEpoch, now);
-    const after = daysLeftUntilEpoch(clock, newEndEpoch, now);
-    // ⛔ A COST THAT COULD NOT BE COMPUTED MUST NOT BECOME A COST OF ZERO. `quote` rejects rather
-    //    than defaulting, and that rejection stops this run before the agreement is asked for.
-    const frost = await reads.quote(leases, epochs);
-    const cohort = Math.max(0, ...preview.targets.map((t) => t.sharedItems));
-    const unreachable = preview.treasuryParts + preview.untrackedParts;
-    // What the wallet holds and what the chain would charge — read, never assumed (`extend-budget.ts`).
-    // ⛔ WHICH WALLET PAYS comes out of the list this run already read, before the price is measured
-    //    against a balance: the address below is the one that will sign (`wallet-pay-index.ts`).
-    const wallet = await payingWalletIndex({ ...options, readActiveWallet: async () => activeWalletOf(settings) });
-    const address = await walletAddress(session.code, wallet);
-    const budget = await readBudget(reads, {
-        address,
-        objectIds: preview.targets.map((t) => t.objectId),
-        epochs,
-        priceFrost: frost,
+        },
     });
-    const facts = {
-        file: path,
-        itemId: entry.id,
-        network: session.network,
-        epoch: clock.current,
-        endEpoch,
-        epochs,
-        newEndEpoch,
-        daysLeft: before,
-        daysLeftAfter: after,
-        blobs: leases.length,
-        priceFrost: frost.toString(),
-        priceWal: coinAmount(frost),
-        paidFrom: "wallet",
-        filesOnTheSameBlobs: cohort,
-        partsThatCannotBeExtended: unreachable,
-        ...budgetFacts(budget),
-    };
+    const { facts, budget } = plan;
     if (options.dryRun === true) {
-        // ⛔ NOTHING BELOW THIS BRANCH RUNS. No key is derived, no agreement is asked for, and the
-        //    signing module is not even loaded — `--dry-run` is a price and nothing else.
+        // ⛔ NOTHING BELOW THIS BRANCH RUNS. No key is derived for signing, no agreement is asked for,
+        //    and the signing module is not even loaded — `--dry-run` is a price and nothing else.
         if (options.json) {
             say(JSON.stringify({ ...facts, dryRun: true, signed: false }));
             return 0;
         }
-        describe(say, facts, cohort, unreachable);
+        describe(say, facts);
         describeBudget(say, budget);
         say(``);
         if (budget.shortfall !== null)
             say(`  ⚠ ${budget.shortfall} As it stands, it would be refused.`);
         say(`  Nothing was signed and nothing was charged. Run the same command without --dry-run to`);
         say(`  buy it.`);
-        if (stage === "later")
+        if (plan.stage === "later")
             say(`  It is not near its deadline, so buying it also needs --yes.`);
         return 0;
     }
     if (!options.json) {
-        describe(say, facts, cohort, unreachable);
+        describe(say, facts);
         describeBudget(say, budget);
     }
     // ⛔ ASKED AFTER THE PRICE IS KNOWN AND BEFORE ANYTHING IS SIGNED. Extending early loses nothing,
     //    so this is not a refusal on principle — it is a refusal to spend on a deadline that is not
     //    close, unless somebody says otherwise out loud.
-    if (stage === "later" && options.yes !== true) {
-        throw new NmtsError(`"${path}" is not near the end of its storage term.`, {
+    if (plan.stage === "later" && options.yes !== true) {
+        throw new NmtsError(`"${plan.path}" is not near the end of its storage term.`, {
             exitCode: 4,
             nextStep: `Nothing was signed and nothing was charged. Extending early loses nothing — the epochs ` +
                 `are added to what is left — but it spends now for time this file does not need yet. ` +
@@ -181,49 +100,37 @@ export async function extend(target, options = {}) {
     // ⛔ THE ONE GATE THAT STANDS BETWEEN A PROGRAM AND SOMEBODY'S WALLET. Everything above this line
     //    is a read; nothing below it can be undone. The grant names a scope, runs out, and may carry
     //    a ceiling — this signature is held against all three (`wallet-grant.ts`).
-    const spend = { walFrost: frost, suiMist: budget.feeMist ?? 0n };
+    const spend = { walFrost: budget.priceFrost, suiMist: budget.feeMist ?? 0n };
     requireWalletGrant("extend", spend, new Date(now));
-    const sign = options.sign ?? (await import("../wallet-sign.js")).signExtension;
-    const digest = await sign({
-        network: session.network,
-        code: session.code,
-        wallet,
-        objectIds: preview.targets.map((t) => t.objectId),
-        epochs,
+    const outcome = await applyExtension(session, plan, {
+        sign: options.sign,
+        // What left the wallet is added to the grant's ledger first — the fee as estimated, since the
+        // amount actually charged is not read back here.
+        onSigned: () => recordWalletSpend(spend),
     });
-    // What left the wallet is added to the grant's ledger first — the fee as estimated, since the
-    // amount actually charged is not read back here.
-    recordWalletSpend(spend);
-    // From here the storage IS extended. Recording it is bookkeeping, and a failure to record must
-    // never be reported as a failure to extend — that reading invites a second run, which pays again.
-    let replay = false;
-    try {
-        const recorded = await request(session.server, `/v1/items/${encodeURIComponent(entry.id)}/extended`, { method: "POST", token: session.apiKey, body: { epochs, tx_digest: digest } });
-        replay = isRecord(recorded) && recorded["replay"] === true;
-    }
-    catch (error) {
+    if (!outcome.recorded) {
         if (options.json) {
-            say(JSON.stringify({ ...facts, dryRun: false, signed: true, digest, recorded: false }));
+            say(JSON.stringify({ ...facts, dryRun: false, signed: true, digest: outcome.digest, recorded: false }));
         }
         else {
             say(``);
-            say(`  The storage IS extended and the payment has been made — transaction ${digest}.`);
+            say(`  The storage IS extended and the payment has been made — transaction ${outcome.digest}.`);
             say(`  What failed is telling the NMTS server about it, so the drive will go on showing the`);
             say(`  old date until something tells it. ⛔ Do not run this command again for this file:`);
             say(`  that would buy the same epochs a second time. Opening the account in a browser reads`);
             say(`  the chain directly.`);
-            say(`  Cause: ${error instanceof Error ? error.message : String(error)}`);
+            say(`  Cause: ${outcome.notRecorded}`);
         }
         return 1;
     }
     if (options.json) {
-        say(JSON.stringify({ ...facts, dryRun: false, signed: true, digest, recorded: true, replay }));
+        say(JSON.stringify({ ...facts, dryRun: false, signed: true, digest: outcome.digest, recorded: true, replay: outcome.replay }));
     }
     else {
         say(``);
-        say(`  Extended. The storage now ends at epoch ${newEndEpoch} — ${daysLeftInWords(after)}.`);
-        say(`  Transaction ${digest}`);
-        if (replay)
+        say(`  Extended. The storage now ends at epoch ${facts.newEndEpoch} — ${daysLeftInWords(facts.daysLeftAfter)}.`);
+        say(`  Transaction ${outcome.digest}`);
+        if (outcome.replay)
             say(`  The server had already recorded this transaction, so nothing was written twice.`);
     }
     // ⛔ AFTER THE PAYMENT, NEVER INSIDE IT, and it cannot change the answer above. In --json the
@@ -232,17 +139,19 @@ export async function extend(target, options = {}) {
         server: session.server,
         network: resolveNetwork(session.server, session.network),
         code: session.code,
-        settings,
-        wallet,
-        paidWalFrost: frost,
+        settings: plan.settings,
+        wallet: plan.wallet,
+        paidWalFrost: budget.priceFrost,
         say: options.json === true ? (line) => void process.stderr.write(`${line}\n`) : say,
         ...(options.tip ?? {}),
     });
     return 0;
 }
 /** What the numbers say, for a person, in the order somebody deciding needs them. */
-function describe(say, facts, cohort, unreachable) {
+function describe(say, facts) {
     const when = (epoch, left) => `epoch ${epoch} — ${daysLeftInWords(left)}`;
+    const cohort = facts.filesOnTheSameBlobs;
+    const unreachable = facts.partsThatCannotBeExtended;
     say(`${facts.file}`);
     say(`  Storage ends at ${when(facts.endEpoch, facts.daysLeft)}.`);
     say(`  Extending by ${facts.epochs} epoch${facts.epochs === 1 ? "" : "s"} moves that to ` +
@@ -262,21 +171,3 @@ function describe(say, facts, cohort, unreachable) {
     say(`  This is paid in WAL from the wallet this NMTS key derives — not from credits, which`);
     say(`  is what every other command in this tool spends. \`${BINARY_NAME} wallet\` shows what is in it.`);
 }
-/** Why a file has nothing to extend, said as the two different things it can be. */
-function nothingToExtend(preview) {
-    const parts = [];
-    if (preview.treasuryParts > 0) {
-        parts.push(`${preview.treasuryParts} part${preview.treasuryParts === 1 ? " is" : "s are"} on storage NMTS ` +
-            `paid for, which this account cannot extend`);
-    }
-    if (preview.untrackedParts > 0) {
-        parts.push(`${preview.untrackedParts} part${preview.untrackedParts === 1 ? " has" : "s have"} no ` +
-            `recorded storage object, so there is nothing to name on the chain`);
-    }
-    const why = parts.length === 0 ? "The server lists no storage object for it." : `${parts.join(", and ")}.`;
-    return `Nothing was signed and nothing was charged. ${why} Opening the account in a browser shows what it is stored on.`;
-}
-/** The real chain reads. Imported only when no seam was supplied — it loads the storage SDK. */
-async function defaultReads(network) {
-    return (await import("../extend-chain.js")).extendReads(network);
-}

package/dist/commands/wallet-storage-ops.d.ts

@@ -1,7 +1,7 @@
 import { type Network } from "../network.ts";
-import { type StorageOpsReads } from "../storage-control-chain.ts";
+import { type StorageOp, type StorageOpsReads } from "../storage-control.ts";
 import type { SignStorageOp } from "../wallet-sign.ts";
-export type StorageOp = "split" | "merge" | "transfer";
+export type { StorageOp } from "../storage-control.ts";
 export interface StorageOpsOptions {
     server?: string | undefined;
     network?: string | undefined;