@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/shared/lib/drive/manifest-chunks.js

@@ -0,0 +1,252 @@
+// The CHUNKED file list — NCF-3 §6.3, format version 2.
+// ⚠ PUBLISHED — copied byte-for-byte into the `nmts` command-line package; keep comments
+// self-contained English.
+//
+// The index stays where the single sealed list was; the entries move into immutable chunks of at
+// most 4 MiB sealed bytes, each named by the hash of its transport string, so an edit rewrites one
+// chunk and the index instead of the whole list. This module is ONLY the byte format — entries ⇄
+// the plaintext that gets sealed, for both halves. It performs no I/O, holds no key and never
+// touches the network, exactly like `manifest-codec.ts` beside it, and for the same reason: the
+// format has to be unit-testable without a browser and written down in one place.
+//
+// WHY TWO LABELS. The index and a chunk are the same shape of bytes to the server, so a chunk
+//   handed back where an index was asked for has to fail at the AEAD rather than at the parser.
+//   That is what `AAD_FILE_LIST_CHUNK` buys, and it is the whole reason the constant exists.
+//
+// WHAT THE INDEX PINS. The index is authenticated (envelope), continued (`p`), and it names every
+//   chunk by hash. A server that swaps, drops, duplicates or rolls a chunk back produces bytes
+//   whose hash is not the one the index named. So every check §6.1 makes on the one blob now
+//   covers the whole list — see `manifest-chunk-flow.ts`, which is where the checking happens.
+import { decodeManifest, FLAG_GZIP, FLAG_RAW, fromWire, gunzip, gzip, manifestFingerprint, ManifestFormatError, toWire, withFlag, } from "./manifest-codec.js";
+import { settingsFromWire, settingsToWire } from "./manifest-settings.js";
+import { zstdCodec, zstdContentSize, ZSTD_LEVEL } from "./zstd.js";
+/**
+ * Envelope AAD for ONE CHUNK of the chunked file list (NCF-3 §2, §6.3). Its own label, distinct
+ * from `AAD_FILE_LIST`, so a chunk can never be presented as an index or an index as a chunk —
+ * the server holds both as opaque bytes of the same shape.
+ */
+export const AAD_FILE_LIST_CHUNK = "nmts/v3/file-list-chunk";
+/** The version an index and its chunks carry. Version 1 is the single blob `manifest-codec` reads. */
+export const FILE_LIST_VERSION_CHUNKED = 2;
+/** Compression flag 0x02 — zstd (NCF-3 §6.3.4). 0x00 and 0x01 are `manifest-codec`'s. */
+export const FLAG_ZSTD = 0x02;
+/**
+ * The plaintext bound for ONE CHUNK (NCF-3 §6.3.3).
+ *
+ * On the PLAINTEXT and not on the sealed size, so a writer can decide where to close a chunk
+ * before it compresses or seals anything: 3,900,000 bytes plus the flag byte plus the 72-byte
+ * envelope is under the server's 4 MiB ceiling by construction, and a compressed chunk is smaller
+ * still. The unused remainder is left unused — an entry is never split across two chunks.
+ */
+export const CHUNK_PLAIN_MAX = 3_900_000;
+/**
+ * The plaintext bound for the INDEX.
+ *
+ * The index sits where the single blob sat, so it inherits that ceiling (16 MiB sealed · §8.291).
+ * It holds one ~110-byte row per chunk plus the account settings, so nothing an account can do
+ * brings it near this; the number exists so a reader has a bound to check a compressed frame
+ * against instead of trusting what the frame claims about itself.
+ */
+export const INDEX_PLAIN_MAX = 15_000_000;
+/**
+ * A chunk's name. The SAME function the parent link uses, deliberately: both commit to the
+ * base64url transport string rather than the bytes it encodes, because the string is what travels
+ * and the encoding is canonical (fixed alphabet, no padding, one string per byte sequence).
+ */
+export const chunkFingerprint = manifestFingerprint;
+// ------------------------------------------------------------------------------ compression
+/**
+ * JSON → the plaintext to seal: `flag || payload` (NCF-3 §6.3.4).
+ *
+ * zstd when this build has an encoder, the platform's gzip when it does not, raw when it has
+ * neither. All three are readable by every version-2 reader, so the choice costs nobody anything.
+ */
+async function pack(json) {
+    const codec = zstdCodec();
+    if (codec) {
+        try {
+            return withFlag(FLAG_ZSTD, await codec.compress(json, ZSTD_LEVEL));
+        }
+        catch {
+            // An encoder that will not run must not cost somebody their save: gzip below writes a
+            // document every reader can open, and the only thing lost is ~9 % of the bytes.
+        }
+    }
+    const gz = await gzip(json);
+    return gz ? withFlag(FLAG_GZIP, gz) : withFlag(FLAG_RAW, json);
+}
+/**
+ * The sealed plaintext → the JSON bytes inside it.
+ *
+ * `maxOut` is the caller's bound (a chunk's or the index's). A zstd frame declares what it expands
+ * to, so a frame that claims more than the bound is refused HERE — before anything is allocated
+ * for it. Every refusal is a `ManifestFormatError` that says which one it was; none of them is
+ * ever an empty drive (§6.1's rule).
+ */
+async function unpack(body, maxOut) {
+    if (body.length < 1)
+        throw new ManifestFormatError("empty file list body");
+    const flag = body[0];
+    const rest = body.subarray(1);
+    if (flag === FLAG_RAW)
+        return rest;
+    if (flag === FLAG_GZIP) {
+        const out = await gunzip(rest);
+        if (!out)
+            throw new ManifestFormatError("the file list is gzipped and this platform cannot expand it");
+        return out;
+    }
+    if (flag === FLAG_ZSTD) {
+        const codec = zstdCodec();
+        if (!codec) {
+            throw new ManifestFormatError("the file list is zstd-compressed and this build has no zstd decoder");
+        }
+        const declared = zstdContentSize(rest);
+        if (declared === null) {
+            throw new ManifestFormatError("the zstd frame does not declare its size, so it cannot be bounded");
+        }
+        if (declared > maxOut) {
+            throw new ManifestFormatError(`the zstd frame claims ${declared} bytes, over the ${maxOut} bound`);
+        }
+        return codec.decompress(rest, maxOut);
+    }
+    throw new ManifestFormatError(`unknown file list compression flag ${String(flag)}`);
+}
+/** The parsed JSON object inside a sealed plaintext, or a `ManifestFormatError` saying why not. */
+async function parse(body, maxOut) {
+    const json = await unpack(body, maxOut);
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(json));
+    }
+    catch {
+        throw new ManifestFormatError("file list body is not valid JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ManifestFormatError("file list body is not an object");
+    }
+    return { ...parsed };
+}
+/** The sealed version this document carries — `1` or `2`, or a refusal naming what it said. */
+function versionOf(doc) {
+    const v = doc.v;
+    if (typeof v !== "number")
+        throw new ManifestFormatError(`file list has no version (v=${String(v)})`);
+    return v;
+}
+/** The sealed store version, checked the way §6.1 requires: present, positive, and linked. */
+function seqOf(doc, what) {
+    const seq = doc.seq;
+    if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 1) {
+        throw new ManifestFormatError(`${what} has no sealed version (seq=${String(seq)})`);
+    }
+    return seq;
+}
+// ------------------------------------------------------------------------------ the index
+/** The index → the plaintext to seal under `AAD_FILE_LIST`. */
+export async function encodeIndex(index) {
+    if (!Number.isSafeInteger(index.seq) || index.seq < 1) {
+        throw new ManifestFormatError(`file list seq must be a positive integer, got ${index.seq}`);
+    }
+    // Version 1 has nothing before it; every later version must name what it continued from, or the
+    // fork check has a hole exactly where a fork would be introduced (§6.1 check 3).
+    if (index.seq > 1 && !index.p) {
+        throw new ManifestFormatError(`file list seq ${index.seq} must name the version it was built on`);
+    }
+    const st = settingsToWire(index.settings);
+    const wire = {
+        v: FILE_LIST_VERSION_CHUNKED,
+        seq: index.seq,
+        ...(index.p ? { p: index.p } : {}),
+        ...(st ? { settings: st } : {}),
+        chunks: index.chunks.map((c) => ({ h: c.h, n: c.n, f: c.f, l: c.l })),
+    };
+    return pack(new TextEncoder().encode(JSON.stringify(wire)));
+}
+/** Sealed plaintext → the index. Throws `ManifestFormatError` on anything it cannot read. */
+export async function decodeIndex(body) {
+    return indexFrom(await parse(body, INDEX_PLAIN_MAX));
+}
+function indexFrom(doc) {
+    const v = versionOf(doc);
+    if (v !== FILE_LIST_VERSION_CHUNKED) {
+        throw new ManifestFormatError(`unsupported file list version ${v}`);
+    }
+    const seq = seqOf(doc, "file list index");
+    const p = doc.p;
+    if (seq > 1 && typeof p !== "string") {
+        throw new ManifestFormatError(`file list index ${seq} does not say what it was built on`);
+    }
+    if (!Array.isArray(doc.chunks))
+        throw new ManifestFormatError("file list index names no chunks");
+    const chunks = [];
+    for (const raw of doc.chunks) {
+        // Every field is load-bearing: the hash IS the pin, and a row missing one of them would leave
+        // a chunk that could not be checked. Refusing the index is the only honest answer.
+        if (!raw || typeof raw !== "object")
+            throw new ManifestFormatError("file list index has a broken chunk row");
+        const row = { ...raw };
+        const { h, n, f, l } = row;
+        if (typeof h !== "string" || h === "")
+            throw new ManifestFormatError("a chunk row has no name");
+        if (typeof n !== "number" || !Number.isSafeInteger(n) || n < 0) {
+            throw new ManifestFormatError(`chunk ${h} does not say how many entries it holds`);
+        }
+        if (typeof f !== "string" || typeof l !== "string") {
+            throw new ManifestFormatError(`chunk ${h} has no placement range`);
+        }
+        chunks.push({ h, n, f, l });
+    }
+    const settings = settingsFromWire(doc.settings);
+    return {
+        v: FILE_LIST_VERSION_CHUNKED,
+        seq,
+        ...(typeof p === "string" ? { p } : {}),
+        ...(settings ? { settings } : {}),
+        chunks,
+    };
+}
+// ------------------------------------------------------------------------------ one chunk
+/** A chunk → the plaintext to seal under `AAD_FILE_LIST_CHUNK`. */
+export async function encodeChunk(doc) {
+    if (!Number.isSafeInteger(doc.seq) || doc.seq < 1) {
+        throw new ManifestFormatError(`chunk seq must be a positive integer, got ${doc.seq}`);
+    }
+    const wire = {
+        v: FILE_LIST_VERSION_CHUNKED,
+        seq: doc.seq,
+        items: doc.items.map(toWire),
+    };
+    return pack(new TextEncoder().encode(JSON.stringify(wire)));
+}
+/** Sealed chunk plaintext → its entries. */
+export async function decodeChunk(body) {
+    const doc = await parse(body, CHUNK_PLAIN_MAX);
+    const v = versionOf(doc);
+    if (v !== FILE_LIST_VERSION_CHUNKED)
+        throw new ManifestFormatError(`unsupported chunk version ${v}`);
+    const seq = seqOf(doc, "chunk");
+    if (!Array.isArray(doc.items))
+        throw new ManifestFormatError("chunk has no item list");
+    return { v: FILE_LIST_VERSION_CHUNKED, seq, items: doc.items.map(fromWire) };
+}
+// ------------------------------------------------------------------------------ either version
+/**
+ * The reader's one door: sealed plaintext → whichever version it turned out to be.
+ *
+ * ⚠ A version-1 body is inflated twice — once here to read `v`, once by `decodeManifest`. That is
+ * deliberate rather than a duplicate validator: version 1's rules live in one place and stay
+ * there. The cost is bounded and self-extinguishing, because the first save after a version-1 load
+ * converts the account (§6.3.6) and no later read takes this branch.
+ */
+export async function decodeFileList(body) {
+    const doc = await parse(body, INDEX_PLAIN_MAX);
+    const v = versionOf(doc);
+    if (v === FILE_LIST_VERSION_CHUNKED)
+        return { v: FILE_LIST_VERSION_CHUNKED, index: indexFrom(doc) };
+    if (v === 1)
+        return { v: 1, manifest: await decodeManifest(body) };
+    // An unknown version means another device wrote a format this build predates. Refusing is the
+    // safe answer, and §6.1 says the caller must never render the refusal as an empty drive.
+    throw new ManifestFormatError(`unsupported file list version ${v}`);
+}

package/dist/shared/lib/drive/manifest-codec.d.ts

@@ -0,0 +1,214 @@
+import { TEXT_SCALE_DEFAULT_PCT, TEXT_SCALE_MAX_PCT, TEXT_SCALE_MIN_PCT, type AccountSettings } from "./manifest-settings.ts";
+export { TEXT_SCALE_DEFAULT_PCT, TEXT_SCALE_MAX_PCT, TEXT_SCALE_MIN_PCT };
+export type { AccountSettings };
+/**
+ * One share this device made, kept where the server cannot reach it (`ManifestEntry.shares`).
+ *
+ * A receipt is written only AFTER the server's created row was checked to carry the very address
+ * the sender typed — so what is stored is the address she asked for, never one the server chose.
+ */
+export interface ShareReceipt {
+    /** Recipient address in WIRE form: exactly what the create call was checked against. */
+    address: string;
+    /** When this device wrote the receipt, ms since the Unix epoch. This browser's clock. */
+    at: number;
+    /**
+     * A revoke was sent for this receipt and the listing has not yet come back without the row.
+     *
+     * The receipt outlives the revoke ON PURPOSE: a revoke this side cannot verify is exactly the
+     * case worth keeping, and a listing that still carries the address is the only evidence the
+     * removal did not happen. Dropped once a listing no longer names it (`sharePrune`), which is
+     * what keeps this array from growing forever.
+     */
+    revoked?: true;
+}
+/** One entry — a file or a folder — as the rest of the app sees it. */
+export interface ManifestEntry {
+    /** Item id. Files: the id the server assigned at commit. Folders: client-generated. */
+    id: string;
+    /** Parent folder id, or null for the drive root. */
+    parentId: string | null;
+    /** 0 folder · 1 file (the same numeric codes the items API uses). */
+    kind: number;
+    /** Plaintext name. */
+    name: string;
+    /** Plaintext size in bytes; 0 for folders. */
+    size: number;
+    /** Created, ms since the Unix epoch (UTC). */
+    createdAt: number;
+    /** Last modified, ms since epoch. */
+    updatedAt: number;
+    /** In the trash since this instant; absent = live. */
+    deletedAt?: number;
+    /** Wrapped file DEK (base64url NCF-3 §3 envelope, 104 bytes), files only. Carried verbatim. */
+    dekWrapped?: string;
+    /** Sealed content hash (base64url NCF-3 §3 envelope, 104 bytes), files only. Carried verbatim. */
+    contentHashCt?: string;
+    /**
+     * Which storage network holds this file's bytes (`lib/storage-network.ts` codes), files only.
+     *
+     * ABSENT MEANS WALRUS — a fact, not a default: no other network has an upload path, so every
+     * entry written before this field is on Walrus by construction. Writing the field only when it
+     * is NOT Walrus keeps the common case free, which matters in a blob that is rewritten whole on
+     * every change and re-downloaded on every cold start.
+     *
+     * Here rather than read from the server per file because the drive list is built from THIS
+     * document alone — the server's item rows carry no placement, and a per-file round trip to
+     * learn where each one lives is what NMF-1 exists to avoid.
+     *
+     * ⚠ DISPLAY, NOT TRUTH. `file_parts.network` on the server is what recovery and the lifecycle
+     * sweep read. A stale tab that saves can drop this mark the same way it can drop a star (see
+     * MANIFEST_FORMAT_VERSION), which would show the wrong tier until the list is rebuilt — bad,
+     * but not lost bytes.
+     */
+    network?: number;
+    /** Starred by the person: shows in Favourites wherever the file actually lives. Absent = not. */
+    favorite?: true;
+    /** Kept at the top of its own folder listing. Absent = not. Independent of `favorite`. */
+    pinned?: true;
+    /**
+     * MY OWN RECORD of who this file was shared with.
+     *
+     * WHY IT IS HERE. The recipients list on screen is the SERVER'S record: a row it joined through
+     * `shares.recipient_id`. A server that hides a row makes the sender believe she never shared;
+     * one that answers "deleted" without deleting makes her believe she took access back. Neither is
+     * catchable from a list only the server can produce. This is the one place the server cannot
+     * edit — the list is sealed under the account's own key — so a receipt written here is the only
+     * thing that can be held up against what the server says.
+     *
+     * ⚠ WHAT IT DOES NOT DO. A receipt proves the SHARE WAS MADE; it cannot revoke one, and it
+     * cannot make an adversarial server stop serving the ciphertext. It also cannot say a row with
+     * no receipt is fabricated: shares made before this field existed have none, and a build that
+     * does not read this field rewrites the list without it (the same limit every mark here has).
+     * That asymmetry is why only two mismatches are ever shown to the person, and neither of them
+     * is "the server invented a row" — see `share-receipts.ts`.
+     *
+     * Absent = this device has recorded nothing for this file, which is NOT "shared with nobody".
+     */
+    shares?: ShareReceipt[];
+    /**
+     * Labels — the person's own labels for this item, stored as the label TEXT.
+     *
+     * There is deliberately no registry of labels: a label exists exactly as long as some item wears
+     * it. That is what keeps every edit replayable onto a list this device has not seen (two devices
+     * inventing the same label converge instead of colliding on an id), and it means a label can
+     * never outlive its last file as an empty row nobody can explain. Renaming one is a sweep across
+     * the entries that carry it (manifest-ops.ts `labelRename`).
+     *
+     * The text is plaintext INSIDE the sealed blob — the same protection the file names get, and the
+     * reason labels are not in the URL: a query string would hand the label to the server and the CDN
+     * log in the clear — the server is never handed a per-account value it could use as a handle.
+     */
+    labels?: string[];
+}
+/**
+ * Account-level settings that live INSIDE the sealed list.
+ *
+ * Here and not in a server column because the server must not learn them: which accounts run
+ * developer mode, or read at what size, is exactly the sort of per-account profile it must never
+ * be handed. Here and not in device storage because they are account-level — one switch, every
+ * signed-in device.
+ *
+ * EVERY FIELD DEFAULTS BY ABSENCE, like the entry marks above it. ⚠ The honest limit is the same
+ * as a star's: an older build that SAVES rewrites the blob without the member it never read, so a
+ * stale tab can silently reset these. Turning them back on is the whole repair.
+ */
+/** The decoded manifest. */
+export interface Manifest {
+    /** Format version — NMF-1 is `1`. Read this FIRST when handling a future format. */
+    v: number;
+    /**
+     * The store version this blob was SEALED at (NCF-3 §6.1, defect A3).
+     *
+     * The server also keeps this number in a column, and before NCF-3 that column was the only
+     * copy — so the server could hand back an older `(seq, ct)` pair and the client had no way to
+     * tell. Deleted files reappeared, recent uploads vanished, a rename undid itself. Sealing the
+     * number means the version and the contents are authenticated together.
+     */
+    seq: number;
+    /**
+     * SHA-256 of the SEALED bytes this list was built from, base64url. Absent only for version 1.
+     *
+     * The version check alone narrows rollback; it does not close it. A server can pin a device that
+     * is merely *behind* by answering with the version it last saw, and it can show two devices two
+     * different forks indefinitely — "not lower than the highest I have seen" is satisfied by
+     * standing still. A link to the previous blob makes a fork visible to the NEXT reader on ANY
+     * device, because a list whose `prev` is not the blob that device actually opened cannot be a
+     * continuation of it.
+     */
+    prev?: string;
+    entries: ManifestEntry[];
+    /** Account-level settings, absent when nothing was ever set. */
+    settings?: AccountSettings;
+}
+/**
+ * Current format version this build writes.
+ *
+ * STAYS 1 WHEN OPTIONAL FIELDS ARE ADDED (favorite · pinned · labels · account settings landed
+ * this way). The reader
+ * below refuses any version it does not know, so bumping would lock every already-open tab out of
+ * the drive to buy nothing: an older build ignores fields it has never heard of and renders the
+ * list correctly. The cost of that choice is real and bounded — an older build that SAVES rewrites
+  * the entries without the marks it dropped, so a stale tab can clear stars and labels. Bump only for
+ * a change an old build would MISREAD, not one it would merely not show.
+ */
+export declare const MANIFEST_FORMAT_VERSION = 1;
+/** base64url SHA-256 of a sealed blob — the value a later list carries as its `prev`. */
+export declare function manifestFingerprint(ct: string): Promise<string>;
+export declare const FLAG_RAW = 0;
+export declare const FLAG_GZIP = 1;
+/** The compact per-entry shape actually stored. */
+export interface WireEntry {
+    i: string;
+    p: string | null;
+    k: number;
+    n: string;
+    s: number;
+    c: number;
+    u: number;
+    d?: number;
+    w?: string;
+    h?: string;
+    f?: 1;
+    pn?: 1;
+    l?: string[];
+    sn?: number;
+    sh?: WireShareReceipt[];
+}
+/** One share receipt on the wire. Same short-key reason as the entry above it. */
+interface WireShareReceipt {
+    /** address. */
+    a: string;
+    /** at. */
+    t: number;
+    /** revoked. */
+    r?: 1;
+}
+export declare function toWire(e: ManifestEntry): WireEntry;
+export declare function fromWire(w: WireEntry): ManifestEntry;
+/** Thrown when the plaintext is not a manifest this build can read. */
+export declare class ManifestFormatError extends Error {
+    constructor(message: string);
+}
+/**
+ * Entries → the plaintext to seal.
+ *
+ * Compresses when the platform offers `CompressionStream`, which is the normal case and roughly
+ * halves the blob (names and repeated JSON keys compress well). When it does not, the raw form is
+ * written instead of failing: an older browser must still be able to save its drive.
+ */
+export declare function encodeManifest(entries: readonly ManifestEntry[], seq: number, prev?: string, settings?: AccountSettings): Promise<Uint8Array>;
+/**
+ * Sealed plaintext → entries.
+ *
+ * Throws `ManifestFormatError` on anything it cannot read — including a version from the future.
+ * Callers must NOT treat a throw as "the drive is empty": it is the signal to try the retained
+ * previous version, because rendering an empty drive invites the user to re-upload everything.
+ */
+export declare function decodeManifest(body: Uint8Array): Promise<Manifest>;
+/** Prepend the compression flag byte. */
+export declare function withFlag(flag: number, body: Uint8Array): Uint8Array;
+/** gzip, or null when the platform has no `CompressionStream`. */
+export declare function gzip(bytes: Uint8Array): Promise<Uint8Array | null>;
+/** gunzip, or null when the platform has no `DecompressionStream`. */
+export declare function gunzip(bytes: Uint8Array): Promise<Uint8Array | null>;

package/dist/shared/lib/drive/manifest-codec.js

@@ -38,9 +38,9 @@ export async function manifestFingerprint(ct) {
         bin += String.fromCharCode(b);
     return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-const FLAG_RAW = 0x00;
-const FLAG_GZIP = 0x01;
-function toWire(e) {
+export const FLAG_RAW = 0x00;
+export const FLAG_GZIP = 0x01;
+export function toWire(e) {
     const w = {
         i: e.id,
         p: e.parentId,
@@ -75,7 +75,7 @@ function toWire(e) {
     }
     return w;
 }
-function fromWire(w) {
+export function fromWire(w) {
     const e = {
         id: w.i,
         parentId: w.p ?? null,
@@ -228,21 +228,21 @@ export async function decodeManifest(body) {
     };
 }
 /** Prepend the compression flag byte. */
-function withFlag(flag, body) {
+export function withFlag(flag, body) {
     const out = new Uint8Array(body.length + 1);
     out[0] = flag;
     out.set(body, 1);
     return out;
 }
 /** gzip, or null when the platform has no `CompressionStream`. */
-async function gzip(bytes) {
+export async function gzip(bytes) {
     const C = globalThis.CompressionStream;
     if (!C)
         return null;
     return collect(streamThrough(bytes, new C("gzip")));
 }
 /** gunzip, or null when the platform has no `DecompressionStream`. */
-async function gunzip(bytes) {
+export async function gunzip(bytes) {
     const D = globalThis.DecompressionStream;
     if (!D)
         return null;

package/dist/shared/lib/drive/manifest-index.d.ts

@@ -0,0 +1,98 @@
+import type { ManifestEntry } from "./manifest-codec.ts";
+/** Folder items use kind 0, files kind 1 — the same numbers the items API uses. */
+export declare const KIND_FOLDER = 0;
+export declare const KIND_FILE = 1;
+export interface ManifestIndex {
+    /** Every entry, in the order the list was written. */
+    readonly all: readonly ManifestEntry[];
+    readonly byId: ReadonlyMap<string, ManifestEntry>;
+    /** Direct children by parent id (root under its own key). Values keep list order. */
+    readonly childrenByParent: ReadonlyMap<string, readonly ManifestEntry[]>;
+}
+/** Build the lookup structures for one version of the list. Cost is linear; do it once. */
+export declare function buildIndex(entries: readonly ManifestEntry[]): ManifestIndex;
+/**
+ * The instant this item became trash — its own, or the nearest trashed ancestor's.
+ * `null` means live. A parent chain that is broken or looping counts as live at the point it
+ * breaks: showing an item whose parent vanished is recoverable, hiding it silently is not.
+ */
+export declare function trashedAt(index: ManifestIndex, entry: ManifestEntry): number | null;
+/** Live = not trashed itself and under no trashed ancestor. */
+export declare function isLive(index: ManifestIndex, entry: ManifestEntry): boolean;
+/**
+ * Does the ACCOUNT hold a file that whole-account export could actually write out?
+ *
+ * Asked by the export card, which offers itself on this and nothing else. The two wrong answers it
+ * replaces are both easy to reach: counting the CURRENT LEVEL hides the card from an account whose
+ * files all sit inside folders, and counting entries of any kind offers a download to a drive of
+ * empty folders — one that can only answer "there is nothing to download".
+ *
+ * ⚠ Trashed files are excluded on purpose. They are still stored and still paid for, but export
+ * writes the live drive, so a drive whose every file is in the trash has nothing to export.
+ */
+export declare function hasLiveFile(index: ManifestIndex): boolean;
+/**
+ * Live children of a folder (`null` = drive root), in list order.
+ * Sorting belongs to the view: the same folder is shown by name, size and date in different places.
+ */
+export declare function childrenOf(index: ManifestIndex, parentId: string | null): readonly ManifestEntry[];
+/**
+ * What the trash view shows: items the person deleted directly, newest first.
+ * A child whose parent is also trashed is deliberately absent — it is restored with its parent.
+ */
+export declare function trashRoots(index: ManifestIndex): readonly ManifestEntry[];
+/**
+ * Folder names from the root down to (and excluding) this item.
+ * An entry whose chain is broken returns what could be resolved — callers render that as a
+ * partial path rather than claiming the item sits at the root.
+ */
+export declare function pathOf(index: ManifestIndex, entry: ManifestEntry): readonly string[];
+/** Every descendant of a folder, live and trashed, depth-first. The folder itself is excluded. */
+export declare function descendantsOf(index: ManifestIndex, folderId: string): readonly ManifestEntry[];
+/**
+ * True when `folderId` is `candidateId` or sits underneath it.
+ * Move targets are checked with this: dropping a folder into its own subtree would detach that
+ * whole branch from the root, and nothing in the UI could reach it afterwards.
+ */
+export declare function isSelfOrDescendant(index: ManifestIndex, candidateId: string, folderId: string): boolean;
+/**
+ * Live items whose name contains `query`, case-insensitively.
+ *
+ * This search is COMPLETE — it reads the whole list from memory. That is a change worth knowing
+ * about: the old server-backed listing could only match what had been fetched, so "no results"
+ * was a claim the UI had to hedge. Here it is simply true.
+ */
+export declare function searchByName(index: ManifestIndex, query: string, limit?: number): readonly ManifestEntry[];
+/**
+ * Live files the person starred, newest first.
+ *
+ * Files only: a folder is already reachable in the panel's tree, so starring one would put the same
+ * thing in two places and make "favourites" mean two different kinds of row.
+ */
+export declare function favoriteFiles(index: ManifestIndex): readonly ManifestEntry[];
+/**
+ * Every label in use, with how many live files wear it, ordered by the person's own locale.
+ *
+ * Counting here rather than in the panel matters: the count is what tells someone a label still has
+ * files in it before they rename or clear it, and it must agree with what opening it shows.
+ */
+export declare function labelCounts(index: ManifestIndex): {
+    label: string;
+    count: number;
+}[];
+/** Live files wearing one label, newest first. */
+export declare function filesWithLabel(index: ManifestIndex, label: string): readonly ManifestEntry[];
+export interface DriveTotals {
+    /** Live files. Folders are not counted — they hold nothing. */
+    files: number;
+    /** Live folders. */
+    folders: number;
+    /** Bytes of live files. */
+    bytes: number;
+    /** Files sitting in the trash (still stored, still paid for). */
+    trashedFiles: number;
+    /** Bytes held by trashed files — the figure that explains "deleting did not free space yet". */
+    trashedBytes: number;
+}
+/** Whole-drive counts. Exact, because the list is complete by construction. */
+export declare function totalsOf(index: ManifestIndex): DriveTotals;