@needmoretruth/nmts-cli 0.39.0 → 0.40.0

package/dist/commands/wallet-storage-ops.js

@@ -1,13 +1,14 @@
 // `nmts wallet storage split|merge|transfer` — reshaping the storage resources the wallet holds,
-// and handing one over. ⛔ EACH SIGNS. The storage-control half a terminal can do: the browser's
-// rules (`shared/lib/storage-control/plan.ts`, copied byte-for-byte) say what the contract allows;
-// the dry run is the final judge; the review comes before the signature; `--yes` is the answer.
+// and handing one over. ⛔ EACH SIGNS. What the contract allows, what a change would leave behind,
+// the dry run that prices it and the signature are `storage-control.ts`, which the SDK calls as
+// well; this file is the terminal over it: the words typed, the review read, and `--yes`.
 //
-// ⛔ THE ORDER IS THE SAFETY, as in `wallet-send.ts`: ① the resources are READ from the chain and
-//    the named ones must be this wallet's ② the rules judge the request and say why not ③ the
-//    exact transaction is dry-run for its fee, and a refusal there is printed and ends the run
-//    ④ the review ⑤ without `--yes` that is the end ⑥ the wallet unlock is held against the fee —
-//    scope `storage` for cutting and joining, scope `all` for handing over ⑦ only then the signature.
+// ⛔ THE ORDER IS THE SAFETY, and it is kept over there: ① the resources are READ from the chain and
+//    the named ones must be this wallet's ② the rules judge the request and say why not ③ the exact
+//    transaction is dry-run for its fee, and a refusal there ends the run ④ the review ⑤ without
+//    `--yes` that is the end ⑥ the wallet unlock is held against the fee — scope `storage` for
+//    cutting and joining, scope `all` for handing over ⑦ only then the signature. Steps ⑤ and ⑥ are
+//    this file's, handed in as the gate.
 //
 // ⛔ HANDING OVER MOVES NO FILE. The owner's sentence for the browser holds here: what goes is size
 //    and remaining time; a file's bytes are sealed with keys the NMTS key derives and stay
@@ -18,20 +19,12 @@ import { NmtsError } from "../errors.js";
 import { resolveNetwork } from "../network.js";
 import { BINARY_NAME } from "../product.js";
 import { resolveServer } from "../server.js";
-import { canFuse, statusOf } from "../shared/lib/storage-control/plan.js";
+import { reshapeStorage, } from "../storage-control.js";
 import { explorerTxUrl } from "../shared/lib/wallet/activity.js";
-import { isValidSuiAddress } from "../shared/lib/wallet/send-rules.js";
-import { storageOpsReads } from "../storage-control-chain.js";
 import { coinAmount, walletAddress } from "../wallet.js";
 import { payingWalletIndex } from "../wallet-pay-index.js";
 import { recordWalletSpend, requireWalletGrant } from "../wallet-grant.js";
 import { formatBytes } from "./wallet-storage.js";
-const FUSE_WHY = {
-    same: "those are the same resource.",
-    differentSize: "their periods differ and so do their sizes — the contract joins sizes only over an identical period, and periods only at an identical size.",
-    differentPeriod: "their periods differ.",
-    notAdjacent: "their sizes are equal but their periods do not touch — one has to end where the other starts.",
-};
 export async function walletStorageOps(op, rest, options = {}) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
     const resolved = await requireAccountCode();
@@ -42,57 +35,43 @@ export async function walletStorageOps(op, rest, options = {}) {
     const stored = resolved.source === "file" || resolved.source === "file-locked" ? readCredentialsFile() : null;
     const server = resolveServer(options.server ?? stored?.server);
     const network = resolveNetwork(server, options.network ?? stored?.network);
-    const reads = (options.storageReads ?? storageOpsReads)(network);
-    // ① The resources, and which epoch it is.
-    let read;
-    try {
-        read = await reads.readStorage(address);
-    }
-    catch (error) {
-        throw new NmtsError("The storage resources could not be read from the chain.", {
-            exitCode: 1,
-            nextStep: `Nothing was signed. Cause: ${error instanceof Error ? error.message : String(error)}`,
-        });
-    }
-    const held = (id) => {
-        const found = read.items.find((r) => r.objectId === id);
-        if (found === undefined) {
-            throw new NmtsError(`This wallet holds no free storage resource ${id}.`, {
-                exitCode: 4,
-                nextStep: `\`${BINARY_NAME} wallet storage\` lists the ones it holds. A resource bound inside a file is not free.`,
-            });
-        }
-        return found;
+    // What was typed, as values. Everything past this is judged against the chain's own answer.
+    const { ask, command } = asked(op, rest, options);
+    // ⛔ WITHOUT `--yes` THE RUN STOPS AT THE REVIEW, exactly as `--dry-run` does — the two differ
+    //    only in what is said afterwards and in the exit code, which is this file's business.
+    const stopAtReview = options.dryRun === true || options.yes !== true;
+    const outcome = await reshapeStorage({ network, code: resolved.code, wallet, address }, ask, {
+        reads: options.storageReads,
+        sign: options.signStorage,
+        dryRun: stopAtReview,
+        // ⚠ THE SENTENCES A PERSON READS ARE THIS FILE'S. The library judges; what a refusal calls
+        //   the thing that was wrong — a flag, another command — belongs where somebody typed it.
+        hints: {
+            cannotRead: "Nothing was signed.",
+            notHeld: `\`${BINARY_NAME} wallet storage\` lists the ones it holds. A resource bound inside a file is not free.`,
+            cut: (what, limit) => new NmtsError(what === "size"
+                ? `--size must be above 0 and below the resource's ${limit}.`
+                : `--epochs must be a whole number above 0 and below the resource's ${limit} epochs.`, { exitCode: 2 }),
+        },
+        onReview: (review) => {
+            if (!options.json)
+                describe(say, review, wallet);
+        },
+        // ⑥ The unlock, held against the fee this review measured. ⛔ Throwing here signs nothing.
+        agree: (review) => {
+            requireWalletGrant(review.plan.action, spendOf(review), new Date(options.now ?? Date.now()));
+        },
+    });
+    const { review } = outcome;
+    const facts = {
+        op,
+        network,
+        address,
+        shape: review.plan.shape,
+        feeSui: review.feeMist === null ? null : coinAmount(review.feeMist),
+        currentEpoch: review.currentEpoch,
     };
-    // ② The request, judged.
-    const { shape, action, lines, command } = plan(op, rest, options, held);
-    const walrusPackageId = await reads.walrusPackageId();
-    // ③ The dry run: the fee, or the contract's own refusal.
-    const verdict = await reads.dryRun(shape, address);
-    if (verdict.refusal !== null) {
-        throw new NmtsError(`The chain would refuse this: ${verdict.refusal}`, {
-            exitCode: 4,
-            nextStep: "Nothing was signed and no fee was spent.",
-        });
-    }
-    const feeMist = verdict.feeMist;
-    const facts = { op, network, address, shape, feeSui: feeMist === null ? null : coinAmount(feeMist), currentEpoch: read.currentEpoch };
-    // ④ The review.
-    if (!options.json) {
-        say(`Would ${lines.what}`);
-        say(`  from  ${address} (wallet ${wallet})`);
-        for (const l of lines.detail)
-            say(`  ${l}`);
-        say(feeMist === null
-            ? `  Chain fee (SUI): could not be measured just now; it is charged with the signature.`
-            : `  Chain fee about ${facts.feeSui} SUI, measured by a dry run just now.`);
-        if (op === "transfer") {
-            say(`  ⛔ No file goes with it. What goes is size and remaining time; the files stay sealed with this`);
-            say(`     account's keys. It cannot be undone, and NMTS cannot recall it. Check the address once more.`);
-        }
-    }
-    // ⑤ Without --yes, that is the end.
-    if (options.dryRun === true || options.yes !== true) {
+    if (outcome.kind === "review") {
         if (options.json) {
             say(JSON.stringify({ ...facts, signed: false, dryRun: options.dryRun === true }));
             return options.dryRun === true ? 0 : 4;
@@ -107,61 +86,86 @@ export async function walletStorageOps(op, rest, options = {}) {
             nextStep: `Read the review above, then: \`${command} --yes\``,
         });
     }
-    // ⑥ The unlock, held against the fee. ⑦ The signature.
-    const spend = { walFrost: 0n, suiMist: feeMist ?? 0n };
-    requireWalletGrant(action, spend, new Date(options.now ?? Date.now()));
-    const sign = options.signStorage ?? (await import("../wallet-sign.js")).signStorageOp;
-    const digest = await sign({ network, code: resolved.code, wallet, shape, walrusPackageId });
-    recordWalletSpend(spend);
+    // What left the wallet is added to this machine's ledger as the dry run measured it.
+    recordWalletSpend(spendOf(review));
     if (options.json) {
-        say(JSON.stringify({ ...facts, signed: true, digest, explorerUrl: explorerTxUrl(digest, network) }));
+        say(JSON.stringify({ ...facts, signed: true, digest: outcome.digest, explorerUrl: explorerTxUrl(outcome.digest, network) }));
         return 0;
     }
     say(``);
-    say(`  Done. Transaction ${digest}`);
-    say(`  ${explorerTxUrl(digest, network)}`);
+    say(`  Done. Transaction ${outcome.digest}`);
+    say(`  ${explorerTxUrl(outcome.digest, network)}`);
     say(`  \`${BINARY_NAME} wallet storage\` lists what the wallet holds now.`);
     return 0;
 }
-/** The shape one request is, the unlock action it needs, and the review's words. */
-function plan(op, rest, options, held) {
+/** What one change costs this wallet: no WAL, and the fee the dry run measured. */
+function spendOf(review) {
+    return { walFrost: 0n, suiMist: review.feeMist ?? 0n };
+}
+/** The review a person reads, in the order somebody deciding needs it. */
+function describe(say, review, wallet) {
+    const { plan } = review;
+    say(`Would ${what(plan)}`);
+    say(`  from  ${review.address} (wallet ${wallet})`);
+    for (const line of detail(plan))
+        say(`  ${line}`);
+    say(review.feeMist === null
+        ? `  Chain fee (SUI): could not be measured just now; it is charged with the signature.`
+        : `  Chain fee about ${coinAmount(review.feeMist)} SUI, measured by a dry run just now.`);
+    if (plan.op === "transfer") {
+        say(`  ⛔ No file goes with it. What goes is size and remaining time; the files stay sealed with this`);
+        say(`     account's keys. It cannot be undone, and NMTS cannot recall it. Check the address once more.`);
+    }
+}
+/** The one-line "what this would do", from the resources as the chain has them. */
+function what(plan) {
+    const named = (at) => {
+        const r = plan.named[at];
+        return r === undefined ? "" : `${formatBytes(r.sizeBytes)} · epoch ${r.startEpoch} to ${r.endEpoch} (${r.objectId})`;
+    };
+    const result = plan.result;
+    if (result.kind === "split")
+        return `cut ${named(0)} by ${plan.shape.kind === "splitSize" ? "size" : "period"}.`;
+    if (result.kind === "merge")
+        return `join ${named(1)} into ${named(0)}.`;
+    return `hand ${named(0)} to ${result.to}.`;
+}
+/** What it would leave behind, said from the numbers the plan worked out. */
+function detail(plan) {
+    const result = plan.result;
+    if (result.kind === "split") {
+        const { keeps, creates } = result;
+        return plan.shape.kind === "splitSize"
+            ? [`It keeps ${formatBytes(keeps.sizeBytes)}; a new resource of ${formatBytes(creates.sizeBytes)} over the same period appears in this wallet.`]
+            : [`It keeps epoch ${keeps.startEpoch} to ${keeps.endEpoch}; a new resource of the same size over epoch ${creates.startEpoch} to ${creates.endEpoch} appears in this wallet.`];
+    }
+    if (result.kind === "merge") {
+        const b = result.becomes;
+        return [
+            result.how === "amount"
+                ? `Same period, so the sizes add: the first becomes ${formatBytes(b.sizeBytes)} and the second is gone.`
+                : `Same size and touching periods, so the periods join: the first spans epoch ${b.startEpoch} to ${b.endEpoch} and the second is gone.`,
+        ];
+    }
+    return [`Afterwards this wallet no longer holds it.`];
+}
+/** What was typed, as the values the library judges — and the line to run to go through with it. */
+function asked(op, rest, options) {
     const [a, b] = rest;
-    const resource = (r) => `${formatBytes(r.sizeBytes)} · epoch ${r.startEpoch} to ${r.endEpoch} (${r.objectId})`;
     if (op === "split") {
         if (a === undefined)
             throw usage("split <resource id> --size <bytes> | --epochs <n>");
-        const r = held(a);
         if (options.size !== undefined && options.epochs !== undefined)
             throw usage("split takes --size OR --epochs, not both");
         if (options.size !== undefined) {
-            const keep = parseBytes(options.size);
-            if (keep <= 0 || keep >= r.sizeBytes) {
-                throw new NmtsError(`--size must be above 0 and below the resource's ${formatBytes(r.sizeBytes)}.`, { exitCode: 2 });
-            }
             return {
-                shape: { kind: "splitSize", objectId: a, keepBytes: keep },
-                action: "reshape",
-                lines: {
-                    what: `cut ${resource(r)} by size.`,
-                    detail: [`It keeps ${formatBytes(keep)}; a new resource of ${formatBytes(r.sizeBytes - keep)} over the same period appears in this wallet.`],
-                },
+                ask: { kind: "splitSize", objectId: a, keepBytes: parseBytes(options.size) },
                 command: `${BINARY_NAME} wallet storage split ${a} --size ${options.size}`,
             };
         }
         if (options.epochs !== undefined) {
-            const n = Number(options.epochs);
-            const span = r.endEpoch - r.startEpoch;
-            if (!Number.isSafeInteger(n) || n <= 0 || n >= span) {
-                throw new NmtsError(`--epochs must be a whole number above 0 and below the resource's ${span} epochs.`, { exitCode: 2 });
-            }
-            const at = r.startEpoch + n;
             return {
-                shape: { kind: "splitEpoch", objectId: a, splitEpoch: at },
-                action: "reshape",
-                lines: {
-                    what: `cut ${resource(r)} by period.`,
-                    detail: [`It keeps epoch ${r.startEpoch} to ${at}; a new resource of the same size over epoch ${at} to ${r.endEpoch} appears in this wallet.`],
-                },
+                ask: { kind: "splitEpochs", objectId: a, keepEpochs: Number(options.epochs) },
                 command: `${BINARY_NAME} wallet storage split ${a} --epochs ${options.epochs}`,
             };
         }
@@ -170,41 +174,11 @@ function plan(op, rest, options, held) {
     if (op === "merge") {
         if (a === undefined || b === undefined)
             throw usage("merge <resource id> <resource id>");
-        const first = held(a);
-        const second = held(b);
-        const verdict = canFuse(first, second);
-        if (!verdict.can) {
-            throw new NmtsError(`These two cannot be joined: ${FUSE_WHY[verdict.why]}`, {
-                exitCode: 4,
-                nextStep: `Nothing was signed. \`${BINARY_NAME} wallet storage\` shows each one's size and period.`,
-            });
-        }
-        return {
-            shape: { kind: "fuse", first: a, second: b, how: verdict.kind },
-            action: "reshape",
-            lines: {
-                what: `join ${resource(second)} into ${resource(first)}.`,
-                detail: [
-                    verdict.kind === "amount"
-                        ? `Same period, so the sizes add: the first becomes ${formatBytes(first.sizeBytes + second.sizeBytes)} and the second is gone.`
-                        : `Same size and touching periods, so the periods join: the first spans epoch ${Math.min(first.startEpoch, second.startEpoch)} to ${Math.max(first.endEpoch, second.endEpoch)} and the second is gone.`,
-                ],
-            },
-            command: `${BINARY_NAME} wallet storage merge ${a} ${b}`,
-        };
+        return { ask: { kind: "merge", first: a, second: b }, command: `${BINARY_NAME} wallet storage merge ${a} ${b}` };
     }
     if (a === undefined || b === undefined)
         throw usage("transfer <resource id> <address>");
-    const r = held(a);
-    if (!isValidSuiAddress(b)) {
-        throw new NmtsError("That is not a Sui address: it is 0x followed by 64 hexadecimal characters.", { exitCode: 2 });
-    }
-    return {
-        shape: { kind: "transfer", objectId: a, to: b },
-        action: "give",
-        lines: { what: `hand ${resource(r)} to ${b}.`, detail: [`Afterwards this wallet no longer holds it.`] },
-        command: `${BINARY_NAME} wallet storage transfer ${a} ${b}`,
-    };
+    return { ask: { kind: "transfer", objectId: a, to: b }, command: `${BINARY_NAME} wallet storage transfer ${a} ${b}` };
 }
 function usage(form) {
     return new NmtsError(`\`${BINARY_NAME} wallet storage ${form}\``, { exitCode: 2 });

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

@@ -1,10 +1,7 @@
 import { type Network } from "../network.ts";
-import type { StorageResource } from "../shared/lib/storage-control/chain.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;
-}
+import { type StorageRead } from "../storage-control.ts";
+export type { StorageRead } from "../storage-control.ts";
+export { formatBytes } from "../storage-control.ts";
 export interface WalletStorageOptions {
     server?: string | undefined;
     network?: string | undefined;
@@ -14,5 +11,3 @@ export interface WalletStorageOptions {
     readStorage?: (network: Network, address: string) => Promise<StorageRead>;
 }
 export declare function walletStorage(options?: WalletStorageOptions): Promise<number>;
-/** Bytes for a person: binary units, two decimals, whole bytes below a KiB. */
-export declare function formatBytes(bytes: number): string;

package/dist/commands/wallet-storage.js

@@ -6,16 +6,16 @@
 //    fusing and spending a resource need a signature and are not here.
 //
 // ⛔ "NONE" AND "COULD NOT READ" ARE DIFFERENT SENTENCES — holding no resource is normal; failing to
-//    read is a reason to look again. The reader (`shared/lib/storage-control/chain.ts`, the
-//    browser's own, copied byte-for-byte) throws rather than answering an empty list.
+//    read is a reason to look again. The reading, the ordering and that refusal are
+//    `storage-control.ts`, which the SDK calls as well; this file is the terminal over it.
 import { requireAccountCode } from "../code-access.js";
 import { readCredentialsFile } from "../credentials.js";
-import { NmtsError } from "../errors.js";
 import { resolveNetwork } from "../network.js";
 import { BINARY_NAME } from "../product.js";
+import { formatBytes, listStorage, } from "../storage-control.js";
 import { resolveServer } from "../server.js";
-import { statusOf, totalUsableBytes, usableFirst } from "../shared/lib/storage-control/plan.js";
 import { walletAddress } from "../wallet.js";
+export { formatBytes } from "../storage-control.js";
 export async function walletStorage(options = {}) {
     const say = options.write ?? ((line) => process.stdout.write(`${line}\n`));
     const resolved = await requireAccountCode();
@@ -23,33 +23,25 @@ export async function walletStorage(options = {}) {
     const stored = resolved.source === "file" || resolved.source === "file-locked" ? readCredentialsFile() : null;
     const server = resolveServer(options.server ?? stored?.server);
     const network = resolveNetwork(server, options.network ?? stored?.network);
-    const read = options.readStorage ??
-        (async (net, addr) => (await import("../wallet-storage-chain.js")).readWalletStorage(net, addr));
-    let got;
-    try {
-        got = await read(network, address);
-    }
-    catch (error) {
-        throw new NmtsError("The storage resources could not be read from the chain.", {
-            exitCode: 1,
-            nextStep: `That is not the same as holding none. \`${BINARY_NAME} env\` says which network was asked. ` +
-                `Cause: ${error instanceof Error ? error.message : String(error)}`,
-        });
-    }
-    const epoch = got.currentEpoch;
-    const items = epoch === null ? [...got.items] : usableFirst(got.items, epoch);
+    // ⚠ THE SENTENCE A PERSON READS IS THIS FILE'S, not the library's: `nmts env` is a command at a
+    //   prompt and means nothing inside somebody else's program.
+    const listed = await listStorage({ network, address }, options.readStorage, {
+        cannotRead: `That is not the same as holding none. \`${BINARY_NAME} env\` says which network was asked.`,
+    });
+    const epoch = listed.currentEpoch;
+    const items = listed.items;
     if (options.json) {
         say(JSON.stringify({
             address,
             network,
             currentEpoch: epoch,
-            usableBytes: epoch === null ? null : totalUsableBytes(items, epoch),
+            usableBytes: listed.usableBytes,
             resources: items.map((r) => ({
                 objectId: r.objectId,
                 sizeBytes: r.sizeBytes,
                 startEpoch: r.startEpoch,
                 endEpoch: r.endEpoch,
-                status: epoch === null ? null : statusOf(r, epoch),
+                status: r.status,
             })),
         }));
         return 0;
@@ -61,10 +53,10 @@ export async function walletStorage(options = {}) {
         say(`  This wallet holds no free storage resource. Anything bound inside a file is not listed here.`);
     }
     else {
-        if (epoch !== null)
-            say(`  ${formatBytes(totalUsableBytes(items, epoch))} usable now, in ${items.length} resource${items.length === 1 ? "" : "s"}.`);
+        if (listed.usableBytes !== null)
+            say(`  ${formatBytes(listed.usableBytes)} usable now, in ${items.length} resource${items.length === 1 ? "" : "s"}.`);
         for (const r of items) {
-            const status = epoch === null ? "" : `  ${statusWord(statusOf(r, epoch))}`;
+            const status = r.status === null ? "" : `  ${statusWord(r.status)}`;
             say(`  ${formatBytes(r.sizeBytes).padStart(11)} · epoch ${r.startEpoch} to ${r.endEpoch}${status}`);
             say(`    ${r.objectId}`);
         }
@@ -80,16 +72,3 @@ export async function walletStorage(options = {}) {
 function statusWord(status) {
     return status === "usable" ? "usable now" : status === "notYet" ? "not started" : "ended";
 }
-/** Bytes for a person: binary units, two decimals, whole bytes below a KiB. */
-export function formatBytes(bytes) {
-    const units = ["KiB", "MiB", "GiB", "TiB"];
-    let value = bytes;
-    let unit = "B";
-    for (const next of units) {
-        if (value < 1024)
-            break;
-        value /= 1024;
-        unit = next;
-    }
-    return unit === "B" ? `${bytes} B` : `${value.toFixed(2)} ${unit}`;
-}

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.39.0";
+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.39.0";
+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;