@needmoretruth/nmts-cli 0.39.0 → 0.40.0

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;

package/dist/storage-control/list.js

@@ -0,0 +1,71 @@
+// What a wallet holds in storage — the free resources, ordered and judged, without a screen.
+//
+// ⛔ EVERYTHING HERE IS A READ. What the storage network sells is size and time, not a file;
+//    deleting a file from the network returns the remaining time to the wallet that bought it, and
+//    that is what this lists. Splitting, joining and handing one over are next door in
+//    `reshape.ts`, because each of them signs.
+//
+// ⛔ "NONE" AND "COULD NOT READ" ARE DIFFERENT ANSWERS, and this file is where that is kept: the
+//    reader throws rather than answering an empty list, and `readOrRefuse` turns that into one
+//    refusal with the chain's own cause in it. Flattening the two would draw a wallet full of
+//    storage as a wallet with none, on the screen somebody decides what to buy from.
+//
+// ⛔ AND THE JUDGEMENT IS THE BROWSER'S, not a second copy of it: `shared/lib/storage-control/plan.ts`
+//    is copied byte for byte from the browser and says what "usable" means and in what order these
+//    are shown. Nothing here reaches for `node:`.
+import { NmtsError } from "../errors.js";
+import { statusOf, totalUsableBytes, usableFirst } from "../shared/lib/storage-control/plan.js";
+/** Every free storage resource one address holds, in the order a person reads them. */
+export async function listStorage(input, read = defaultRead, hints = {}) {
+    const got = await readOrRefuse(() => read(input.network, input.address), hints);
+    const epoch = got.currentEpoch;
+    const ordered = epoch === null ? [...got.items] : usableFirst(got.items, epoch);
+    return {
+        address: input.address,
+        network: input.network,
+        currentEpoch: epoch,
+        items: ordered.map((r) => ({ ...r, status: epoch === null ? null : statusOf(r, epoch) })),
+        usableBytes: epoch === null ? null : totalUsableBytes(ordered, epoch),
+    };
+}
+/**
+ * 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 async function readOrRefuse(read, hints = {}) {
+    try {
+        return await read();
+    }
+    catch (error) {
+        const said = hints.cannotRead ?? "That is not the same as holding none, and nothing was signed.";
+        throw new NmtsError("The storage resources could not be read from the chain.", {
+            exitCode: 1,
+            nextStep: `${said} Cause: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
+/** The real read. Imported only when no seam was supplied — it loads the storage network's client. */
+async function defaultRead(network, address) {
+    return (await import("../wallet-storage-chain.js")).readWalletStorage(network, address);
+}
+/**
+ * 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 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/storage-control/reshape.d.ts

@@ -0,0 +1,120 @@
+import type { Network } from "../network.ts";
+import type { StorageResource } from "../shared/lib/storage-control/chain.ts";
+import type { StorageOpShape, StorageOpsReads } from "../storage-control-chain.ts";
+import type { WalletAction } from "../wallet-grant.ts";
+import type { SignStorageOp } from "../wallet-sign-seams.ts";
+import type { StorageHints } from "./hints.ts";
+/** The three things that can be done to a resource the wallet holds free. */
+export type StorageOp = "split" | "merge" | "transfer";
+/**
+ * One request, in the values it is made of rather than in what anybody typed.
+ *
+ * ⚠ `keepEpochs` IS A COUNT AND THE CHAIN TAKES AN EPOCH. The resource keeps its first
+ *   `keepEpochs` epochs; which absolute epoch that is depends on where it starts, which is a fact
+ *   read from the chain below rather than one a caller should have to work out.
+ */
+export type StorageOpAsk = {
+    kind: "splitSize";
+    objectId: string;
+    keepBytes: number;
+} | {
+    kind: "splitEpochs";
+    objectId: string;
+    keepEpochs: number;
+} | {
+    kind: "merge";
+    first: string;
+    second: string;
+} | {
+    kind: "transfer";
+    objectId: string;
+    to: string;
+};
+/** A resource as the chain would hold it. A resource that does not exist yet has no id. */
+export interface StorageShape {
+    sizeBytes: number;
+    startEpoch: number;
+    endEpoch: number;
+}
+/** What one change leaves behind — the numbers, without a word of prose about them. */
+export type StorageOpResult = {
+    kind: "split";
+    keeps: StorageShape;
+    creates: StorageShape;
+} | {
+    kind: "merge";
+    becomes: StorageShape;
+    consumed: string;
+    how: "amount" | "periods";
+} | {
+    kind: "transfer";
+    moves: StorageShape;
+    to: string;
+};
+/** One request, judged: what the chain is asked for, what it needs, and what it would leave. */
+export interface StorageOpPlan {
+    op: StorageOp;
+    /** The transaction shape — what is priced, and what is signed. One builder for both. */
+    shape: StorageOpShape;
+    /** The wallet unlock this needs: `reshape` for cutting and joining, `give` for handing over. */
+    action: WalletAction;
+    /** The resources it is about, as the chain has them. */
+    named: readonly StorageResource[];
+    result: StorageOpResult;
+}
+/**
+ * Judge one request against the resources this wallet actually holds.
+ *
+ * ⛔ EVERY REFUSAL HAPPENS HERE, BEFORE THE CHAIN IS ASKED ANYTHING. Letting the contract refuse it
+ *    instead leaves somebody having paid gas with no idea why — the rule the browser's own
+ *    judgement (`shared/lib/storage-control/plan.ts`) was written for.
+ */
+export declare function planStorageOp(held: readonly StorageResource[], ask: StorageOpAsk, hints?: StorageHints): StorageOpPlan;
+/** What one change would do, priced, before anything is signed. */
+export interface StorageOpReview {
+    plan: StorageOpPlan;
+    /** The wallet whose resources these are — the one that would sign. */
+    address: string;
+    network: Network;
+    currentEpoch: number | null;
+    /**
+     * The chain fee the dry run measured, in MIST — or null when it could not be measured.
+     * ⛔ NEVER ZERO FOR "UNKNOWN": the fee is charged with the signature either way.
+     */
+    feeMist: bigint | null;
+}
+/** Stopped at the review, or done and signed. */
+export type ReshapeOutcome = {
+    kind: "review";
+    review: StorageOpReview;
+} | {
+    kind: "done";
+    review: StorageOpReview;
+    digest: string;
+};
+/** Whose resources these are: the wallet that holds them, and the key that derives it. */
+export interface ReshapeContext {
+    network: Network;
+    /** ⛔ The NMTS key. It never leaves this process: it derives the wallet and nothing else. */
+    code: string;
+    /** Which of this key's wallets holds the resources. */
+    wallet: number;
+    /** That wallet's address — read, priced and signed with as one. */
+    address: string;
+}
+/** The chain, the signature, and the two places a caller gets a word in. ⚠ Seams, not options. */
+export interface ReshapeSeams {
+    reads?: ((network: Network) => StorageOpsReads) | undefined;
+    /** ⛔ SEPARATE FROM THE READS so a test can prove the review stops before this. */
+    sign?: SignStorageOp | undefined;
+    /** Told once the change is priced, and before anything is signed. */
+    onReview?: ((review: StorageOpReview) => void) | undefined;
+    /** ⛔ THE GATE. Throwing here stops the run with nothing signed. */
+    agree?: ((review: StorageOpReview) => void) | undefined;
+    /** Stop at the review. Nothing is signed and no signer is even loaded. */
+    dryRun?: boolean | undefined;
+    /** What this caller wants said in a refusal instead of the neutral sentence. */
+    hints?: StorageHints | undefined;
+}
+/** Read, judge, price and — unless somebody stops it — sign one change to a storage resource. */
+export declare function reshapeStorage(context: ReshapeContext, ask: StorageOpAsk, seams?: ReshapeSeams): Promise<ReshapeOutcome>;

package/dist/storage-control/reshape.js

@@ -0,0 +1,188 @@
+// Cutting a storage resource, joining two of them, and handing one over — decided, priced, signed
+// and handed back rather than printed.
+//
+// ⛔ ONE IMPLEMENTATION, TWO CALLERS, which is the whole reason this file exists. `nmts wallet
+//    storage split|merge|transfer` is a terminal's shape: it prints a review, asks for `--yes` and
+//    answers an exit code. The SDK is somebody else's program and needs the same acts with none of
+//    those. A second implementation of "what may be joined with what" would be a second place for
+//    the contract's rules to be got right, and the copy nobody re-reads is the one that quietly
+//    disagrees — about transactions that spend a fee and cannot be undone.
+//
+// ⛔ THE ORDER IS THE SAFETY, and it is here rather than in either caller: ① the resources are READ
+//    from the chain and the named ones must be this wallet's ② the browser's 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 is handed out ⑤ `dryRun` stops here ⑥ `agree` is the gate — whatever it throws
+//    stops the run with nothing signed ⑦ only then the signature.
+//
+// ⛔ HANDING ONE OVER MOVES NO FILE. What goes is size and remaining time; a file's bytes are sealed
+//    with keys the NMTS key derives and stay unreadable to whoever receives the resource. It cannot
+//    be undone and NMTS cannot recall it.
+//
+// ⚠ NOTHING HERE WRITES TO A STREAM, ASKS ANYBODY ANYTHING OR PICKS AN EXIT CODE, and nothing
+//   reaches for `node:` — the chain and the signature are loaded only when no seam was supplied.
+import { NmtsError } from "../errors.js";
+import { canFuse } from "../shared/lib/storage-control/plan.js";
+import { isValidSuiAddress } from "../shared/lib/wallet/send-rules.js";
+import { formatBytes, readOrRefuse } from "./list.js";
+/** Why two resources cannot be joined, in the contract's own terms. */
+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.",
+};
+/**
+ * Judge one request against the resources this wallet actually holds.
+ *
+ * ⛔ EVERY REFUSAL HAPPENS HERE, BEFORE THE CHAIN IS ASKED ANYTHING. Letting the contract refuse it
+ *    instead leaves somebody having paid gas with no idea why — the rule the browser's own
+ *    judgement (`shared/lib/storage-control/plan.ts`) was written for.
+ */
+export function planStorageOp(held, ask, hints = {}) {
+    const one = (id) => {
+        const found = held.find((r) => r.objectId === id);
+        if (found === undefined) {
+            throw new NmtsError(`This wallet holds no free storage resource ${id}.`, {
+                exitCode: 4,
+                nextStep: hints.notHeld ??
+                    "Nothing was signed. A storage listing shows the free ones it holds; a resource bound " +
+                        "inside a file is not free.",
+            });
+        }
+        return found;
+    };
+    // ⛔ THE JUDGEMENT IS HERE AND THE WORD FOR IT IS THE CALLER'S. What was too big has a different
+    //    name at a prompt and in a program, and neither should be told about the other's.
+    const tooBig = (what, limit) => hints.cut?.(what, limit) ??
+        new NmtsError(what === "size"
+            ? `A cut by size keeps above 0 and below the resource's ${limit}.`
+            : `A cut by period keeps a whole number of epochs above 0 and below the resource's ${limit}.`, { exitCode: 2, nextStep: "Nothing was signed. The rest becomes a second resource, so there has to be a rest." });
+    const shapeOf = (r) => ({
+        sizeBytes: r.sizeBytes,
+        startEpoch: r.startEpoch,
+        endEpoch: r.endEpoch,
+    });
+    if (ask.kind === "splitSize") {
+        const r = one(ask.objectId);
+        if (ask.keepBytes <= 0 || ask.keepBytes >= r.sizeBytes)
+            throw tooBig("size", formatBytes(r.sizeBytes));
+        return {
+            op: "split",
+            shape: { kind: "splitSize", objectId: ask.objectId, keepBytes: ask.keepBytes },
+            action: "reshape",
+            named: [r],
+            result: {
+                kind: "split",
+                keeps: { ...shapeOf(r), sizeBytes: ask.keepBytes },
+                creates: { ...shapeOf(r), sizeBytes: r.sizeBytes - ask.keepBytes },
+            },
+        };
+    }
+    if (ask.kind === "splitEpochs") {
+        const r = one(ask.objectId);
+        const span = r.endEpoch - r.startEpoch;
+        if (!Number.isSafeInteger(ask.keepEpochs) || ask.keepEpochs <= 0 || ask.keepEpochs >= span) {
+            throw tooBig("period", String(span));
+        }
+        const at = r.startEpoch + ask.keepEpochs;
+        return {
+            op: "split",
+            shape: { kind: "splitEpoch", objectId: ask.objectId, splitEpoch: at },
+            action: "reshape",
+            named: [r],
+            result: {
+                kind: "split",
+                keeps: { ...shapeOf(r), endEpoch: at },
+                creates: { ...shapeOf(r), startEpoch: at },
+            },
+        };
+    }
+    if (ask.kind === "merge") {
+        const first = one(ask.first);
+        const second = one(ask.second);
+        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. A storage listing shows each one's size and period.",
+            });
+        }
+        return {
+            op: "merge",
+            shape: { kind: "fuse", first: ask.first, second: ask.second, how: verdict.kind },
+            action: "reshape",
+            named: [first, second],
+            result: {
+                kind: "merge",
+                how: verdict.kind,
+                consumed: ask.second,
+                becomes: verdict.kind === "amount"
+                    ? { ...shapeOf(first), sizeBytes: first.sizeBytes + second.sizeBytes }
+                    : {
+                        sizeBytes: first.sizeBytes,
+                        startEpoch: Math.min(first.startEpoch, second.startEpoch),
+                        endEpoch: Math.max(first.endEpoch, second.endEpoch),
+                    },
+            },
+        };
+    }
+    const r = one(ask.objectId);
+    // ⛔ THE ADDRESS IS JUDGED BEFORE THE CHAIN IS ASKED. A resource sent to a mistyped address is
+    //    gone: nothing here, and nobody at NMTS, can recall it.
+    if (!isValidSuiAddress(ask.to)) {
+        throw new NmtsError("That is not a Sui address: it is 0x followed by 64 hexadecimal characters.", {
+            exitCode: 2,
+            nextStep: "Nothing was signed. Check the address it should go to.",
+        });
+    }
+    return {
+        op: "transfer",
+        shape: { kind: "transfer", objectId: ask.objectId, to: ask.to },
+        action: "give",
+        named: [r],
+        result: { kind: "transfer", moves: shapeOf(r), to: ask.to },
+    };
+}
+/** Read, judge, price and — unless somebody stops it — sign one change to a storage resource. */
+export async function reshapeStorage(context, ask, seams = {}) {
+    const reads = seams.reads === undefined
+        ? (await import("../storage-control-chain.js")).storageOpsReads(context.network)
+        : seams.reads(context.network);
+    // ① The resources, and which epoch it is.
+    const read = await readOrRefuse(() => reads.readStorage(context.address), seams.hints ?? {});
+    // ② The request, judged.
+    const plan = planStorageOp(read.items, ask, seams.hints ?? {});
+    const walrusPackageId = await reads.walrusPackageId();
+    // ③ The dry run: the fee, or the contract's own refusal.
+    const verdict = await reads.dryRun(plan.shape, context.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.",
+        });
+    }
+    // ④ The review.
+    const review = {
+        plan,
+        address: context.address,
+        network: context.network,
+        currentEpoch: read.currentEpoch,
+        feeMist: verdict.feeMist,
+    };
+    seams.onReview?.(review);
+    // ⑤ Stopped here, with nothing signed.
+    if (seams.dryRun === true)
+        return { kind: "review", review };
+    // ⑥ The gate.
+    seams.agree?.(review);
+    // ⑦ The signature.
+    const sign = seams.sign ?? (await import("../wallet-sign.js")).signStorageOp;
+    const digest = await sign({
+        network: context.network,
+        code: context.code,
+        wallet: context.wallet,
+        shape: plan.shape,
+        walrusPackageId,
+    });
+    return { kind: "done", review, digest };
+}

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

@@ -1,6 +1,6 @@
 import { Transaction } from "@mysten/sui/transactions";
 import type { Network } from "./network.ts";
-import type { StorageRead } from "./commands/wallet-storage.ts";
+import type { StorageRead } from "./storage-control/list.ts";
 export type StorageOpShape = {
     kind: "splitSize";
     objectId: string;