@needmoretruth/nmts-cli 0.17.2

package/dist/shared/lib/drive/unique-name.js

@@ -0,0 +1,48 @@
+// Give an uploaded file a name that is not already in use in its destination folder —
+// `report.pdf` → `report (2).pdf`. ⚠ PUBLISHED — copied byte-for-byte into the `nmts` command-line
+// package; keep comments self-contained English.
+//
+// WHY THIS INSTEAD OF OVERWRITING: the alternative on the table was
+//   "same name replaces the old file". Replacing destroys data that cannot be got back — NMTS
+//   keeps no previous versions, so an accidental same-name upload would be permanent loss — and
+//   keeping previous versions would mean paying Walrus storage for every generation, out of the
+//   user's own wallet. Suffixing costs nothing, loses nothing, and is what every desktop does.
+//
+// EXACT-MATCH COMPARISON, deliberately: the drive treats `A.txt` and `a.txt` as two files, so this
+//   must too, or uploading `a.txt` next to an existing `A.txt` would rename a file the user can
+//   see is differently named. Case-insensitive filesystems are handled at the other end — the bulk
+//   download's `freeName()` already suffixes on collision when writing to disk.
+//
+// WHERE THE TAKEN SET COMES FROM: the account's sealed file list, in memory (`namesIn`). It used
+//   to be one server listing per destination folder, decrypted name by name — which could FAIL,
+//   and a failed name check had to refuse the upload outright. That whole failure mode is gone.
+//
+// Pure: no imports at all, so `node --test` covers it directly.
+/** Where the extension starts, or -1. A leading dot is part of the name, not a separator. */
+function extIndex(filename) {
+    const dot = filename.lastIndexOf(".");
+    return dot > 0 ? dot : -1;
+}
+/**
+ * A name not present in `taken`.
+ *
+ * Returns `desired` untouched when it is free. Otherwise inserts ` (n)` before the extension,
+ * starting at 2, until it finds a free one — matching desktop behaviour so nobody has to learn a
+ * new convention. `taken` is not mutated; callers uploading several files at once must add each
+ * returned name themselves, or a batch of identical names would all resolve to the same `(2)`.
+ */
+export function uniqueFileName(desired, taken) {
+    if (!taken.has(desired))
+        return desired;
+    const dot = extIndex(desired);
+    const stem = dot === -1 ? desired : desired.slice(0, dot);
+    const ext = dot === -1 ? "" : desired.slice(dot);
+    // Bounded: an unbounded loop here would hang the upload rather than fail it. 10k duplicates of
+    // one name in one folder is far past any real use, and the timestamp fallback is still unique.
+    for (let n = 2; n < 10_000; n += 1) {
+        const candidate = `${stem} (${n})${ext}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+    return `${stem} (${new Date().toISOString().replace(/[:.]/g, "-")})${ext}`;
+}

package/dist/shared/lib/extend/epochs.js

@@ -0,0 +1,256 @@
+// The half of storage-lease reasoning that never speaks to a network: when a lease runs out, when
+// to start warning, and how much more time can still be bought. Numbers in, numbers out.
+//
+// ⛔ WHY IT IS NOT IN `chain.ts` ANY MORE. The command-line tool has to answer the same questions,
+//    and that file also imports the wallet client, which a command-line package cannot follow. So
+//    the tool had a SECOND IMPLEMENTATION of this arithmetic, and the only thing a machine compared
+//    between them was four threshold numbers. ⚠ COMPARING VALUES DOES NOT STOP TWO PROGRAMS
+//    COMPUTING DIFFERENT ANSWERS FROM THEM — and the answer here is printed on a screen where
+//    somebody decides whether to spend money. This file is now copied byte for byte into that
+//    package, so both programs run the same functions.
+//
+// ⛔ DO NOT ADD AN IMPORT HERE. The moment this file imports anything the copy cannot resolve, the
+//    copy breaks and the tool goes back to writing its own. Everything that talks to the chain
+//    belongs in `chain.ts`, which re-exports these names so callers need not know the split exists.
+//
+// ⛔ AND IT IS ENGLISH, unlike most notes in this tree: these exact bytes are published in a
+//    separate public repository, whose checks refuse Korean and refuse pointers into documents
+//    nobody outside can read.
+//
+// PURE: not even a clock — `nowMs` is always passed in. That is what lets a plain test drive the
+// branches a real network only reaches while it is changing epochs.
+/**
+ * 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 function epochDate(window, epoch) {
+    // ⚠ `== null` catches undefined as well as null. `LeaseClock.startedMs` is optional, so a
+    //    `=== null` test lets undefined through and the arithmetic produces an Invalid Date.
+    if (window.startedMs == null || !Number.isFinite(window.durationMs))
+        return null;
+    return new Date(window.startedMs + (epoch - window.current) * window.durationMs);
+}
+/**
+ * ⭐ THE ONE PIECE OF ARITHMETIC EVERY EXPIRY SURFACE STANDS ON: how long until `epoch` arrives,
+ * in ms from `nowMs`, as a RANGE.
+ *
+ * `epochDate` refuses to answer without an exact anchor (`startedMs`), and the network lives in
+ * that state most of the time — so the extend sheet said "cannot be determined" over a file whose
+ * end epoch and epoch length were both known. Not knowing exactly is not the same as knowing
+ * nothing, and drawing one as the other loses a real answer. What IS known pins the moment to one
+ * epoch's width: we are somewhere
+ * inside epoch `current` and cannot tell how far in, so `epoch` arrives between (epoch−current−1)
+ * and (epoch−current) epoch-lengths from now.
+ *
+ * ⛔ `max` — (epoch−current) whole epochs — IS THE DEFECT. It is the OPTIMISTIC edge:
+ * it silently assumes the current epoch has not started yet. On mainnet, where an epoch is
+ * fourteen days, a file was told it had 28 days left when the chain said 23 (measured 2026-08-02,
+ * 2026-08-02). Anything shown to a person about deletion takes `min` — it can only warn early,
+ * never late — and the words beside it then say "or more" / "as early as", because a floor is not
+ * a measurement.
+ *
+ * With an exact anchor both ends collapse onto one moment (`exact: true`). Null only when the
+ * epoch length itself is missing — a window `readEpochWindow` never produces.
+ */
+function epochArrival(clock, epoch, nowMs) {
+    if (!Number.isFinite(clock.durationMs) || clock.durationMs <= 0)
+        return null;
+    const ahead = epoch - clock.current;
+    const started = clock.startedMs;
+    if (started != null && Number.isFinite(started)) {
+        const at = started + ahead * clock.durationMs - nowMs;
+        return { minMs: at, maxMs: at, exact: true };
+    }
+    return {
+        minMs: (ahead - 1) * clock.durationMs,
+        maxMs: ahead * clock.durationMs,
+        exact: false,
+    };
+}
+/**
+ * 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 function epochDateBounds(clock, epoch, nowMs) {
+    const a = epochArrival(clock, epoch, nowMs);
+    if (a === null)
+        return null;
+    if (a.exact) {
+        const at = new Date(nowMs + a.minMs);
+        return { earliest: at, latest: at, exact: true };
+    }
+    return {
+        earliest: new Date(nowMs + Math.max(0, a.minMs)),
+        latest: new Date(nowMs + Math.max(0, a.maxMs)),
+        exact: false,
+    };
+}
+/**
+ * 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 const NOTICE_DAYS = 14;
+export const NOTICE_EPOCHS = 3;
+export const URGENT_DAYS = 3;
+export 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 function warningEpochs(days, floorEpochs, durationMs) {
+    const dayMs = 24 * 60 * 60 * 1000;
+    return Math.max(Math.ceil((days * dayMs) / durationMs), floorEpochs);
+}
+/**
+ * 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 function daysLeftUntilEpoch(epoch, clock, nowMs) {
+    const a = epochArrival(clock, epoch, nowMs);
+    if (a === null)
+        return null;
+    const dayMs = 24 * 60 * 60 * 1000;
+    return { days: Math.floor(a.minMs / dayMs), exact: a.exact };
+}
+/**
+ * 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 function timeLeftUntilEpoch(epoch, clock, nowMs) {
+    const a = epochArrival(clock, epoch, nowMs);
+    if (a === null)
+        return null;
+    const totalMs = Math.max(0, a.minMs);
+    const seconds = Math.floor(totalMs / 1000);
+    return {
+        days: Math.floor(seconds / 86_400),
+        hours: Math.floor(seconds / 3_600) % 24,
+        minutes: Math.floor(seconds / 60) % 60,
+        seconds: seconds % 60,
+        totalMs,
+        exact: a.exact,
+    };
+}
+/**
+ * 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 function headroom(leases, window) {
+    if (leases.length === 0)
+        return 0;
+    const furthest = Math.max(...leases.map((l) => l.endEpoch));
+    return Math.max(0, window.current + window.maxAhead - furthest);
+}
+/**
+ * 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 const EPOCH_START_VARIANTS = ["EpochChangeDone", "NextParamsSelected"];
+/**
+ * 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 function epochStartedMs(epochState) {
+    if (typeof epochState !== "object" || epochState === null)
+        return null;
+    const kind = Reflect.get(epochState, "$kind");
+    if (typeof kind !== "string" || !EPOCH_START_VARIANTS.includes(kind))
+        return null;
+    const at = Number(Reflect.get(epochState, kind));
+    // 0 is not a moment any epoch began at, and a negative one is a corrupted reading.
+    return Number.isFinite(at) && at > 0 ? at : 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 function soonestEnd(leases) {
+    if (leases.length === 0)
+        return null;
+    return Math.min(...leases.map((l) => l.endEpoch));
+}

package/dist/shared/lib/net/retry-budget.js

@@ -0,0 +1,95 @@
+// Waiting for a network to come back and repeating a failure are different things, and this is the
+// arithmetic that tells them apart. Numbers in, a decision out.
+//
+// ⛔ AND IT IS ENGLISH, unlike most notes in this tree: these exact bytes are copied into the
+//    published command-line package, so that both programs answer "have we tried hard enough" the
+//    same way. Two policies is two answers, and the one nobody looks at is the one that gives up
+//    early.
+//
+// ⛔ WHY IT EXISTS. What this product did about a dropped connection was three attempts, two and
+//    four seconds apart, on one step of one upload path; a download had two attempts a quarter of
+//    a second apart. Moving between a phone's data and a wifi network takes five to thirty
+//    seconds. So the retries were spent before the network came back, every time, and a person was
+//    handed a choice they had no way to make: resume, or give up.
+//
+// ⛔ TIME IS THE BUDGET, NOT A COUNT OF ATTEMPTS. "We tried three times" says nothing; three
+//    attempts six seconds apart is not trying. What a person means by "keep trying" is a length of
+//    time, so that is what is counted.
+//
+// ⛔ BEING OFFLINE DOES NOT SPEND THE BUDGET. There is nothing to retry while there is no network,
+//    and charging that time to the budget is how a long tunnel becomes a failed upload. Waiting
+//    for the network has its own, longer, bound — it exists so a forgotten process does not hold a
+//    file open forever, not to give up on somebody who is briefly out of range.
+//
+// ⚠ WHATEVER SAYS "ONLINE" IS A HINT AND NOTHING MORE. A browser's flag is false when there is
+//   certainly no network and true when there might be one, so it is read for the FALSE case only:
+//   the caller keeps asking the network itself, and this decides how long to wait between askings.
+//
+// PURE: no DOM, no clock of its own, no randomness of its own — every input is passed in. That is
+// what lets a test drive a tunnel, a flapping link and an exhausted budget on demand.
+/** First wait after a failure, before jitter. */
+export const RETRY_BASE_MS = 1_000;
+/**
+ * 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 const RETRY_MAX_WAIT_MS = 30_000;
+/**
+ * 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 const RETRY_BUDGET_MS = 10 * 60_000;
+/**
+ * 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 const WATCHED_RETRY_BUDGET_MS = 60_000;
+/** The matching offline bound for a watched surface. */
+export const WATCHED_OFFLINE_BUDGET_MS = 5 * 60_000;
+/** How long to go on waiting while there is no network at all. Longer, because waiting is free. */
+export const OFFLINE_BUDGET_MS = 30 * 60_000;
+/** How often to look again while offline. The `online` event is the real signal; this is the net. */
+export const OFFLINE_POLL_MS = 2_000;
+/**
+ * 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 function nextAttempt(input) {
+    if (!input.online) {
+        return {
+            again: input.elapsedOfflineMs < (input.offlineBudgetMs ?? OFFLINE_BUDGET_MS),
+            waitMs: OFFLINE_POLL_MS,
+            waitingForNetwork: true,
+        };
+    }
+    const step = Math.min(RETRY_BASE_MS * 2 ** Math.max(0, input.attempt - 1), RETRY_MAX_WAIT_MS);
+    // Jitter spreads parts that failed together: without it every part of one file wakes at the same
+    // instant and hits the same host again, which is the load that made them fail.
+    const jitter = Math.floor(clampRandom(input.random) * RETRY_BASE_MS);
+    return {
+        again: input.elapsedOnlineMs < (input.budgetMs ?? RETRY_BUDGET_MS),
+        waitMs: step + jitter,
+        waitingForNetwork: false,
+    };
+}
+/** A caller that hands over something that is not a number must not silently get a fixed wait. */
+function clampRandom(value) {
+    if (!Number.isFinite(value) || value < 0)
+        return 0;
+    return value >= 1 ? 0.999_999 : value;
+}
+/**
+ * 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 function budgetLeft(elapsedMs, waitingForNetwork) {
+    const total = waitingForNetwork ? OFFLINE_BUDGET_MS : RETRY_BUDGET_MS;
+    return Math.max(0, 1 - elapsedMs / total);
+}

package/dist/shared/lib/share/shared-file-info.js

@@ -0,0 +1,65 @@
+// What the SENDER seals beside a shared file — the plaintext the recipient opens to learn what
+// they were sent.
+//
+// It used to be the file's name and nothing else: one sealed string, opened and shown. That was
+// enough while the number the server holds was the file's own length. It stopped being enough
+// twice over:
+//   1. The stored size became the SEALED total, so the number a recipient is handed is
+//      bytes-on-the-network rather than bytes-of-the-file — larger by a fixed amount per part.
+//      A length check against it fails on any file stored in more than one piece.
+//   2. Size padding means a stored stream may be sealed from MORE bytes than the file has, so the
+//      padding can only be taken back off by somebody who knows the real length. The owner has it
+//      in their own sealed list. A recipient has nothing but what the sender sealed.
+//
+// So this is a small, EXTENSIBLE document rather than a bare string. Adding a field later costs a
+// key here and a fallback there; it does not cost a database column, a migration, or a byte the
+// server can read — which is the whole reason the size lives in here.
+//
+// ⛔ BACKWARD COMPATIBLE IN ONE DIRECTION, ON PURPOSE. Shares sealed before this document existed
+//    hold a bare name, and `decode` reads them as exactly that. A recipient running this code
+//    against an older share therefore learns the name and NOT the size — which is correct, because
+//    a file shared before padding existed has none to strip. If a padded file ever were shared by
+//    an old client still sealing bare names, the recipient would write the padding, the whole-file
+//    content hash would not match, and the download would be DISCARDED rather than saved wrong.
+//    That is the safe direction, and it is why this needed no flag day.
+//
+// ⚠ IT IS COPIED VERBATIM INTO OTHER PROGRAMS, so it depends on nothing. Two programs that seal
+//   this document must produce the same bytes: what is sealed here is hashed into the key that
+//   wraps the file's own key, so a document that differs by one character makes a share the
+//   recipient cannot open.
+/** The marker that tells a document apart from a file that happens to be named like JSON. */
+const FORMAT = "nmts-share-file/1";
+/** The string to seal as `name_share_ct`. */
+export function encodeSharedFileInfo(info) {
+    const doc = { f: FORMAT, name: info.name };
+    if (info.size !== undefined && Number.isSafeInteger(info.size) && info.size >= 0) {
+        doc.size = info.size;
+    }
+    return JSON.stringify(doc);
+}
+/**
+ * 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 function decodeSharedFileInfo(sealed) {
+    if (!sealed.startsWith("{"))
+        return { name: sealed };
+    let parsed;
+    try {
+        parsed = JSON.parse(sealed);
+    }
+    catch {
+        return { name: sealed };
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return { name: sealed };
+    const doc = parsed;
+    if (doc.f !== FORMAT || typeof doc.name !== "string")
+        return { name: sealed };
+    const size = typeof doc.size === "number" && Number.isSafeInteger(doc.size) && doc.size >= 0
+        ? doc.size
+        : undefined;
+    return size === undefined ? { name: doc.name } : { name: doc.name, size };
+}

package/dist/shared/lib/storage-network.js

@@ -0,0 +1,64 @@
+// WHICH STORAGE NETWORK a stored piece lives on — the client half of the registry. The server
+// keeps the same codes in its own item rows. NCF-3 dropped the storage-network section the old
+// format document carried, so these modules ARE the registry now.
+//
+// ⚠ THIS FILE IS PUBLISHED. It is copied byte-for-byte into the `nmts` command-line package.
+//   Keep the comments self-contained English, with no pointer only we can follow.
+//
+// WHY THIS EXISTS AT ALL: every placement field NMTS has ever written is Walrus vocabulary —
+// `blob_id`, `patch_id`, `sui_object_id`, `expiry_epoch`. Nothing said so, because until the
+// tiers were decided (BACKLOG §2.2) "the storage network" and "Walrus" were the same thing. A
+// blob id is only meaningful on the network that issued it, so a recovery tool holding one and
+// no network name has to guess which aggregator to ask.
+//
+// TWO SPELLINGS, ONE MEANING — and the split is deliberate:
+//   · NUMBER (0/1/2) in the database and in the sealed FILE LIST (NMF-1), where every byte is
+//     rewritten on each save and repeated across thousands of entries.
+//   · NAME ("walrus") in the RECOVERY MAP (NRM-2), which a standalone tool parses years from now
+//     with none of our code beside it. A magic number in that document is a trap; a word is not.
+// This mirrors the existing `kind` field, which is `1` in the file list and `"file"` in the map.
+//
+// ⚠ NOT A TIER MAPPING. 「NMTS Fast」/「NMTS Heavy」 are product names for what the person buys;
+// these are the networks underneath. The screen keeps its own mapping (components/drive/
+// StorageTier.tsx) so a rename of either never silently redefines the other.
+//
+// FAILURE MODES: none at runtime — pure functions over constants. An UNKNOWN code answers `null`
+// rather than falling back to Walrus: a wrong network recorded in a recovery map is unfixable
+// years later, so callers are made to decide what to do about it.
+/** Network codes, as stored. Fixed forever once a row carries one. */
+export const NETWORK_WALRUS = 0;
+/** Filecoin — product tier 「NMTS Heavy」. Reserved; no upload path exists yet. */
+export const NETWORK_FILECOIN = 1;
+/** Arweave — reserved and deliberately last: it cannot be deleted, ever (BACKLOG §2.2). */
+export const NETWORK_ARWEAVE = 2;
+const BY_CODE = {
+    [NETWORK_WALRUS]: "walrus",
+    [NETWORK_FILECOIN]: "filecoin",
+    [NETWORK_ARWEAVE]: "arweave",
+};
+const BY_NAME = {
+    walrus: NETWORK_WALRUS,
+    filecoin: NETWORK_FILECOIN,
+    arweave: NETWORK_ARWEAVE,
+};
+/**
+ * Code → the name a recovery map stores. `null` for a code this build has never heard of.
+ *
+ * A newer client could store a network this one predates. Returning null makes that visible to
+ * the caller instead of mislabelling someone's bytes.
+ */
+export function networkName(code) {
+    return BY_CODE[code] ?? null;
+}
+/** Name → code. `null` for anything not in the registry. */
+export function networkCode(name) {
+    return BY_NAME[name] ?? null;
+}
+/**
+ * What an ABSENT network field means: Walrus.
+ *
+ * This is a fact, not a fallback. No other network has ever had an upload path, so every part,
+ * entry and map written before the field existed is on Walrus by construction. Stated as a named
+ * constant so the reasoning sits next to every use of it rather than being re-derived.
+ */
+export const NETWORK_WHEN_UNRECORDED = NETWORK_WALRUS;

package/dist/shared/lib/upload/part-plan.js

@@ -0,0 +1,28 @@
+/**
+ * Split a plaintext length into ordered, contiguous, non-overlapping ranges of at most
+ * `partSizeBytes` each; the last one carries the remainder.
+ *
+ * The ranges tile `[0, plaintextLen)` exactly — the lengths sum to `plaintextLen` — and a file that
+ * fits in one part is simply the one-range case, so a caller never needs a separate path for it.
+ *
+ * Throws on a non-positive length or part size rather than coercing: both are caller mistakes, and
+ * a silently corrected one would produce a plan that does not describe the file.
+ */
+export function planParts(plaintextLen, partSizeBytes) {
+    if (!Number.isFinite(plaintextLen) || plaintextLen <= 0) {
+        throw new RangeError(`planParts needs a positive plaintextLen, got ${String(plaintextLen)}`);
+    }
+    if (!Number.isFinite(partSizeBytes) || partSizeBytes <= 0) {
+        throw new RangeError(`planParts needs a positive partSizeBytes, got ${String(partSizeBytes)}`);
+    }
+    const ranges = [];
+    let offset = 0;
+    let partIndex = 0;
+    while (offset < plaintextLen) {
+        const length = Math.min(partSizeBytes, plaintextLen - offset);
+        ranges.push({ partIndex, offset, length });
+        offset += length;
+        partIndex += 1;
+    }
+    return ranges;
+}