@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/shared/lib/extend/epochs.d.ts

@@ -0,0 +1,205 @@
+/** One blob's lease, as the chain currently has it. */
+export interface BlobLease {
+    /** Sui object id of the blob. */
+    objectId: string;
+    /** Unencoded size in bytes (Blob.size) — what the storage price is computed from. */
+    size: number;
+    /** The epoch the lease runs out at (Blob.storage.end_epoch). THE authoritative expiry. */
+    endEpoch: number;
+}
+/** Where the network is now, how far ahead anyone may buy, and how long an epoch lasts. */
+export interface EpochWindow {
+    /** The epoch the network is in. */
+    current: number;
+    /**
+     * How many epochs ahead of `current` a lease may reach — the protocol's
+     * `storage_accounting::max_epochs_ahead`, read as the future-accounting ring length (that is
+     * exactly what the Move function returns). Measured 53 on testnet, 2026-07-27.
+     */
+    maxAhead: number;
+    /** One epoch's length in milliseconds (testnet 1 day · mainnet 14 days — read, not assumed). */
+    durationMs: number;
+    /**
+     * When the current epoch began, in ms. Null while the network is mid-epoch-change, in which case
+     * no date is shown at all — a wrong date on a screen about deletion is worse than no date.
+     */
+    startedMs: number | null;
+}
+/**
+ * The wall-clock moment an epoch is reached, from the network's own epoch clock. Null when there
+ * is no anchor to measure from.
+ *
+ * ⚠ An ESTIMATE, and labelled as one wherever it is shown: epoch changes can run late, and the
+ * measured history proves it (epoch 471 began 9 days later than `first_epoch_start` plus 470 × the
+ * epoch length would put it). Never present this as the exact deletion time.
+ */
+export declare function epochDate(window: LeaseClock, epoch: number): Date | null;
+/**
+ * The window an epoch can arrive in — an answer even when the clock is only APPROXIMATE.
+ *
+ * ⚠ The two ends are clamped at "now" only on the approximate branch, where a negative bound is an
+ * artefact of not knowing how far into the current epoch we are. An anchored date that lands in the
+ * past is a real answer (the lease ended on that day) and is returned as it is.
+ */
+export declare function epochDateBounds(clock: LeaseClock, epoch: number, nowMs: number): {
+    earliest: Date;
+    latest: Date;
+    exact: boolean;
+} | null;
+/**
+ * Warn from here on. Two stages: a plain note, then a red one.
+ *
+ * ⭐ THEY LIVE HERE, NOT IN THE COMPONENT THAT DRAWS THE BANNER (moved 2026-07-30). Two surfaces
+ * now read them — the drive-wide banner (`ExpiryNotice`) and every file row's own status
+ * (`lib/drive/file-status.ts`). A copy in each is how a banner ends up shouting "extend now" over
+ * a list of rows that all say "sealed", with neither file looking wrong on its own.
+ * ⚠ A `.tsx` cannot hold them either: `node --test` reads plain `.ts` and not `.tsx`, so a constant
+ * parked in a component is a constant no pure test can check.
+ *
+ * Both stages are a floor in DAYS and a floor in EPOCHS, and the wider one wins (see
+ * `warningEpochs`). The epoch figures are what mainnet is really sized by: 3 epochs is six weeks of
+ * runway there, and 1 epoch — the urgent stage — is the last two weeks in which extending is still
+ * possible at all.
+ */
+export declare const NOTICE_DAYS = 14;
+export declare const NOTICE_EPOCHS = 3;
+export declare const URGENT_DAYS = 3;
+export declare const URGENT_EPOCHS = 1;
+/**
+ * How far ahead the expiry warning starts, in epochs: a floor in DAYS and a floor in EPOCHS, wider
+ * one wins.
+ *
+ * Counted in days alone, mainnet's 14-day epoch made the whole warning exactly ONE epoch wide, so
+ * someone who opens the app monthly missed it entirely. Counted in epochs alone, testnet's 1-day
+ * epoch would have shrunk the window from 14 days to 3. Taking whichever is longer never narrows
+ * either network's warning — and the day-count rounds UP, because arriving a tick late is the
+ * quiet failure this whole surface exists to prevent.
+ */
+export declare function warningEpochs(days: number, floorEpochs: number, durationMs: number): number;
+/** The part of the epoch clock that turns an end epoch into a number of days. */
+export interface LeaseClock {
+    /** The epoch the network is in. */
+    current: number;
+    /** One epoch's length in ms — 1 day on testnet, 14 on mainnet. Read, never assumed. */
+    durationMs: number;
+    /**
+     * When the current epoch began, when the network said so (`EpochChangeDone`). Absent or null ⇒
+     * there is no anchor, and every figure derived from this clock is a FLOOR rather than a
+     * measurement. Optional so a caller with only the two numbers above still type-checks; the real
+     * clock (`EpochWindow`) always carries it.
+     */
+    startedMs?: number | null;
+}
+/** Whole days until a lease ends, and whether that number is a measurement or a floor. */
+export interface DaysLeft {
+    /** Rounded DOWN. Negative is a real answer — the epoch is already behind us. */
+    days: number;
+    /** False ⇒ `days` is a LOWER BOUND and the words beside it must say "or more". */
+    exact: boolean;
+}
+/**
+ * Whole days from now until `epoch` is reached, by the network's own epoch clock.
+ *
+ * ⛔ THE SAFE EDGE, NOT THE OPTIMISTIC ONE (fixed 2026-08-16). This used to be
+ * `(epoch − current) × epochLength`, which ignores the time already spent inside the current epoch
+ * — on mainnet that overstates the runway by up to fourteen days, and it did: 28 shown where the
+ * chain said 23. Without an anchor the answer is now the floor of `epochArrival`'s `minMs`, and
+ * `exact: false` tells the surface to say "N days or more" instead of making a flat claim.
+ *
+ * ⛔ Never substitute `NETWORK.epochDays` for the clock here. That constant is the MAINNET basis
+ * (14); using it on testnet, where an epoch is one day, would report 196 days over a file with
+ * fourteen days to live.
+ *
+ * Null when the clock carries no usable epoch length — the caller says the period is unread rather
+ * than counting days from a constant.
+ */
+export declare function daysLeftUntilEpoch(epoch: number, clock: LeaseClock, nowMs: number): DaysLeft | null;
+/** How much time is left, broken into the units a person reads off a clock. */
+export interface TimeLeft {
+    /** Whole days. */
+    days: number;
+    /** 0–23. */
+    hours: number;
+    /** 0–59. */
+    minutes: number;
+    /** 0–59. */
+    seconds: number;
+    /** Total milliseconds, floored at zero. */
+    totalMs: number;
+    /** False ⇒ this is a LOWER BOUND — the real moment is later, by up to one epoch. */
+    exact: boolean;
+}
+/**
+ * The same answer `daysLeftUntilEpoch` gives, down to the second.
+ *
+ * ⭐ WHY THIS EXISTS: a day count is the right thing to glance at and the wrong thing to plan by
+ * on the last day. "1 day left" covers everything from twenty-four hours to one minute, and by
+ * then the only question left is whether there is time to deal with it tonight.
+ *
+ * ⛔ IT IS THE SAME EDGE AS THE DAY COUNT, on purpose. Both take `epochArrival`'s `minMs`, so the
+ *    two can never disagree: a countdown reading three hours under a label reading "2 days left"
+ *    would be two numbers about one fact, and a person believes the reassuring one.
+ *
+ * ⚠ EVEN EXACT IS AN ESTIMATE, and the direction is known: an epoch change can run LATE, never
+ *   early, so this can only be early. Measured on mainnet 2026-08-25 — 36 epochs after the first,
+ *   the accumulated drift was nine minutes.
+ *
+ * Null on the same input as `daysLeftUntilEpoch`: no usable epoch length.
+ */
+export declare function timeLeftUntilEpoch(epoch: number, clock: LeaseClock, nowMs: number): TimeLeft | null;
+/**
+ * The largest number of epochs these leases can ALL be extended by.
+ *
+ * The ceiling is per-blob: a lease may not end more than `maxAhead` epochs past the current one,
+ * so the blob that already reaches furthest into the future is the binding one. Returns 0 when
+ * nothing more can be bought yet — which is a real answer ("already paid as far ahead as the
+ * network allows"), not an error.
+ */
+export declare function headroom(leases: readonly BlobLease[], window: EpochWindow): number;
+/**
+ * The enum cases of the network's `epoch_state` that carry WHEN THE CURRENT EPOCH BEGAN.
+ *
+ * ⛔ THERE ARE TWO OF THEM, AND READING ONLY THE FIRST COST US A FORTNIGHT OF PRECISION. The Move
+ *    enum has three cases: `EpochChangeSync` (a node count — a small integer, NOT a moment),
+ *    `EpochChangeDone` (the moment this epoch's change happened), and `NextParamsSelected` (the
+ *    same moment, kept after the next epoch's parameters are chosen). A network settles into the
+ *    LAST of those and stays there, so an implementation that accepted `EpochChangeDone` alone
+ *    threw the anchor away nearly always. Measured on mainnet 2026-08-25: epoch 37 reported
+ *    `NextParamsSelected` holding 2026-08-11T15:08:58Z — exactly one epoch before its end. Without
+ *    it `epochArrival` falls back to a range ONE WHOLE EPOCH wide (fourteen days on mainnet), and
+ *    every surface that counts down to a deletion then says "as early as N days" — honest, and
+ *    useless to somebody deciding whether to pay for more time.
+ *
+ * ⛔ THIS IS AN ALLOW-LIST, NOT A DENY-LIST. `EpochChangeSync` carries a `u16`, which is finite and
+ *    would happily become a date in 1970; and a case this code has not been taught must report NO
+ *    anchor rather than guess. Losing precision costs a warning that comes early. Guessing costs a
+ *    deleted file.
+ */
+export declare const EPOCH_START_VARIANTS: readonly string[];
+/**
+ * When the current epoch began, in ms — or null when this reading cannot say.
+ *
+ * ⭐ ONE OF IT, ON PURPOSE. Both the browser and the command-line tool read the same enum for the
+ * same reason, and a second narrowing elsewhere would be a second answer to "has this epoch
+ * settled" — the two would drift the day the protocol renames a case, and drift here is a wrong
+ * deletion date on a screen where somebody spends money.
+ *
+ * Read by name rather than cast: a shape change in the protocol has to surface as "no anchor",
+ * which costs precision, instead of as a NaN that becomes a date.
+ */
+export declare function epochStartedMs(epochState: unknown): number | null;
+/**
+ * When a file actually runs out: the SOONEST end epoch across the blobs it rides on. Null when
+ * there is no lease to read.
+ *
+ * ⚠ NULL IS NOT A ZERO AND NOT "NOW" (2026-07-28). The sheet that shows this used to
+ * substitute the CURRENT epoch when the list was empty, and so printed today's date under "expires
+ * on" above the sentence "after this date the file is deleted and cannot be recovered" —
+ * telling someone their file dies today. The empty case is reached by real files: every part on
+ * treasury-paid storage, or parts old enough to carry no on-chain object id, produce no targets
+ * and therefore no leases. There is no epoch to report for those, so this reports none and the
+ * caller shows nothing rather than a number it invented.
+ *
+ * SOONEST, not furthest: one expired blob is enough to make the file unreadable.
+ */
+export declare function soonestEnd(leases: readonly BlobLease[]): number | null;

package/dist/shared/lib/net/retry-budget.d.ts

@@ -0,0 +1,79 @@
+/** First wait after a failure, before jitter. */
+export declare const RETRY_BASE_MS = 1000;
+/**
+ * The longest single wait. Without a ceiling the ninth backoff is eight minutes, and a person
+ * watching a progress bar cannot tell that from a program that has stopped.
+ */
+export declare const RETRY_MAX_WAIT_MS = 30000;
+/**
+ * How long to go on retrying while the network is reachable and the far side keeps failing.
+ *
+ * ⚠ THIS IS THE UPLOAD-SHAPED DEFAULT: money is already spent, the work resumes where it stopped,
+ *   and nobody is staring at it. A surface where none of that is true passes its own (`budgetMs`).
+ */
+export declare const RETRY_BUDGET_MS: number;
+/**
+ * The budget for something a person is watching and can simply ask for again — a download.
+ *
+ * ⚠ It is not small because failing is fine; it is small because ten minutes of "still trying" is
+ *   indistinguishable from a program that has stopped, and pressing again costs nothing here.
+ */
+export declare const WATCHED_RETRY_BUDGET_MS = 60000;
+/** The matching offline bound for a watched surface. */
+export declare const WATCHED_OFFLINE_BUDGET_MS: number;
+/** How long to go on waiting while there is no network at all. Longer, because waiting is free. */
+export declare const OFFLINE_BUDGET_MS: number;
+/** How often to look again while offline. The `online` event is the real signal; this is the net. */
+export declare const OFFLINE_POLL_MS = 2000;
+/** What the caller should do next. */
+export interface NextAttempt {
+    /** False ⇒ the budget is spent. Report the failure honestly and stop. */
+    readonly again: boolean;
+    /** How long to wait first, in ms. */
+    readonly waitMs: number;
+    /**
+     * True ⇒ this wait is for the network to come back, not for a busy server.
+     *
+     * ⛔ The caller must NOT add this wait to `elapsedOnlineMs`, and the screen must say
+     *    「waiting for the network」 rather than 「retrying」 — those are different facts, and only
+     *    one of them is something the person can do anything about.
+     */
+    readonly waitingForNetwork: boolean;
+}
+export interface AttemptInput {
+    /** 1-based number of the attempt that just failed. */
+    readonly attempt: number;
+    /** Wall clock spent retrying WHILE ONLINE, in ms. Offline waiting is not counted here. */
+    readonly elapsedOnlineMs: number;
+    /** Wall clock spent waiting for a network, in ms. */
+    readonly elapsedOfflineMs: number;
+    /** What the browser says about having a network. Believed only when it says no. */
+    readonly online: boolean;
+    /** A number in [0, 1). Passed in so the jitter is reproducible in a test. */
+    readonly random: number;
+    /**
+     * How long to go on retrying while online. Defaults to {@link RETRY_BUDGET_MS}.
+     *
+     * ⛔ IT IS NOT ONE NUMBER FOR EVERYTHING, because the two sides are not the same bargain. An
+     *    upload has money already spent on it and resumes where it stopped, so waiting is cheap and
+     *    giving up is expensive. A download has nothing at stake and the person is watching it — ten
+     *    minutes of "still trying" there is a program that looks broken, and pressing it again costs
+     *    nothing. So the caller says.
+     */
+    readonly budgetMs?: number;
+    /** How long to go on waiting for a network. Defaults to {@link OFFLINE_BUDGET_MS}. */
+    readonly offlineBudgetMs?: number;
+}
+/**
+ * What to do after one failed attempt.
+ *
+ * ⛔ THE ORDER OF THE TWO CHECKS MATTERS. Offline is decided first, because a failure that
+ *    happened because there is no network must not spend the online budget — otherwise a tunnel
+ *    long enough to exhaust it turns into a failed upload the moment the network returns.
+ */
+export declare function nextAttempt(input: AttemptInput): NextAttempt;
+/**
+ * How much of the budget is left, as a fraction — for a screen that wants to say how long it will
+ * go on trying. Null when nothing has been spent on this kind of waiting yet.
+ */
+export declare function budgetLeft(elapsedMs: number, waitingForNetwork: boolean): number;

package/dist/shared/lib/share/shared-file-info.d.ts

@@ -0,0 +1,21 @@
+/** What a recipient learns about a shared file before fetching a byte of it. */
+export interface SharedFileInfo {
+    /** Plaintext file name, exactly as the sender's drive spells it. */
+    name: string;
+    /**
+     * The file's REAL plaintext length. Absent for a share sealed before this document existed.
+     *
+     * Absent must be read as "not recorded", never as "zero" and never as "unpadded": what makes an
+     * older share safe is the content hash, not this field.
+     */
+    size?: number;
+}
+/** The string to seal as `name_share_ct`. */
+export declare function encodeSharedFileInfo(info: SharedFileInfo): string;
+/**
+ * Read what the sender sealed. Never throws: a name that cannot be parsed IS the name.
+ *
+ * The refusal to throw is deliberate. This runs while painting a list of everything shared with a
+ * person, and one row whose document is malformed must not take the other rows' names down with it.
+ */
+export declare function decodeSharedFileInfo(sealed: string): SharedFileInfo;

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

@@ -0,0 +1,57 @@
+/**
+ * The slice of a Sui RPC client this file uses. Structural on purpose: the browser hands in its
+ * Walrus-extended client and the command-line tool its plain JSON-RPC client, and neither has to
+ * be named here.
+ */
+export interface StorageChainReader {
+    getObject(input: {
+        id: string;
+        options: {
+            showType: true;
+        };
+    }): Promise<{
+        data?: {
+            type?: string | null;
+        } | null;
+    }>;
+    getOwnedObjects(input: {
+        owner: string;
+        filter: {
+            StructType: string;
+        };
+        options: {
+            showContent: true;
+        };
+        cursor?: string;
+    }): Promise<{
+        data?: readonly unknown[] | null;
+        hasNextPage?: boolean;
+        nextCursor?: string | null;
+    }>;
+}
+/** One storage resource — the chain's `Storage { id, start_epoch, end_epoch, storage_size }` as is. */
+export interface StorageResource {
+    /** The Sui object id. */
+    readonly objectId: string;
+    /** The epoch from which this resource can be used. */
+    readonly startEpoch: number;
+    /** The epoch at which it ends. */
+    readonly endEpoch: number;
+    /** How much it can hold AFTER encoding, in bytes. ⚠ Not a plaintext size. */
+    readonly sizeBytes: number;
+}
+/**
+ * This network's storage-resource type name, derived from the system object.
+ *
+ * ⛔ `showType` only — the content is not needed, and asking for it returns a large answer.
+ */
+export declare function readStorageType(client: StorageChainReader, systemObjectId: string): Promise<string>;
+/** One object response as a storage resource. A different shape gives null — it quietly leaves the list. */
+export declare function toStorageResource(node: unknown): StorageResource | null;
+/**
+ * Every storage resource this address holds.
+ *
+ * ⚠ Follows the pages to the end. Reading only the first would show a person with many resources
+ *   SOME OF THEM AS IF THEY WERE ALL, which is a worse lie than "none".
+ */
+export declare function readOwnedStorage(client: StorageChainReader, owner: string, storageType: string, maxPages?: number): Promise<StorageResource[]>;

package/dist/shared/lib/storage-control/chain.js

@@ -0,0 +1,82 @@
+// Storage resources — the "size × time" a wallet holds, read from the chain. ⚠ PUBLISHED —
+// copied byte-for-byte into the `nmts` command-line package; keep comments self-contained English.
+//
+// ⛔ WHY THIS EXISTS (owner directive 2026-08-10, pressed again 2026-08-27). What the storage
+//    network sells is not a file but an OBJECT WITH A SIZE AND A PERIOD. Deleting a file gives
+//    that object BACK TO ITS OWNER — and until this, the product had nowhere to see what came
+//    back, nor to use it: the erase path sent it to the person's address and stopped, so paid-for
+//    space sat there unseen.
+//
+// ⛔ THE TYPE NAME IS NOT WRITTEN AS A CONSTANT. When Walrus upgrades its contract the package
+//    address changes, but a Move type carries the package that FIRST defined it. So the name is cut
+//    from the system object's own type — an object that survives upgrades (the same judgement the
+//    wallet configuration makes). ⚠ Written by hand, the list would fall to "none" — not to an
+//    error — on the day of the next upgrade.
+//
+// ⛔ EVERYTHING HERE IS A READ. Splitting, fusing and transferring need a signature and are not here.
+//
+// FAILURE MODES: what cannot be read THROWS — it is not flattened to "0 resources". Having none and
+//   failing to read are different facts to a person, and drawing both as one screen is a defect this
+//   product has stepped on more than once.
+/**
+ * This network's storage-resource type name, derived from the system object.
+ *
+ * ⛔ `showType` only — the content is not needed, and asking for it returns a large answer.
+ */
+export async function readStorageType(client, systemObjectId) {
+    const res = await client.getObject({ id: systemObjectId, options: { showType: true } });
+    const type = res.data?.type;
+    if (typeof type !== "string" || !type.includes("::")) {
+        throw new Error("The storage network's system object did not say its type.");
+    }
+    return `${type.split("::")[0]}::storage_resource::Storage`;
+}
+/** One object response as a storage resource. A different shape gives null — it quietly leaves the list. */
+export function toStorageResource(node) {
+    if (typeof node !== "object" || node === null)
+        return null;
+    const data = Reflect.get(node, "data");
+    if (typeof data !== "object" || data === null)
+        return null;
+    const objectId = Reflect.get(data, "objectId");
+    const content = Reflect.get(data, "content");
+    if (typeof objectId !== "string" || typeof content !== "object" || content === null)
+        return null;
+    const fields = Reflect.get(content, "fields");
+    if (typeof fields !== "object" || fields === null)
+        return null;
+    const start = Number(Reflect.get(fields, "start_epoch"));
+    const end = Number(Reflect.get(fields, "end_epoch"));
+    const size = Number(Reflect.get(fields, "storage_size"));
+    if (!Number.isFinite(start) || !Number.isFinite(end) || !Number.isFinite(size))
+        return null;
+    return { objectId, startEpoch: start, endEpoch: end, sizeBytes: size };
+}
+/**
+ * Every storage resource this address holds.
+ *
+ * ⚠ Follows the pages to the end. Reading only the first would show a person with many resources
+ *   SOME OF THEM AS IF THEY WERE ALL, which is a worse lie than "none".
+ */
+export async function readOwnedStorage(client, owner, storageType, maxPages = 20) {
+    const out = [];
+    let cursor = null;
+    for (let page = 0; page < maxPages; page += 1) {
+        const res = await client.getOwnedObjects({
+            owner,
+            filter: { StructType: storageType },
+            options: { showContent: true },
+            ...(cursor === null ? {} : { cursor }),
+        });
+        for (const node of res.data ?? []) {
+            const one = toStorageResource(node);
+            if (one !== null)
+                out.push(one);
+        }
+        if (res.hasNextPage !== true || typeof res.nextCursor !== "string")
+            return out;
+        cursor = res.nextCursor;
+    }
+    // ⛔ Hitting the page ceiling is SAID. Cutting quietly would make the screen claim "this is all".
+    throw new Error("Too many storage resources to read in one go.");
+}

package/dist/shared/lib/storage-control/plan.d.ts

@@ -0,0 +1,40 @@
+import type { StorageResource } from "./chain.ts";
+/** Whether two resources can be fused, and if not, why. */
+export type FuseVerdict = {
+    readonly can: true;
+    readonly kind: "amount" | "periods";
+} | {
+    readonly can: false;
+    readonly why: "differentPeriod" | "differentSize" | "notAdjacent" | "same";
+};
+/**
+ * Whether the contract will fuse these two.
+ *
+ * ⚠ Written so the order does not matter — the order a person picks them in means nothing.
+ */
+export declare function canFuse(a: StorageResource, b: StorageResource): FuseVerdict;
+/**
+ * Where a resource stands against the current epoch.
+ *
+ * ⛔ "Ended" is decided by COMPARING EPOCHS, not dates — the rule this product learned from its
+ *    expiry display, for the same reason here.
+ */
+export declare function statusOf(resource: StorageResource, currentEpoch: number): "lapsed" | "notYet" | "usable";
+/** Usable ones first, largest first. The order a list shows before anything else. */
+export declare function usableFirst(resources: readonly StorageResource[], currentEpoch: number): StorageResource[];
+/**
+ * Whether a file of `encodedBytes` that must last until `needUntilEpoch` fits in this resource.
+ *
+ * ⚠ `encodedBytes` is the size AFTER the storage network's encoding, not the plaintext size.
+ */
+export declare function fits(resource: StorageResource, encodedBytes: number, needUntilEpoch: number): boolean;
+/**
+ * What is left of the resource after that file goes in.
+ *
+ * ⛔ Registration DOES NOT GIVE THE REMAINDER BACK — putting 500 MB into a 1 GB resource binds
+ *    the whole gigabyte. That is why this number is shown: it is what a person chooses "cut to
+ *    fit" or "use whole" on.
+ */
+export declare function leftoverBytes(resource: StorageResource, encodedBytes: number): number;
+/** The sizes of the usable resources added up — the "space held right now" line. */
+export declare function totalUsableBytes(resources: readonly StorageResource[], currentEpoch: number): number;

package/dist/shared/lib/storage-control/plan.js

@@ -0,0 +1,72 @@
+// What can be done with a storage resource — pure judgement. Touches no chain and no screen.
+// ⚠ PUBLISHED — copied byte-for-byte into the `nmts` command-line package; keep comments
+// self-contained English.
+//
+// ⛔ ONLY WHAT THE CONTRACT ALLOWS IS ALLOWED (`storage_resource.move`, read verbatim 2026-08-11):
+//    · `fuse_amount` — the periods must be IDENTICAL for the sizes to add;
+//    · `fuse_periods` — the sizes must be equal and the periods ADJACENT for the periods to join;
+//    · `split_by_size` / `split_by_epoch` — cut by size, or by period.
+//    ⛔ No other combination fuses. Leaving a button alive and letting the chain refuse it leaves
+//       the person having PAID GAS with no idea why. So the answer is given here, first.
+//
+// ⛔ The reason it cannot be done is returned with the verdict. A greyed-out button alone is a
+//    shape this product has already forbidden (the final approval never stands grey and silent).
+/**
+ * Whether the contract will fuse these two.
+ *
+ * ⚠ Written so the order does not matter — the order a person picks them in means nothing.
+ */
+export function canFuse(a, b) {
+    if (a.objectId === b.objectId)
+        return { can: false, why: "same" };
+    const samePeriod = a.startEpoch === b.startEpoch && a.endEpoch === b.endEpoch;
+    if (samePeriod)
+        return { can: true, kind: "amount" };
+    const sameSize = a.sizeBytes === b.sizeBytes;
+    if (!sameSize)
+        return { can: false, why: "differentSize" };
+    const adjacent = a.endEpoch === b.startEpoch || b.endEpoch === a.startEpoch;
+    return adjacent ? { can: true, kind: "periods" } : { can: false, why: "notAdjacent" };
+}
+/**
+ * Where a resource stands against the current epoch.
+ *
+ * ⛔ "Ended" is decided by COMPARING EPOCHS, not dates — the rule this product learned from its
+ *    expiry display, for the same reason here.
+ */
+export function statusOf(resource, currentEpoch) {
+    if (resource.endEpoch <= currentEpoch)
+        return "lapsed";
+    if (resource.startEpoch > currentEpoch)
+        return "notYet";
+    return "usable";
+}
+/** Usable ones first, largest first. The order a list shows before anything else. */
+export function usableFirst(resources, currentEpoch) {
+    const rank = (r) => ({ usable: 0, notYet: 1, lapsed: 2 })[statusOf(r, currentEpoch)];
+    return [...resources].sort((x, y) => rank(x) - rank(y) || y.sizeBytes - x.sizeBytes || y.endEpoch - x.endEpoch);
+}
+/**
+ * Whether a file of `encodedBytes` that must last until `needUntilEpoch` fits in this resource.
+ *
+ * ⚠ `encodedBytes` is the size AFTER the storage network's encoding, not the plaintext size.
+ */
+export function fits(resource, encodedBytes, needUntilEpoch) {
+    return resource.sizeBytes >= encodedBytes && resource.endEpoch >= needUntilEpoch;
+}
+/**
+ * What is left of the resource after that file goes in.
+ *
+ * ⛔ Registration DOES NOT GIVE THE REMAINDER BACK — putting 500 MB into a 1 GB resource binds
+ *    the whole gigabyte. That is why this number is shown: it is what a person chooses "cut to
+ *    fit" or "use whole" on.
+ */
+export function leftoverBytes(resource, encodedBytes) {
+    return Math.max(0, resource.sizeBytes - encodedBytes);
+}
+/** The sizes of the usable resources added up — the "space held right now" line. */
+export function totalUsableBytes(resources, currentEpoch) {
+    return resources
+        .filter((r) => statusOf(r, currentEpoch) === "usable")
+        .reduce((sum, r) => sum + r.sizeBytes, 0);
+}

package/dist/shared/lib/storage-control/reuse.d.ts

@@ -0,0 +1,72 @@
+import { Transaction } from "@mysten/sui/transactions";
+/** Whether one resource CERTAINLY holds this file — true means it does; false means "unknown", not "it cannot". */
+export interface FitInput {
+    /** The space the resource holds (bytes AFTER encoding) — the chain's `storage_size`. */
+    readonly resourceSizeBytes: number;
+    /** The BEFORE-encoding size of the file this resource used to hold. Absent = defer the judgement. */
+    readonly heldRawBytes?: number;
+    /** The BEFORE-encoding size of the file about to go in. */
+    readonly newRawBytes: number;
+    /** The epoch the resource ends at. */
+    readonly resourceEndEpoch: number;
+    /** The current epoch. */
+    readonly currentEpoch: number;
+}
+/**
+ * Only "it certainly fits" is true.
+ *
+ * ⛔ THE ENCODED LENGTH IS NOT COMPUTED HERE. That arithmetic is the protocol's and lives inside
+ *    the SDK (unexported); a copy kept here would be wrong the day they change it, and only we
+ *    would not know. ▶ Instead MONOTONICITY alone is used: the encoded length never shrinks as the
+ *    raw length grows, so a new file no larger than the one the resource held certainly fits.
+ * ⚠ This is therefore a SUFFICIENT condition. When it is false the real answer comes from a dry
+ *   run — resources carry a 63 MiB floor, so a slightly larger file fitting a small file's slot
+ *   is common in practice.
+ */
+export declare function surelyFits(input: FitInput): boolean;
+export interface RegisterIntoInput {
+    /** The Walrus system object. */
+    readonly systemObjectId: string;
+    /** The package to CALL — the system object's `package_id` field. ⛔ Not the type's prefix. */
+    readonly walrusPackageId: string;
+    /** The full type name of the WAL coin. */
+    readonly walType: string;
+    /** The resource already held. */
+    readonly storageObjectId: string;
+    /** What the encoder produced. */
+    readonly blobIdAsInt: bigint;
+    readonly rootHash: Uint8Array;
+    readonly rawBytes: number;
+    /** The write cost for this size, in FROST (WAL base units). */
+    readonly writeCost: bigint;
+    readonly deletable: boolean;
+    /** Where the created blob object goes. */
+    readonly owner: string;
+}
+/** A registration that uses ONE held storage resource as it is. */
+export declare function registerIntoStorage(input: RegisterIntoInput, transaction?: Transaction): Transaction;
+export interface SplitToFitInput {
+    /** The package to CALL — the system object's `package_id`, as above. */
+    readonly walrusPackageId: string;
+    /** The resource to cut. After this call it is exactly `keepBytes` large. */
+    readonly storageObjectId: string;
+    /** The encoded size the file needs — what the cut resource keeps. */
+    readonly keepBytes: number;
+    /** Where the remainder — a NEW resource object — goes. */
+    readonly owner: string;
+}
+/**
+ * "Cut to fit": shrink a held resource to exactly what the file needs, so the rest stays a free
+ * resource instead of being bound inside the blob. The owner's rule: the person chooses between
+ * cutting and binding whole, and is shown the leftover in bytes — no default is chosen for them.
+ *
+ * ⛔ WHICH HALF IS WHICH IS THE CONTRACT'S CHOICE, read from `storage_resource.move`: `split_by_size`
+ *    MODIFIES the given resource down to `split_size` and RETURNS a new object holding the rest.
+ *    So the object id the caller already holds is the one that registers the blob afterwards, and
+ *    the returned object is the leftover — which must be transferred, or the transaction is
+ *    refused at assembly for an unused value.
+ *
+ * ⚠ `keepBytes` must be the ENCODED size (the chain's `encoded_blob_length`), never the raw one:
+ *   registration checks `encoded_size <= storage_size` and a resource cut to the raw size fails it.
+ */
+export declare function splitStorageToFit(input: SplitToFitInput, transaction?: Transaction): Transaction;