@needmoretruth/nmts-cli 0.17.2

package/dist/upload-store.js

@@ -0,0 +1,252 @@
+// Where an unfinished PAID upload waits.
+//
+// ⛔ THIS FILE EXISTS BECAUSE THE CREDITS MOVE BEFORE THE BYTES DO. `POST /v1/sponsored/reserve`
+//    spends the account's credits and buys storage on the network; only after that do the bytes
+//    go to the relay. A process that dies in between has bought storage it never filled, and a
+//    plain retry would buy a second lot. What makes the retry free instead is sending the SAME
+//    idempotency key with the SAME blob — and the blob id is a function of the sealed bytes and a
+//    random tip nonce, neither of which can be re-derived once they are gone.
+//
+//    So they are written down BEFORE the money moves. That ordering is the whole design.
+//
+// ⛔ WHAT IS ON DISK IS ALREADY PUBLIC. The `.bin` is the sealed NCF-3 stream — the exact bytes
+//    about to be handed to a public storage network. It is still written 0600, because "already
+//    public" is about the CONTENT and the file's presence would otherwise say which files this
+//    account uploaded and when.
+//
+// ⛔ THE FILE NAME IS NOT A CONTENT FINGERPRINT. Keying by SHA-256 of the plaintext would leave a
+//    directory of hashes matchable against published hash sets — the very thing sealing the
+//    content hash avoids. The key mixes the account's data key in, so it identifies the file only
+//    to somebody who already holds the account.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir, modesAreEnforced } from "./credentials.js";
+import { chmodSync } from "node:fs";
+import { NmtsError } from "./errors.js";
+/** Where unfinished uploads live. */
+export function uploadsDir() {
+    return join(configDir(), "uploads");
+}
+/**
+ * A stable, account-scoped name for one file's upload attempt.
+ *
+ * Same account, same bytes, same destination give the same key — which is what lets a second `put`
+ * of a file whose first attempt died find the reservation instead of paying again.
+ *
+ * ⛔ THE DESTINATION IS PART OF IT, and leaving it out was a real defect. Two local files with
+ *    identical content — a copy, a re-download, `a.bin` and `backup/a.bin` — would otherwise share
+ *    one reservation, and putting the second one would silently resume the first: it would report
+ *    success, spend nothing, and write a SECOND file-list entry pointing at the FIRST file's item.
+ *    Deleting either would then break the other. They are two files in the drive, so they are two
+ *    uploads.
+ *
+ * ⚠ It is the destination AS TYPED, not the folder id, because the id needs a network round trip
+ *   and this key is wanted before one. Two spellings of one folder therefore make two reservations
+ *   — one extra unfinished record, never a wrong file.
+ */
+export function reservationKey(dataKey, plaintext, name, destination) {
+    return reservationKeyStreamed(dataKey, [plaintext], name, destination);
+}
+/**
+ * The same key, computed without ever holding the file.
+ *
+ * ⛔ IT MUST HASH THE IDENTICAL BYTE SEQUENCE. A file large enough to need several parts is a file
+ *    too large to hand `reservationKey` as one array, and a second construction here — hashing a
+ *    hash, hashing the parts' digests — would give the same file two different keys depending on
+ *    how it was read. The one above is written in terms of this one so there is only ever one
+ *    answer, and a test feeds the same file both ways to hold that.
+ */
+export function reservationKeyStreamed(dataKey, plaintextChunks, name, destination) {
+    const hash = startReservationKey(dataKey);
+    for (const chunk of plaintextChunks)
+        hash.update(chunk);
+    return finishReservationKey(hash, name, destination);
+}
+/**
+ * Begin the hash a reservation key is made from.
+ *
+ * ⛔ TWO HASHES, ONE READ. A file large enough to need parts is read once to work out its key AND
+ *    the SHA-256 the account checks its contents against; handing the caller the running hash is
+ *    what lets both come out of a single pass instead of two reads of a very large file.
+ */
+export function startReservationKey(dataKey) {
+    return createHash("sha256").update(dataKey);
+}
+/** Finish it. The name and the destination go in last, exactly as the one-shot form does. */
+export function finishReservationKey(hash, name, destination) {
+    const digest = hash.update(new TextEncoder().encode(`\u0000${name}\u0000${destination}`)).digest();
+    return Buffer.from(digest).toString("base64url").slice(0, 32);
+}
+/**
+ * The record name for ONE part of a file.
+ *
+ * ⛔ EVERY PART IS ITS OWN RESERVATION. Each one buys its own storage, under its own idempotency
+ *    key, and can fail or resume on its own — so each one is written down on its own. Sharing a
+ *    record between parts would mean a run that died between part 3 and part 4 could not say which
+ *    of them the credits had already been spent on.
+ */
+export function partKey(fileKey, partIndex) {
+    return `${fileKey}~p${partIndex}`;
+}
+function paths(key) {
+    const dir = uploadsDir();
+    return { json: join(dir, `${key}.json`), bin: join(dir, `${key}.bin`) };
+}
+function isReservation(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    for (const name of ["blobId", "nonceB64", "rootHashB64", "relayUrl", "dekWrapped", "contentHashCt", "name"]) {
+        if (typeof Reflect.get(value, name) !== "string")
+            return false;
+    }
+    for (const name of ["epochs", "sealedLen", "plaintextLen", "partPlaintextLen", "partIndex", "partTotal", "attempt"]) {
+        if (typeof Reflect.get(value, name) !== "number")
+            return false;
+    }
+    const parent = Reflect.get(value, "parentId");
+    return parent === null || typeof parent === "string";
+}
+/**
+ * The waiting reservation's RECORD, without its sealed bytes.
+ *
+ * ⛔ THE BYTES ARE THE FILE. Reading them to answer "has this part been paid for?" would mean a
+ *    resume that only needs to commit still reads every byte of a very large upload off the disk.
+ *    They are fetched separately, by the one step that actually pushes them.
+ */
+export function readReservationRecord(key) {
+    const { json, bin } = paths(key);
+    if (!existsSync(json) || !existsSync(bin))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(json, "utf8"));
+    }
+    catch {
+        // ⛔ Unreadable is not the same as absent, and treating it as absent would buy storage twice.
+        throw new NmtsError(`An unfinished upload record at ${json} could not be read.`, {
+            nextStep: "It names storage this account may already have paid for. Move it aside rather than " +
+                "deleting it if the upload matters, then try again.",
+        });
+    }
+    if (!isReservation(parsed)) {
+        throw new NmtsError(`The unfinished upload record at ${json} is not in a shape this version knows.`, {
+            nextStep: "Move it aside and try again. Nothing was sent.",
+        });
+    }
+    return parsed;
+}
+/**
+ * The sealed bytes a reservation bought.
+ *
+ * ⛔ NEVER RE-SEALED ONES. Sealing is non-deterministic, so bytes produced by a later run are a
+ *    different blob from the one the treasury registered — the relay refuses them, forever, and
+ *    the credits are gone.
+ */
+export function readReservationBytes(key) {
+    const { bin } = paths(key);
+    return new Uint8Array(readFileSync(bin));
+}
+/** The record and its bytes together, for the callers that need both. */
+export function readReservation(key) {
+    const record = readReservationRecord(key);
+    if (record === null)
+        return null;
+    return { record, sealed: readReservationBytes(key) };
+}
+/** Write the record and its sealed bytes. Called BEFORE the reserve, and again after it answers. */
+export function writeReservation(key, record, sealed) {
+    const dir = uploadsDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (modesAreEnforced())
+        chmodSync(dir, 0o700);
+    const { json, bin } = paths(key);
+    // ⛔ WRITTEN ASIDE AND RENAMED OVER, never truncated in place. A rename within one directory is
+    //    atomic, so a reader sees the old record or the new one and never a half-written one. The
+    //    write that matters is the LAST one — the one that adds the item id — because a truncated
+    //    file there is the only local pointer to a file that is already paid for and committed, and
+    //    losing it makes that file invisible.
+    atomically(bin, sealed);
+    atomically(json, Buffer.from(`${JSON.stringify(record, null, 2)}\n`, "utf8"));
+}
+function atomically(target, bytes) {
+    const scratch = `${target}.${process.pid}.tmp`;
+    writeFileSync(scratch, bytes, { mode: 0o600 });
+    if (modesAreEnforced())
+        chmodSync(scratch, 0o600);
+    renameSync(scratch, target);
+}
+/**
+ * Forget a reservation.
+ *
+ * ⚠ Called on success AND on a couple of failure paths, so the comment that used to say "the
+ *   upload already succeeded" was not true of every caller. What IS true of all of them is that
+ *   nothing further depends on the record, which is why it never throws.
+ */
+export function clearReservation(key) {
+    const { json, bin } = paths(key);
+    for (const path of [json, bin]) {
+        try {
+            rmSync(path, { force: true });
+        }
+        catch {
+            // ⚠ A record that cannot be removed is left where it is. That is not free -- a record
+            //   carrying an item id is READ before anything is written, so a stale one would be
+            //   resumed rather than overwritten. It is still better than failing a finished upload
+            //   over a file that could not be deleted.
+        }
+    }
+}
+function itemPath(fileKey) {
+    return join(uploadsDir(), `${fileKey}.item.json`);
+}
+function isItemRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (typeof Reflect.get(value, "attempt") !== "number")
+        return false;
+    const id = Reflect.get(value, "itemId");
+    return id === undefined || typeof id === "string";
+}
+/** What is known about this file's commit, or `null` when it has not been attempted. */
+export function readItemRecord(fileKey) {
+    const path = itemPath(fileKey);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        // ⛔ Same reasoning as an unreadable reservation: unreadable is not absent. This file is the
+        //    only local pointer to storage that is already bought and possibly already committed.
+        throw new NmtsError(`An unfinished upload record at ${path} could not be read.`, {
+            nextStep: "It names a file this account may already have paid for. Move it aside rather than " +
+                "deleting it if the upload matters, then try again.",
+        });
+    }
+    if (!isItemRecord(parsed)) {
+        throw new NmtsError(`The unfinished upload record at ${path} is not in a shape this version knows.`, {
+            nextStep: "Move it aside and try again. Nothing was sent.",
+        });
+    }
+    return parsed;
+}
+/** Write the file-level record. Called before the commit, and again once it has an id. */
+export function writeItemRecord(fileKey, record) {
+    const dir = uploadsDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (modesAreEnforced())
+        chmodSync(dir, 0o700);
+    atomically(itemPath(fileKey), Buffer.from(`${JSON.stringify(record, null, 2)}\n`, "utf8"));
+}
+/** Forget the file-level record. Never throws, for the same reason `clearReservation` does not. */
+export function clearItemRecord(fileKey) {
+    try {
+        rmSync(itemPath(fileKey), { force: true });
+    }
+    catch {
+        // ⚠ Left where it is. A stale one carrying an item id would be resumed rather than
+        //   overwritten, which is still better than failing a finished upload over a stuck file.
+    }
+}

package/dist/upload-wire.js

@@ -0,0 +1,25 @@
+// The shapes the credit-paid upload speaks in — the storage-network protocol, the api calls, and
+// what a failure is allowed to claim about money.
+//
+// ⛔ SEPARATE FROM THE MACHINE ON PURPOSE. `upload.ts` is a sequence of decisions about spending;
+//    keeping the vocabulary here means a test can name every seam without importing that sequence,
+//    and means the file that DOES spend stays short enough to read in one sitting.
+import { NmtsError } from "./errors.js";
+/**
+ * A failure that names its phase — and, crucially, whether the account has already paid.
+ *
+ * ⛔ `paid` IS NOT COSMETIC. Before the reserve, a failure costs nothing and "try again" is honest
+ *    advice. After it, the credits are gone and the storage exists; the honest advice is that the
+ *    same command will FINISH it rather than buy it again, and that saying otherwise would send
+ *    somebody to spend twice.
+ */
+export class UploadError extends NmtsError {
+    phase;
+    paid;
+    constructor(input) {
+        super(input.message, { exitCode: 1, nextStep: input.nextStep ?? null });
+        this.name = "UploadError";
+        this.phase = input.phase;
+        this.paid = input.paid;
+    }
+}

package/dist/upload.js

@@ -0,0 +1,294 @@
+// The credit-paid upload, end to end, for ONE file.
+//
+// ⛔ THIS IS THE ONLY PATH IN THIS TOOL THAT SPENDS. Everything else reads. The order of the steps
+//    below is not a style choice — it is what stands between an interruption and money that bought
+//    nothing:
+//
+//      seal → encode → WRITE IT DOWN → reserve (credits move here) → write it down again
+//           → relay → certify        … once per part …
+//      → commit the file (every part named at once) → write the file list → forget the records
+//
+//    The two writes bracket the spend. Before it, so a retry has the sealed bytes and the tip
+//    nonce that reproduce the blob the reservation bought. After it, so the transaction the relay
+//    checks its tip in is not lost with the process.
+//
+// ⛔ A RESUME READS THE RECORD AND NOT THE CALLER. Sealing is non-deterministic, so a run that
+//    re-sealed and then resumed would push bytes that are not the blob the treasury registered —
+//    the relay refuses them, forever, and the credits are gone. Everything the reservation bought
+//    is a function of ONE PARTICULAR SEALING of the file: the blob id, the wrapped file key, the
+//    content hash, the relay that was tipped. All of it comes back out of the record.
+//
+// ⛔ NO WALLET IS TOUCHED AND NOTHING IS SIGNED HERE. The treasury pays for the storage against
+//    credits the account already holds; this tool encodes bytes, asks the server to buy, pushes
+//    the bytes at the relay and reports what the storage nodes signed. There is no signer in this
+//    file and no transaction is built.
+//
+// ⛔ EVERY SEAM IS INJECTED. The storage-network protocol and the api are interfaces, so the tests
+//    drive the real decisions — including every failure branch — without a network and without
+//    spending anything. The seams themselves are in `upload-wire.ts`.
+import { NmtsError } from "./errors.js";
+import { ServerError } from "./api.js";
+import { readReservationBytes, readReservationRecord, writeReservation, } from "./upload-store.js";
+import { pushPart } from "./upload-steps.js";
+import { UploadError, } from "./upload-wire.js";
+export * from "./upload-wire.js";
+/** A reservation state that can still become storage. Anything else is dead. */
+function isLive(state) {
+    return state === "registered" || state === "certified";
+}
+function why(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Buy storage for ONE PART, put its bytes on the network, and stop there.
+ *
+ * ⛔ IT DOES NOT MAKE A FILE. Committing is one act for the whole file — `commitItem` names every
+ *    part at once — and a part that returns from here is bought, filled and certified storage that
+ *    nothing in the account can see yet. Splitting it this way is what lets a file be larger than
+ *    memory: the parts are bought one at a time, each written down before its own money moves.
+ *
+ * ⛔ IT DOES NOT WRITE THE FILE LIST either. That is the caller's step, and it must happen before
+ *    the records are cleared — a committed file the list does not name is invisible and, to the
+ *    person, indistinguishable from one that never uploaded.
+ */
+export async function buyAndPushPart(input) {
+    const { api, protocol, key, sealed, onStep } = input;
+    const existing = readReservationRecord(key);
+    // ⛔ THE STORED PLACEMENT WINS THE ARGUMENT, AND A DISAGREEMENT STOPS THE RUN. The bytes on disk
+    //    were sealed as part i of n and paid for as that; pushing them while this run believes the
+    //    file splits some other way would file storage under the wrong position in the file. It
+    //    happens for one ordinary reason — the same file put again with a different part size — so
+    //    it is said plainly rather than left to fail later as an unreadable download.
+    if (existing !== null) {
+        const record = existing;
+        if (record.partIndex !== input.part.index || record.partTotal !== input.part.total) {
+            throw new UploadError({
+                phase: "reserve",
+                message: `This upload was started as part ${record.partIndex + 1} of ${record.partTotal} and this ` +
+                    `run is treating it as part ${input.part.index + 1} of ${input.part.total}.`,
+                paid: record.ledgerId !== undefined,
+                nextStep: "Run it again with the part size the first attempt used, or move the records in the " +
+                    "uploads directory aside to start over. Nothing was sent.",
+            });
+        }
+    }
+    // ── the credits already moved: ask where the reservation stands before doing anything ──
+    if (existing?.ledgerId !== undefined) {
+        const record = existing;
+        const ledgerId = record.ledgerId;
+        if (ledgerId === undefined)
+            throw new NmtsError("unreachable: a record with no ledger id");
+        let status;
+        try {
+            status = await api.status(ledgerId);
+        }
+        catch (error) {
+            throw new UploadError({
+                phase: "reserve",
+                message: `Could not ask about the paid reservation ${ledgerId}: ${why(error)}`,
+                paid: true,
+                nextStep: "Nothing more was spent. The storage this account paid for is still bought — run the " +
+                    "same command again when the server answers.",
+            });
+        }
+        onStep?.({ step: "resuming", ledgerId, state: status.state });
+        if (status.state === "certified") {
+            return paidPart(record, ledgerId, true);
+        }
+        if (!isLive(status.state)) {
+            // ⛔ THE RECORD IS KEPT AND ITS ATTEMPT NUMBER GOES UP. Deleting it looks tidier and is the
+            //    trap: the idempotency key is derived from a key that is a pure function of the account,
+            //    the bytes and the destination, and the server replays a reservation row under its key
+            //    whatever state it is in — `failed` included. A cleared record means the next run
+            //    rebuilds the same key, is handed the same dead row, and is told to start over into it.
+            //    Forever. Counting up is what starting over actually means.
+            writeReservation(key, { ...stripReservation(record), attempt: record.attempt + 1 }, readReservationBytes(key));
+            throw new UploadError({
+                phase: "reserve",
+                message: `The credit reservation for this file ended as "${status.state}" and cannot be used.`,
+                paid: true,
+                nextStep: "Running the same command again asks for a NEW reservation, which will spend credits. " +
+                    "Nothing was uploaded under the one that failed.",
+            });
+        }
+        if (!status.register_tx_digest || !status.blob_object_id) {
+            throw new UploadError({
+                phase: "reserve",
+                message: `Reservation ${ledgerId} is registered but the server did not say which blob it bought.`,
+                paid: true,
+                nextStep: "Nothing was uploaded and nothing more was spent.",
+            });
+        }
+        await pushPart(input, {
+            ledgerId,
+            blobId: record.blobId,
+            nonce: Buffer.from(record.nonceB64, "base64url"),
+            registerTxDigest: status.register_tx_digest,
+            blobObjectId: status.blob_object_id,
+            // ⛔ THE STORED BYTES AND THE STORED RELAY. Not the caller's — see the module header.
+            //    Read here, and only here: a part that came back certified never needs them at all.
+            sealed: readReservationBytes(key),
+            relayUrl: record.relayUrl,
+        });
+        return paidPart(record, ledgerId, true);
+    }
+    // ── fresh, or interrupted before the money moved ──
+    onStep?.({ step: "encoding", bytes: sealed.length });
+    let meta;
+    try {
+        meta = await protocol.computeMetadata({
+            bytes: sealed,
+            // Re-feeding a stored nonce is what makes the retry reproduce the digest a paid tip was
+            // computed for. A fresh random one would strand the reservation.
+            nonce: existing ? new Uint8Array(Buffer.from(existing.nonceB64, "base64url")) : undefined,
+        });
+    }
+    catch (error) {
+        throw new UploadError({
+            phase: "encoding",
+            message: `Could not prepare this file for the storage network: ${why(error)}`,
+            paid: false,
+            nextStep: "Nothing was sent and nothing was spent.",
+        });
+    }
+    const nonceB64 = Buffer.from(meta.nonce).toString("base64url");
+    const record = {
+        // ⛔ The attempt number is CARRIED FORWARD, not reset. A record that survives a dead
+        //    reservation is exactly the case that needs a different idempotency key.
+        attempt: existing?.attempt ?? 0,
+        blobId: meta.blobId,
+        nonceB64,
+        rootHashB64: Buffer.from(meta.rootHash).toString("base64url"),
+        relayUrl: input.relayUrl,
+        epochs: input.epochs,
+        sealedLen: sealed.length,
+        plaintextLen: input.entry.plaintextLen,
+        partPlaintextLen: input.part.plaintextLen,
+        partIndex: input.part.index,
+        partTotal: input.part.total,
+        dekWrapped: input.entry.dekWrapped,
+        contentHashCt: input.entry.contentHashCt,
+        name: input.entry.name,
+        parentId: input.entry.parentId,
+    };
+    // ⛔ BEFORE THE MONEY. See the module header.
+    writeReservation(key, record, sealed);
+    onStep?.({ step: "reserving" });
+    let reply;
+    try {
+        reply = await api.reserve({
+            idempotency_key: idempotencyKey(key, record.attempt),
+            blob_id: meta.blobId,
+            root_hash_b64: record.rootHashB64,
+            // One number, measured: what the treasury is asked to buy and what the credits are charged
+            // on are the same sealed bytes.
+            size: sealed.length,
+            epochs: input.epochs,
+            relay: {
+                host: input.relayUrl,
+                blob_digest_b64: Buffer.from(meta.blobDigest).toString("base64url"),
+                nonce_b64: nonceB64,
+            },
+        });
+    }
+    catch (error) {
+        throw new UploadError({
+            phase: "reserve",
+            message: why(error),
+            // ⛔ A refusal did not spend. A request that never got an answer MIGHT have — and the record
+            //    is on disk either way, so the next run asks the server instead of guessing here.
+            paid: false,
+            nextStep: error instanceof ServerError
+                ? "Nothing was uploaded. No credits were spent on a refused reservation."
+                : "If the request reached the server, credits may have been spent — running the same " +
+                    "command again finds that reservation rather than making a second one.",
+        });
+    }
+    if (!isLive(reply.state)) {
+        // Same reason as the resumed branch above: keep the record, count up, so the next run does not
+        // ask under a key the server has already settled.
+        writeReservation(key, { ...stripReservation(record), attempt: record.attempt + 1 }, sealed);
+        throw new UploadError({
+            phase: "reserve",
+            message: `The reservation came back as "${reply.state}", which cannot become storage.`,
+            paid: reply.credits_spent > 0,
+            nextStep: "Nothing was uploaded.",
+        });
+    }
+    record.ledgerId = reply.ledger_id;
+    if (reply.register_tx_digest)
+        record.registerTxDigest = reply.register_tx_digest;
+    if (reply.blob_object_id)
+        record.blobObjectId = reply.blob_object_id;
+    writeReservation(key, record, sealed);
+    if (reply.state === "certified") {
+        return paidPart(record, reply.ledger_id, false);
+    }
+    if (!reply.register_tx_digest || !reply.blob_object_id) {
+        throw new UploadError({
+            phase: "reserve",
+            message: "The storage was bought but the reply did not say which blob it bought.",
+            paid: true,
+            nextStep: "Nothing was uploaded. Running the same command again asks the server again.",
+        });
+    }
+    await pushPart(input, {
+        ledgerId: reply.ledger_id,
+        blobId: meta.blobId,
+        nonce: meta.nonce,
+        registerTxDigest: reply.register_tx_digest,
+        blobObjectId: reply.blob_object_id,
+        sealed,
+        relayUrl: input.relayUrl,
+    });
+    return paidPart(record, reply.ledger_id, false);
+}
+/**
+ * What the commit needs about a finished part — read off the RECORD, never off the run.
+ *
+ * ⛔ THE SAME REASON THE FILE LIST ENTRY COMES FROM THE RECORD. What is stored on the network is
+ *    one particular sealing; a resumed run that named its own freshly computed blob id or length
+ *    would commit a part that does not exist.
+ */
+function paidPart(record, ledgerId, resumed) {
+    return {
+        partIndex: record.partIndex,
+        ledgerId,
+        blobId: record.blobId,
+        sealedLen: record.sealedLen,
+        resumed,
+    };
+}
+/**
+ * The idempotency key for one attempt at one file.
+ *
+ * ⛔ THE ATTEMPT NUMBER IS IN IT. Without it the key is a pure function of the account, the bytes
+ *    and the destination — and the server replays whatever row it has under a key, including a
+ *    settled one that can never become storage.
+ */
+function idempotencyKey(key, attempt) {
+    return `nmts-cli-${key}-${attempt}`;
+}
+/** What the file list must record about this upload. Always from the record, never from a run. */
+export function entryOf(record) {
+    return {
+        name: record.name,
+        parentId: record.parentId,
+        plaintextLen: record.plaintextLen,
+        dekWrapped: record.dekWrapped,
+        contentHashCt: record.contentHashCt,
+    };
+}
+/**
+ * The record with everything the dead reservation put on it removed.
+ *
+ * ⛔ Explicit, not `delete`: a field left behind here is a resumed run believing it holds a
+ *    transaction the relay will accept, and the failure would arrive after the money moved.
+ */
+function stripReservation(record) {
+    const { ledgerId, registerTxDigest, blobObjectId, ...rest } = record;
+    void ledgerId;
+    void registerTxDigest;
+    void blobObjectId;
+    return rest;
+}

package/dist/usage-report.js

@@ -0,0 +1,54 @@
+// What an account is holding, worked out from the decrypted list and nothing else.
+//
+// ⛔ EVERY NUMBER IS EXACT, NOT ESTIMATED. The sealed list IS the drive — it is what every device
+//    reads to know what exists — so counting it is counting the account. Nothing here samples,
+//    rounds or asks the server: the server holds sizes and times, and the names and the tree it
+//    cannot read at all, so "how many folders do I have" has no server-side answer to fetch.
+//
+// ⛔ THE TRASH IS COUNTED SEPARATELY AND KEPT OUT OF THE TOTAL. The two figures answer different
+//    questions: the total is what the drive holds, and the trash figure is what is still stored
+//    and still paid for while being no longer in the drive. Folding them together would tell
+//    somebody who just deleted 4 GB that nothing changed; leaving the trash out silently would
+//    tell them the 4 GB is gone when the storage is still bought. It is the same split the account
+//    screen in a browser shows, and for the same reason.
+//
+// ⚠ IT COUNTS PLAINTEXT BYTES — what the files hold. What the storage network holds for the
+//   account is larger: sealing adds bytes to every file, and storage is bought in fixed units.
+//   This is not a bill, and nothing here should be printed as one.
+import { fullPathOf, isLive, KIND_FILE } from "./drive-paths.js";
+import { totalsOf } from "./shared/lib/drive/manifest-index.js";
+/** How many of the largest files a report carries. */
+export const BIGGEST_SHOWN = 5;
+/**
+ * The whole report, in one pass over the list.
+ *
+ * The counts come from the same `totalsOf` the browser's own usage figures are built on — this
+ * package carries that module as a byte-for-byte copy — so the two cannot drift into disagreeing
+ * about what "in the trash" means. Being in the trash is INHERITED: a file under a trashed folder
+ * is trashed even though nothing marked the file itself, and a count that read only the file's own
+ * mark would report bytes as live that the server has already stopped serving.
+ */
+export function computeUsage(index) {
+    const totals = totalsOf(index);
+    const biggest = index.all
+        .filter((entry) => entry.kind === KIND_FILE && isLive(index, entry))
+        // Largest first, ties broken by name — so two runs over one unchanged list name the same
+        // files in the same order instead of reshuffling whatever the list order happened to be.
+        .slice()
+        .sort((a, b) => b.size - a.size || a.name.localeCompare(b.name))
+        .slice(0, BIGGEST_SHOWN)
+        .map((entry) => ({
+        id: entry.id,
+        name: entry.name,
+        path: fullPathOf(index, entry),
+        size: entry.size,
+    }));
+    return {
+        files: totals.files,
+        folders: totals.folders,
+        bytes: totals.bytes,
+        trashedFiles: totals.trashedFiles,
+        trashedBytes: totals.trashedBytes,
+        biggest,
+    };
+}