@needmoretruth/nmts-cli 0.38.1 → 0.40.0

package/dist/drive-erase.js

@@ -0,0 +1,161 @@
+// Erasing files for good, without a terminal: the targets resolved, the treasury's storage let go,
+// the server's records destroyed and the entries taken out of the sealed list — decided, done and
+// handed back rather than printed.
+//
+// ⛔ ONE IMPLEMENTATION, TWO CALLERS, WHICH IS THE WHOLE REASON THIS FILE EXISTS — the argument
+//    `drive-edit.ts` makes one verb family over. `commands/erase.ts` is a terminal's shape: it
+//    prints the list, asks for the typed sentence and answers an exit code. The SDK is somebody
+//    else's program and needs the same act with none of those. A second implementation of "what
+//    order do these three destructions happen in" would be a second place for the rules below to
+//    be got right, and the copy nobody re-reads is the one that quietly disagrees — about the one
+//    verb in this package that nothing can undo.
+//
+// ⛔ NOTHING HERE WRITES TO A STREAM, PICKS AN EXIT CODE OR ASKS ANYBODY ANYTHING. The confirmation
+//    is the caller's: a terminal types a sentence, a program passes one. This file is reached only
+//    after somebody decided, and it destroys what it is given.
+//
+// ⛔ THE SERVER GOES FIRST AND THE LIST LAST, which is the order the trash keeps and for the same
+//    reason: a row erased before its list entry leaves a file the person can see and never open.
+//    A release that FAILS stops the run before a single row is touched — nothing is erased behind
+//    one. A release the server REFUSES ("that storage was bought by the wallet, not by credits")
+//    is an answer rather than a failure: it is reported on that file and the erase goes on.
+//
+// ⛔ THE PROOF IS THE CALLER'S TO BUILD AND IS NOT DERIVED HERE. Both doors ask for the account
+//    code's own proof, and WHETHER this run may make one is a policy question with two different
+//    answers — the command line asks for an agreement first (`account-proof.ts`), a library caller
+//    has already made that decision by calling. So it arrives as a value. Nothing here reaches for
+//    `node:`: the SDK's browser entry bundles what this exports.
+//
+// ⚠ THE PIECES IT BORROWS COME FROM `drive-edit/` DIRECTLY, the way that folder's own files borrow
+//   from each other. This is a sibling of that family rather than an outside caller.
+import { request, ServerError } from "./api.js";
+import { DriveEditError, resolving } from "./drive-edit/errors.js";
+import { filesUnder, uniqueById } from "./drive-edit/tree.js";
+import { buildIndex, fullPathOf, KIND_FILE } from "./drive-paths.js";
+import { NmtsError } from "./errors.js";
+import { readFileList } from "./manifest.js";
+import { applyToList, batchTargets } from "./manifest-write.js";
+import { BINARY_NAME } from "./product.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";
+/**
+ * Work out what erasing these paths would destroy, without destroying anything.
+ *
+ * ⛔ ITS OWN STEP BECAUSE ONE CALLER HAS TO SHOW THE LIST BEFORE IT ASKS. `nmts erase` prints every
+ *    file it is about to destroy and then waits for a typed sentence; folding this into the act
+ *    would leave the terminal with nothing to print, and reading the list twice would leave the
+ *    two reads free to disagree about what is in it.
+ */
+export async function planErase(input, paths) {
+    const list = await readFileList(input.server, input.apiKey, input.code, input.accountId);
+    const entries = list.manifest?.entries ?? [];
+    const index = buildIndex(entries);
+    const targets = resolving(() => 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 DriveEditError("NOT_FOUND", `Nothing named holds a file; empty folders are removed with \`${BINARY_NAME} rm\`.`, {
+            exitCode: 4,
+        });
+    }
+    return {
+        files: files.map((f) => ({ id: f.id, path: fullPathOf(index, f) })),
+        going: going.map((e) => e.id),
+    };
+}
+/**
+ * Destroy what the plan names. ⛔ Irreversible, and nothing below asks whether the caller meant it.
+ */
+export async function eraseFiles(input, plan, options = {}) {
+    const releases = [];
+    if (options.releaseStorage === true) {
+        for (const f of plan.files) {
+            const path = f.path;
+            try {
+                const reply = await request(input.server, `/v1/items/${encodeURIComponent(f.id)}/release-storage`, {
+                    method: "POST",
+                    body: {},
+                    token: input.apiKey,
+                    accountProof: input.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 < plan.files.length; i += BATCH) {
+        const reply = await request(input.server, "/v1/items/erase", {
+            method: "POST",
+            body: { item_ids: plan.files.slice(i, i + BATCH).map((f) => f.id) },
+            token: input.apiKey,
+            accountProof: input.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(plan.going);
+    const result = await applyToList(input, (current) => {
+        const still = current.filter((e) => ids.has(e.id)).map((e) => e.id);
+        return still.length === 0 ? null : { op: "purge", ids: still };
+    });
+    return { erased, files: [...plan.files], releases, seq: result.seq };
+}
+/**
+ * Resolve these paths and destroy what they name, in one call.
+ *
+ * ⚠ FOR A CALLER THAT HAS ALREADY DECIDED. Anything that shows a person what is about to go should
+ *   use `planErase` first, so what it shows is what it then destroys.
+ */
+export async function erasePaths(input, paths, options = {}) {
+    return eraseFiles(input, await planErase(input, paths), options);
+}
+/** 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) : "?";
+}

package/dist/platform-sign.d.ts

@@ -25,14 +25,22 @@ export declare const DELEGATION_MAX_TTL_SECS = 2592000;
  * ⛔ THE FIRST THREE ARE AN API KEY'S OWN SCOPES, value for value. One vocabulary, so that a
  *    business asking for "read and write" asks for the number a person's key already means by it.
  *    `register` is the fourth and opens exactly one door: making the account the token names.
+ *
+ * ⛔ `files_erase` IS THE FIFTH, AND AN API KEY HAS NO BIT OF THAT NAME. It opens the two acts
+ *    nothing undoes: erasing a file's record and this account's key to it, and destroying the
+ *    treasury's storage under a file. Its own name rather than `files_write`, so a token minted so
+ *    an app can upload cannot destroy — and it does not stand alone: both doors also ask for the
+ *    account code's own proof on the same request, which is an act only whoever holds the code can
+ *    perform. The token is the business's permission; the proof is the key holder's.
  */
 export declare const SCOPE_BITS: {
     readonly files_read: 1;
     readonly files_write: 2;
     readonly storage_spend: 4;
     readonly register: 8;
+    readonly files_erase: 16;
 };
-/** One of the four names above. */
+/** One of the five names above. */
 export type ScopeName = keyof typeof SCOPE_BITS;
 /** Every bit a token may carry. */
 export declare const SCOPE_ALL: number;

package/dist/platform-sign.js

@@ -53,15 +53,23 @@ export const DELEGATION_MAX_TTL_SECS = 2_592_000;
  * ⛔ THE FIRST THREE ARE AN API KEY'S OWN SCOPES, value for value. One vocabulary, so that a
  *    business asking for "read and write" asks for the number a person's key already means by it.
  *    `register` is the fourth and opens exactly one door: making the account the token names.
+ *
+ * ⛔ `files_erase` IS THE FIFTH, AND AN API KEY HAS NO BIT OF THAT NAME. It opens the two acts
+ *    nothing undoes: erasing a file's record and this account's key to it, and destroying the
+ *    treasury's storage under a file. Its own name rather than `files_write`, so a token minted so
+ *    an app can upload cannot destroy — and it does not stand alone: both doors also ask for the
+ *    account code's own proof on the same request, which is an act only whoever holds the code can
+ *    perform. The token is the business's permission; the proof is the key holder's.
  */
 export const SCOPE_BITS = {
     files_read: 1,
     files_write: 2,
     storage_spend: 4,
     register: 8,
+    files_erase: 16,
 };
 /** Every bit a token may carry. */
-export const SCOPE_ALL = SCOPE_BITS.files_read | SCOPE_BITS.files_write | SCOPE_BITS.storage_spend | SCOPE_BITS.register;
+export const SCOPE_ALL = SCOPE_BITS.files_read | SCOPE_BITS.files_write | SCOPE_BITS.storage_spend | SCOPE_BITS.register | SCOPE_BITS.files_erase;
 /**
  * A new key pair, from the runtime's own random source.
  *

package/dist/product.d.ts

@@ -9,7 +9,7 @@ export declare const BINARY_NAME = "nmts";
  *    beside it. Here rather than in `main.ts` because the MCP server has to say it too, and a
  *    command importing the entry point is a cycle waiting to bite.
  */
-export declare const VERSION = "0.38.1";
+export declare const VERSION = "0.40.0";
 /** Where the product lives, for messages that need to send somebody somewhere real. */
 export declare const HOME_URL = "https://nmts.me";
 /** The source, so a person holding only the built program can find what it was built from. */

package/dist/product.js

@@ -18,7 +18,7 @@ export const BINARY_NAME = "nmts";
  *    beside it. Here rather than in `main.ts` because the MCP server has to say it too, and a
  *    command importing the entry point is a cycle waiting to bite.
  */
-export const VERSION = "0.38.1";
+export const VERSION = "0.40.0";
 /** Where the product lives, for messages that need to send somebody somewhere real. */
 export const HOME_URL = "https://nmts.me";
 /** The source, so a person holding only the built program can find what it was built from. */

package/dist/storage-control/extend.d.ts

@@ -0,0 +1,124 @@
+import { type Budget } from "../extend-budget.ts";
+import { type DaysLeft, type ExpiryStage } from "../expiry.ts";
+import { type ExtendPreview, type ExtendReads, type SignExtension } from "../extend-plan.ts";
+import type { StorageHints } from "./hints.ts";
+import { type AccountSettings } from "../shared/lib/drive/manifest-settings.ts";
+/** Where to talk, what opens the list, and whose list it is. */
+export interface ExtendInput {
+    server: string;
+    apiKey: string;
+    /** ⛔ The NMTS key. It opens the list and derives the wallet that pays; it goes nowhere else. */
+    code: string;
+    accountId: string;
+    network: string;
+}
+/**
+ * Everything one run worked out, in one shape.
+ *
+ * ⛔ ONE OBJECT SO TWO ANSWERS CANNOT DISAGREE. The words a person reads and the JSON a program
+ *    reads are built from this and from nothing else; when they were assembled separately the day
+ *    count in one of them was the count before the extension and in the other the count after.
+ */
+export interface ExtendFacts {
+    file: string;
+    itemId: string;
+    network: string;
+    epoch: number;
+    endEpoch: number;
+    epochs: number;
+    newEndEpoch: number;
+    daysLeft: DaysLeft;
+    daysLeftAfter: DaysLeft;
+    blobs: number;
+    /** ⚠ A STRING: base units run past what a JSON number keeps without losing digits. */
+    priceFrost: string;
+    priceWal: string;
+    /** ⛔ Said in the machine-readable answer too. A program spending WAL should not have to infer it. */
+    paidFrom: "wallet";
+    filesOnTheSameBlobs: number;
+    partsThatCannotBeExtended: number;
+    /** The address that would sign. */
+    wallet: string;
+    /** What it holds, as amounts — null when the chain could not say. ⛔ Never zero for unread. */
+    walletWal: string | null;
+    walletSui: string | null;
+    /** The chain fee a dry run measured — null when it could not be measured. */
+    feeMist: string | null;
+    feeSui: string | null;
+}
+/** What one extension would buy, and everything the decision to buy it rests on. */
+export interface ExtendPlan {
+    facts: ExtendFacts;
+    itemId: string;
+    /** The file's full path in the account, as the list spells it. */
+    path: string;
+    /** The blobs the transaction would name. */
+    objectIds: readonly string[];
+    epochs: number;
+    /**
+     * ⚠ THE WALLET'S NUMBER. `facts.wallet` is that wallet's address — the one the price was measured
+     *   against, and the one that signs.
+     */
+    wallet: number;
+    /**
+     * How close this file is to running out.
+     *
+     * ⛔ `later` IS NOT A REFUSAL HERE. Extending early loses nothing — the epochs are added to what
+     *    is left — so whether to spend now for time a file does not need yet is the caller's to
+     *    decide, and each surface names its own way of saying yes.
+     */
+    stage: ExpiryStage;
+    budget: Budget;
+    /** The sealed list's settings, as read for this price. */
+    settings: AccountSettings | undefined;
+}
+/** The chain reads. ⚠ A SEAM, NOT AN OPTION — no flag and no caller argument reaches it. */
+export interface ExtendPlanSeams {
+    readChain?: ((network: string) => Promise<ExtendReads> | ExtendReads) | undefined;
+    /** How many of the storage network's epochs to add. Default `DEFAULT_EXTEND_EPOCHS`. */
+    epochs?: string | number | undefined;
+    /** Which of this key's wallets pays. Absent = the account's own number, out of the list read here. */
+    wallet?: number | undefined;
+    /** The instant to measure against. Passed in so one run reports one moment. */
+    now: number;
+    /** What this caller wants said in a refusal instead of the neutral sentence. */
+    hints?: StorageHints | undefined;
+}
+/**
+ * Work out what extending this file would buy and what it would cost, without signing anything.
+ *
+ * ⛔ NO KEY IS DERIVED FOR SIGNING AND NO SIGNER IS LOADED. Everything here is a read, which is
+ *    what lets a price be asked for without an agreement being asked for first.
+ */
+export declare function planExtension(input: ExtendInput, target: string, seams: ExtendPlanSeams): Promise<ExtendPlan>;
+/** What one extension did. ⛔ By the time this exists, the storage IS extended and paid for. */
+export interface ExtendOutcome {
+    /** The transaction digest — what the server records as the replay guard. */
+    digest: string;
+    /** Whether the server wrote the new date down. */
+    recorded: boolean;
+    /** True when the server had already recorded this digest, so nothing was written twice. */
+    replay: boolean;
+    /**
+     * Why the date was not written down, in the words the failure gave. Null when it was.
+     *
+     * ⛔ IT IS NOT AN EXCEPTION, and that is the whole point: the money is already spent, so a caller
+     *    that saw a throw here would reasonably try again — and trying again pays again.
+     */
+    notRecorded: string | null;
+}
+/** The signature, and the one moment a caller may want between it and the server. ⚠ Seams. */
+export interface ExtendApplySeams {
+    sign?: SignExtension | undefined;
+    /** Told the instant the signature exists — before the server is asked to write the date down. */
+    onSigned?: ((digest: string) => void) | undefined;
+}
+/**
+ * Buy it. ⛔ THIS SIGNS, and nothing below this line can be undone by anybody, NMTS included.
+ *
+ * Nothing here asks whether the caller meant it: the price, both balances and any shortfall are in
+ * the plan, and calling this is the answer.
+ */
+export declare function applyExtension(input: ExtendInput, plan: ExtendPlan, seams?: ExtendApplySeams): Promise<ExtendOutcome>;
+/** Why a file has nothing to extend, said as the two different things it can be. */
+export declare function nothingToExtend(preview: ExtendPreview): string;

package/dist/storage-control/extend.js

@@ -0,0 +1,189 @@
+// Buying more storage time for one file that is already stored — worked out, signed and handed
+// back rather than printed.
+//
+// ⛔ ONE IMPLEMENTATION, TWO CALLERS. `nmts extend` is a terminal over this: the sentences a person
+//    reads, the agreement this machine keeps, the exit code. The SDK is somebody else's program and
+//    needs the same act with none of those. What must not be written twice is the ORDER below,
+//    because every step of it is about money that does not come back.
+//
+// ⛔ IT PRICES BEFORE IT SPENDS, ALWAYS. `planExtension` reads, judges and quotes; it holds no key
+//    and signs nothing, so a caller that only wants a price never comes near `applyExtension`.
+//
+// ⛔ THE SERVER DOES NOT EXTEND ANYTHING. `POST /v1/items/{id}/extended` means "record an extension
+//    the device already signed": the storage is bought by the time it is called, so a failure there
+//    is a failure to WRITE THE DATE DOWN and comes back as itself. Reporting it as a failure to
+//    extend would invite a second run, and a second run pays again.
+//
+// ⛔ AND THE CHAIN IS THE AUTHORITY ON WHEN A LEASE ENDS, not the server's `expiry_epoch`. The
+//    server's answer is used for one thing: knowing WHICH blobs to ask the chain about.
+//
+// ⚠ Nothing here reaches for `node:`, and the chain and the signer are loaded only when no seam was
+//   supplied.
+import { request } from "../api.js";
+import { buildIndex, entryAt, fullPathOf, KIND_FILE, normalisePath } from "../drive-paths.js";
+import { NmtsError } from "../errors.js";
+import { budgetFacts, readBudget } from "../extend-budget.js";
+import { 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 { activeWalletOf } from "../shared/lib/drive/manifest-settings.js";
+import { coinAmount, walletAddress } from "../wallet.js";
+/**
+ * Work out what extending this file would buy and what it would cost, without signing anything.
+ *
+ * ⛔ NO KEY IS DERIVED FOR SIGNING AND NO SIGNER IS LOADED. Everything here is a read, which is
+ *    what lets a price be asked for without an agreement being asked for first.
+ */
+export async function planExtension(input, target, seams) {
+    const list = await readFileList(input.server, input.apiKey, input.code, input.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;
+    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; anything that spends money reads the chain's own answer below.
+    const preview = asExtendPreview(await request(input.server, `/v1/items/${encodeURIComponent(entry.id)}/extend-preview`, {
+        token: input.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 (seams.readChain ?? defaultReads)(input.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 ${input.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 will not spend against a ` +
+                `guess. Try again, or name a different Sui node in NMTS_SUI_RPC.`,
+        });
+    }
+    const clock = window.clock;
+    const objectIds = preview.targets.map((t) => t.objectId);
+    const leases = await reads.readLeases(objectIds);
+    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, seams.now);
+    if (stage === "lapsed") {
+        throw new NmtsError(`The storage term for "${path}" has already ended.`, {
+            exitCode: 4,
+            nextStep: seams.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. ` +
+                    `Fetching the file is what says whether they can still be read.`,
+        });
+    }
+    const epochs = chooseEpochs(seams.epochs, headroom(leases, clock.current, window.maxAhead));
+    const newEndEpoch = endEpoch + epochs;
+    const before = daysLeftUntilEpoch(clock, endEpoch, seams.now);
+    const after = daysLeftUntilEpoch(clock, newEndEpoch, seams.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 anything is agreed to.
+    const frost = await reads.quote(leases, epochs);
+    const cohort = Math.max(0, ...preview.targets.map((t) => t.sharedItems));
+    const unreachable = preview.treasuryParts + preview.untrackedParts;
+    // ⛔ 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.
+    const wallet = seams.wallet ?? activeWalletOf(settings);
+    const address = await walletAddress(input.code, wallet);
+    const budget = await readBudget(reads, { address, objectIds, epochs, priceFrost: frost });
+    return {
+        facts: {
+            file: path,
+            itemId: entry.id,
+            network: input.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),
+        },
+        itemId: entry.id,
+        path,
+        objectIds,
+        epochs,
+        wallet,
+        stage,
+        budget,
+        settings,
+    };
+}
+/**
+ * Buy it. ⛔ THIS SIGNS, and nothing below this line can be undone by anybody, NMTS included.
+ *
+ * Nothing here asks whether the caller meant it: the price, both balances and any shortfall are in
+ * the plan, and calling this is the answer.
+ */
+export async function applyExtension(input, plan, seams = {}) {
+    const sign = seams.sign ?? (await import("../wallet-sign.js")).signExtension;
+    const digest = await sign({
+        network: input.network,
+        code: input.code,
+        wallet: plan.wallet,
+        objectIds: plan.objectIds,
+        epochs: plan.epochs,
+    });
+    seams.onSigned?.(digest);
+    // 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.
+    try {
+        const recorded = await request(input.server, `/v1/items/${encodeURIComponent(plan.itemId)}/extended`, { method: "POST", token: input.apiKey, body: { epochs: plan.epochs, tx_digest: digest } });
+        return { digest, recorded: true, replay: isRecord(recorded) && recorded["replay"] === true, notRecorded: null };
+    }
+    catch (error) {
+        return {
+            digest,
+            recorded: false,
+            replay: false,
+            notRecorded: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/** Why a file has nothing to extend, said as the two different things it can be. */
+export 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/storage-control/hints.d.ts

@@ -0,0 +1,20 @@
+import type { NmtsError } from "../errors.ts";
+export interface StorageHints {
+    /**
+     * The `nextStep` for a chain that did not answer. The chain's own cause is added after it, so
+     * this is the part before `Cause: …` and nothing else.
+     */
+    cannotRead?: string | undefined;
+    /** The `nextStep` for a resource this wallet does not hold free. */
+    notHeld?: string | undefined;
+    /**
+     * The whole refusal for a cut that would keep nothing or everything.
+     *
+     * ⚠ A FUNCTION BECAUSE THE NUMBER IS THE CHAIN'S: `limit` is the resource's own size, already in
+     *   the units a person reads, or its own number of epochs. What the refusal calls the thing that
+     *   was too big — a flag, a field — is the caller's to say.
+     */
+    cut?: ((what: "size" | "period", limit: string) => NmtsError) | undefined;
+    /** The `nextStep` for a storage term that has already ended. */
+    lapsed?: string | undefined;
+}

package/dist/storage-control/hints.js

@@ -0,0 +1,11 @@
+// The words a caller puts in a refusal, where the neutral sentence is not the one to say.
+//
+// ⛔ A TERMINAL NAMES ITS OWN COMMANDS AND A LIBRARY NAMES NONE. "`nmts env` says which network was
+//    asked" is the right next step for somebody at a prompt and the wrong one inside somebody
+//    else's server, where that program may not exist. So the JUDGEMENT is written once, here, and
+//    the sentence that follows it belongs to whoever asked — the same division this whole folder
+//    keeps between what is decided and what is printed.
+//
+// ⚠ EVERY FIELD IS OPTIONAL, and what is left out is answered with a sentence that names nothing
+//   outside the caller's own program. The SDK passes none of them.
+export {};

package/dist/storage-control/list.d.ts

@@ -0,0 +1,55 @@
+import type { Network } from "../network.ts";
+import type { StorageResource } from "../shared/lib/storage-control/chain.ts";
+import type { StorageHints } from "./hints.ts";
+/** What the chain said: the resources, and which epoch it is (null when the clock could not be read). */
+export interface StorageRead {
+    items: readonly StorageResource[];
+    currentEpoch: number | null;
+}
+/** Where a resource stands against the current epoch. */
+export type StorageStatus = "lapsed" | "notYet" | "usable";
+/** One resource, with where it stands. */
+export interface StorageItem extends StorageResource {
+    /**
+     * ⛔ NULL IS "THE EPOCH COULD NOT BE READ", never "lapsed". Which epoch the network is in is a
+     *    fact only the chain has, and guessing it would mark a resource somebody paid for as over.
+     */
+    status: StorageStatus | null;
+}
+/** One wallet's storage, as anything asking about it needs it. */
+export interface StorageListing {
+    address: string;
+    network: Network;
+    currentEpoch: number | null;
+    /** Usable first, then largest, then furthest ahead — left as read when there is no epoch. */
+    items: readonly StorageItem[];
+    /** The usable sizes added up — null when the epoch could not be read. */
+    usableBytes: number | null;
+}
+/**
+ * How the resources are read.
+ *
+ * ⚠ A SEAM, NOT AN OPTION — no flag and no caller argument reaches it. A test that talked to a live
+ *   storage network could not run offline and could never be asked to hold a lapsed resource.
+ */
+export type ReadWalletStorage = (network: Network, address: string) => Promise<StorageRead>;
+/** Every free storage resource one address holds, in the order a person reads them. */
+export declare function listStorage(input: {
+    network: Network;
+    address: string;
+}, read?: ReadWalletStorage, hints?: StorageHints): Promise<StorageListing>;
+/**
+ * The one refusal for a chain that did not answer.
+ *
+ * ⛔ IT IS NOT AN EMPTY LIST. Holding no resource is normal; failing to read is a reason to look
+ *    again, and the chain's own words are carried so that whoever reads it knows which it was.
+ */
+export declare function readOrRefuse(read: () => Promise<StorageRead>, hints?: StorageHints): Promise<StorageRead>;
+/**
+ * Bytes as a person reads them: binary units, two decimals, whole bytes below a KiB.
+ *
+ * ⚠ HERE RATHER THAN BESIDE THE SCREEN THAT PRINTS THEM, because the refusals in `reshape.ts` name
+ *   a resource's size too, and a refusal that said `4294967296` about a resource a listing calls
+ *   `4.00 GiB` would be two spellings of one number in front of the same person.
+ */
+export declare function formatBytes(bytes: number): string;