cursedbelt-server 4.45.0 → 4.46.1

package/dist/server/storage/binaryStore.js

@@ -417,13 +417,16 @@ export function createBinaryStore(cfg) {
      * caller asked for `paced` and the budget allows, otherwise thrown as a typed error that
      * keeps the `[binary-store] <op> <key>: 429` message batch callers already match.
      */
-    const sendRead = async (op, key, url, init, opts) => {
+    const sendRead = async (op, key, 
+    /** Signs the URL. Called for EVERY attempt: a read token lives 60 s and a paced read may wait
+     *  120 s, so a URL signed once went out dead after the first long retry-after (forge task 3302). */
+    mint, init, opts) => {
         const budget = opts?.paced
             ? (typeof opts.paced === 'object' ? opts.paced.maxWaitMs : undefined) ?? BINARY_PACED_MAX_WAIT_MS
             : 0;
         let waited = 0;
         for (let attempt = 0;; attempt++) {
-            const res = await send(url, init);
+            const res = await send(await mint(), init);
             if (res.status !== 429)
                 return res;
             const retryAfterSec = retryAfterSeconds(res.headers.get('retry-after'), attempt);
@@ -548,7 +551,7 @@ export function createBinaryStore(cfg) {
             if (!opts?.fresh && knownAbsent(key))
                 return null;
             countWireRead(key);
-            const res = await sendRead('get', key, await internalMediaUrl(key), undefined, opts);
+            const res = await sendRead('get', key, () => internalMediaUrl(key), undefined, opts);
             if (res.status === 404) {
                 rememberAbsent(key);
                 return null;
@@ -624,7 +627,7 @@ export function createBinaryStore(cfg) {
                     return null;
             }
             countWireRead(key);
-            const res = await sendRead('meta', key, await metaUrl(key), undefined, opts);
+            const res = await sendRead('meta', key, () => metaUrl(key), undefined, opts);
             if (res.status === 404) {
                 rememberAbsent(key);
                 return null;
@@ -671,7 +674,7 @@ export function createBinaryStore(cfg) {
                     throw why;
             }
             countWireRead(key);
-            const res = await sendRead('stat', key, await internalMediaUrl(key), { headers: { Range: 'bytes=0-0' } }, opts);
+            const res = await sendRead('stat', key, () => internalMediaUrl(key), { headers: { Range: 'bytes=0-0' } }, opts);
             if (res.status === 404) {
                 rememberAbsent(key);
                 return null;

package/dist/server/zipStream.d.ts

@@ -59,6 +59,14 @@ export type ZipEntry = {
     name: string;
     directory: true;
     modified?: Date | string | null;
+} | {
+    /**
+     * A member the CALLER could not read before naming it (desk reads a picture's bytes to
+     * decide its extension). Nothing is written under this name; it is listed, with `missing`
+     * as the reason, in the archive's `MISSING FILES.txt`.
+     */
+    name: string;
+    missing: string;
 };
 /**
  * Names inside a zip must not escape the extraction directory, and must not carry characters
@@ -78,6 +86,11 @@ export declare function dosDateTime(when: Date | string | null | undefined): {
  * Duplicate file names are disambiguated rather than colliding — two different files that both
  * want `Notes/Summary.md` produce `Summary.md` and `Summary (2).md`, because a zip with two
  * identical names extracts as one file, silently losing the other. A duplicate FOLDER is written
- * once: its files already land in it.
+ * once: its files already land in it. Names are compared the way the person's disk will compare
+ * them — case-folded and Unicode-normalised, since macOS and Windows both treat `Todo.md` and
+ * `todo.md` as ONE file — so the later one is numbered rather than overwriting the first on unzip.
+ *
+ * A member that cannot be read (its `open()` returns `null` or throws, or the caller yielded it
+ * as `missing`) is left out, and listed in a final `MISSING FILES.txt`.
  */
 export declare function zipStream(entries: Iterable<ZipEntry> | AsyncIterable<ZipEntry>): ReadableStream<Uint8Array>;

package/dist/server/zipStream.js

@@ -97,6 +97,12 @@ class ByteWriter {
         return out;
     }
 }
+/**
+ * The last entry of an archive that left anything out: one line per missing path and why.
+ * A skipped file must not end a 2,000-file download, but a zip that reads as complete when it is
+ * not is a backup that fails on the day it is restored — so the skip is never silent.
+ */
+const MISSING_FILES_NAME = "MISSING FILES.txt";
 const encoder = new TextEncoder();
 /** ZIP64 needs version 4.5; bit 3 = sizes/CRC follow in a data descriptor; bit 11 = UTF-8
  *  names, which every accented and non-Latin file name needs. */
@@ -141,6 +147,22 @@ export function dosDateTime(when) {
         time: (at.getUTCHours() << 11) | (at.getUTCMinutes() << 5) | Math.floor(at.getUTCSeconds() / 2),
     };
 }
+/**
+ * A name as the extracting disk compares it. APFS and NTFS are case-insensitive by default, and
+ * APFS also ignores Unicode composition (`é` typed as one code point or as `e` + accent), so two
+ * names equal under this fold are ONE file there — and the second would overwrite the first.
+ */
+function foldName(name) {
+    return name.normalize("NFC").toLowerCase();
+}
+/** A reason for a person to read: one line, short, and never a signed URL's query string. */
+function readableReason(text) {
+    return text
+        .replace(/(\bhttps?:\/\/[^\s?]*)\?[^\s)]*/g, "$1")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 200);
+}
 function asStream(body) {
     if (!(body instanceof Uint8Array))
         return body;
@@ -158,13 +180,81 @@ function asStream(body) {
  * Duplicate file names are disambiguated rather than colliding — two different files that both
  * want `Notes/Summary.md` produce `Summary.md` and `Summary (2).md`, because a zip with two
  * identical names extracts as one file, silently losing the other. A duplicate FOLDER is written
- * once: its files already land in it.
+ * once: its files already land in it. Names are compared the way the person's disk will compare
+ * them — case-folded and Unicode-normalised, since macOS and Windows both treat `Todo.md` and
+ * `todo.md` as ONE file — so the later one is numbered rather than overwriting the first on unzip.
+ *
+ * A member that cannot be read (its `open()` returns `null` or throws, or the caller yielded it
+ * as `missing`) is left out, and listed in a final `MISSING FILES.txt`.
  */
 export function zipStream(entries) {
     const central = [];
     let offset = 0n;
+    /** Every name written, as the extracting disk will compare it ({@link foldName}). */
     const used = new Set();
+    const missing = [];
+    let reported = false;
     const iterator = Symbol.asyncIterator in entries ? entries[Symbol.asyncIterator]() : entries[Symbol.iterator]();
+    /** A name not yet taken: `Summary.md` → `Summary (2).md`, numbering the file, never its folder's dot. */
+    const freeName = (name) => {
+        if (!used.has(foldName(name)))
+            return name;
+        const slash = name.lastIndexOf("/");
+        const dot = name.lastIndexOf(".");
+        const cut = dot > slash + 1 ? dot : name.length;
+        const stem = name.slice(0, cut);
+        const ext = name.slice(cut);
+        let n = 2;
+        while (used.has(foldName(`${stem} (${n})${ext}`)))
+            n++;
+        return `${stem} (${n})${ext}`;
+    };
+    /** One local header, the bytes, and the data descriptor; remembered for the central directory. */
+    const writeEntry = async (controller, name, body, modified) => {
+        const directory = body === null;
+        used.add(foldName(name));
+        const nameBytes = encoder.encode(name);
+        const { date, time } = dosDateTime(modified);
+        // ZIP64 extra field, sizes zeroed — the data descriptor carries the truth.
+        const localExtra = new ByteWriter().u16(0x0001).u16(16).u64(0).u64(0).done();
+        const header = new ByteWriter()
+            .u32(0x04034b50)
+            .u16(VERSION_ZIP64)
+            .u16(FLAG_DATA_DESCRIPTOR | FLAG_UTF8)
+            .u16(METHOD_STORE)
+            .u16(time)
+            .u16(date)
+            .u32(0) // crc, in the descriptor
+            .u32(0xffffffff) // compressed size → see ZIP64 extra
+            .u32(0xffffffff) // uncompressed size → see ZIP64 extra
+            .u16(nameBytes.length)
+            .u16(localExtra.length)
+            .raw(nameBytes)
+            .raw(localExtra)
+            .done();
+        controller.enqueue(header);
+        const entryOffset = offset;
+        offset += BigInt(header.length);
+        const crc = new Crc32();
+        let size = 0n;
+        if (body) {
+            const reader = body.getReader();
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                crc.update(value);
+                size += BigInt(value.length);
+                controller.enqueue(value);
+            }
+        }
+        offset += size;
+        // ZIP64 data descriptor: 8-byte sizes, unlike the 4-byte classic form.
+        const descriptor = new ByteWriter().u32(0x08074b50).u32(crc.value).u64(size).u64(size).done();
+        controller.enqueue(descriptor);
+        offset += BigInt(descriptor.length);
+        central.push({ name: nameBytes, crc: crc.value, size, offset: entryOffset, date, time, directory });
+    };
     return new ReadableStream({
         async pull(controller) {
             // One entry per pull keeps backpressure honest: the next file is not opened until the
@@ -180,76 +270,39 @@ export function zipStream(entries) {
                 if (next.done)
                     break;
                 const entry = next.value;
-                const directory = entry.directory === true;
-                let name = safeEntryName(entry.name);
-                if (directory) {
-                    name = `${name}/`;
-                    if (used.has(name))
-                        continue;
-                }
-                else if (used.has(name)) {
-                    const slash = name.lastIndexOf("/");
-                    const dot = name.lastIndexOf(".");
-                    const cut = dot > slash + 1 ? dot : name.length;
-                    const stem = name.slice(0, cut);
-                    const ext = name.slice(cut);
-                    let n = 2;
-                    while (used.has(`${stem} (${n})${ext}`))
-                        n++;
-                    name = `${stem} (${n})${ext}`;
+                if ("missing" in entry) {
+                    missing.push({ name: safeEntryName(entry.name), reason: readableReason(entry.missing) || "could not be read" });
+                    continue;
                 }
-                let body = null;
-                if (!directory) {
-                    const opened = await entry.open().catch(() => null);
-                    // A file whose bytes have gone is skipped, not fatal: one missing file must not abort
-                    // a 2,000-file download that is otherwise fine. `continue`, never `return` — see the
-                    // note on the loop above.
-                    if (!opened)
+                if (entry.directory === true) {
+                    const name = `${safeEntryName(entry.name)}/`;
+                    if (used.has(foldName(name)))
                         continue;
-                    body = asStream(opened);
+                    await writeEntry(controller, name, null, entry.modified);
+                    return;
                 }
-                used.add(name);
-                const nameBytes = encoder.encode(name);
-                const { date, time } = dosDateTime(entry.modified);
-                // ZIP64 extra field, sizes zeroed — the data descriptor carries the truth.
-                const localExtra = new ByteWriter().u16(0x0001).u16(16).u64(0).u64(0).done();
-                const header = new ByteWriter()
-                    .u32(0x04034b50)
-                    .u16(VERSION_ZIP64)
-                    .u16(FLAG_DATA_DESCRIPTOR | FLAG_UTF8)
-                    .u16(METHOD_STORE)
-                    .u16(time)
-                    .u16(date)
-                    .u32(0) // crc, in the descriptor
-                    .u32(0xffffffff) // compressed size → see ZIP64 extra
-                    .u32(0xffffffff) // uncompressed size → see ZIP64 extra
-                    .u16(nameBytes.length)
-                    .u16(localExtra.length)
-                    .raw(nameBytes)
-                    .raw(localExtra)
-                    .done();
-                controller.enqueue(header);
-                const entryOffset = offset;
-                offset += BigInt(header.length);
-                const crc = new Crc32();
-                let size = 0n;
-                if (body) {
-                    const reader = body.getReader();
-                    while (true) {
-                        const { done, value } = await reader.read();
-                        if (done)
-                            break;
-                        crc.update(value);
-                        size += BigInt(value.length);
-                        controller.enqueue(value);
-                    }
+                const name = freeName(safeEntryName(entry.name));
+                let failure = "its bytes are missing from the store";
+                const opened = await entry.open().catch((error) => {
+                    failure = `could not be read (${readableReason(error instanceof Error ? error.message : String(error)) || "unknown error"})`;
+                    return null;
+                });
+                // A file whose bytes have gone is skipped, not fatal: one missing file must not abort
+                // a 2,000-file download that is otherwise fine. `continue`, never `return` — see the
+                // note on the loop above.
+                if (!opened) {
+                    missing.push({ name, reason: failure });
+                    continue;
                 }
-                offset += size;
-                // ZIP64 data descriptor: 8-byte sizes, unlike the 4-byte classic form.
-                const descriptor = new ByteWriter().u32(0x08074b50).u32(crc.value).u64(size).u64(size).done();
-                controller.enqueue(descriptor);
-                offset += BigInt(descriptor.length);
-                central.push({ name: nameBytes, crc: crc.value, size, offset: entryOffset, date, time, directory });
+                await writeEntry(controller, name, asStream(opened), entry.modified);
+                return;
+            }
+            if (missing.length > 0 && !reported) {
+                reported = true;
+                const lines = missing.map((m) => `${m.name} — ${m.reason}`);
+                const count = missing.length === 1 ? "1 file was" : `${missing.length} files were`;
+                const text = `${count} in the selection but could not be read, so this archive does NOT contain ${missing.length === 1 ? "it" : "them"}:\n\n${lines.join("\n")}\n`;
+                await writeEntry(controller, freeName(MISSING_FILES_NAME), asStream(encoder.encode(text)), new Date());
                 return;
             }
             // Central directory, then the ZIP64 end records, then the classic end record.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.45.0",
+	"version": "4.46.1",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",

package/src/server/storage/binaryStore.spec.ts

@@ -26,7 +26,7 @@
  * server; the RSA keypair is generated in-process and the signature is verified with
  * `node:crypto`, which is what makes the token assertions real rather than shape-deep.
  */
-import { afterAll, afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { afterAll, afterEach, beforeEach, describe, expect, it, setSystemTime } from 'bun:test';
 import { generateKeyPairSync, verify as cryptoVerify } from 'node:crypto';
 import {
   AUTO_CHUNK_THRESHOLD_BYTES,
@@ -1056,6 +1056,29 @@ describe('🔴 a read the store PACES is waited out when asked, typed when not (
     expect(calls).toHaveLength(4);
   });
 
+  it('🔴 every attempt goes with a token signed for IT — a 60 s token outlives no 120 s wait (forge task 3302)', async () => {
+    // The URL was signed once, before the first attempt, so a paced read that waited out 30 s
+    // refusals sent a dead token on its third try, and binary-server answered 403 — not 429.
+    try {
+      let n = 0;
+      reply = () => (n++ < 3 ? limited('30') : ok(new Uint8Array([7, 8])));
+      const store = makeStore({
+        sleep: (ms) => {
+          setSystemTime(new Date(Date.now() + ms));
+          return Promise.resolve();
+        },
+      });
+      await store.get('parts/0', { paced: true });
+      expect(calls).toHaveLength(4);
+      // The last attempt went 90 s after the first: its token must still have time left.
+      const token = new URL(String(calls.at(-1)?.url)).searchParams.get('token') ?? '';
+      const { exp } = JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString('utf8')) as { exp: number };
+      expect(exp * 1000).toBeGreaterThan(Date.now());
+    } finally {
+      setSystemTime();
+    }
+  });
+
   it('without paced, a 429 is the typed error carrying retryAfterSec — and the old message', async () => {
     const { store, slept } = pacedStore(1, '7');
     const error = await store.get('parts/0').catch((e: unknown) => e);

package/src/server/storage/binaryStore.ts

@@ -728,7 +728,9 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
   const sendRead = async (
     op: string,
     key: string,
-    url: string,
+    /** Signs the URL. Called for EVERY attempt: a read token lives 60 s and a paced read may wait
+     *  120 s, so a URL signed once went out dead after the first long retry-after (forge task 3302). */
+    mint: () => Promise<string>,
     init: RequestInit | undefined,
     opts: ReadOptions | undefined,
   ): Promise<Response> => {
@@ -737,7 +739,7 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
       : 0;
     let waited = 0;
     for (let attempt = 0; ; attempt++) {
-      const res = await send(url, init);
+      const res = await send(await mint(), init);
       if (res.status !== 429) return res;
       const retryAfterSec = retryAfterSeconds(res.headers.get('retry-after'), attempt);
       const ms = retryAfterSec * 1000;
@@ -875,7 +877,7 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
       // short-circuit here — we want the bytes, and only the store has them.
       if (!opts?.fresh && knownAbsent(key)) return null;
       countWireRead(key);
-      const res = await sendRead('get', key, await internalMediaUrl(key), undefined, opts);
+      const res = await sendRead('get', key, () => internalMediaUrl(key), undefined, opts);
       if (res.status === 404) {
         rememberAbsent(key);
         return null;
@@ -952,7 +954,7 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
         if (knownAbsent(key)) return null;
       }
       countWireRead(key);
-      const res = await sendRead('meta', key, await metaUrl(key), undefined, opts);
+      const res = await sendRead('meta', key, () => metaUrl(key), undefined, opts);
       if (res.status === 404) {
         rememberAbsent(key);
         return null;
@@ -995,7 +997,7 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
         if (why instanceof BinaryStoreRateLimitedError) throw why;
       }
       countWireRead(key);
-      const res = await sendRead('stat', key, await internalMediaUrl(key), { headers: { Range: 'bytes=0-0' } }, opts);
+      const res = await sendRead('stat', key, () => internalMediaUrl(key), { headers: { Range: 'bytes=0-0' } }, opts);
       if (res.status === 404) {
         rememberAbsent(key);
         return null;

package/src/server/zipStream.spec.ts

@@ -13,6 +13,9 @@ import { Crc32, dosDateTime, safeEntryName, type ZipEntry, zipStream } from './z
 
 const bytesOf = (text: string): Uint8Array => new TextEncoder().encode(text);
 
+/** The report entry a skipped member lands in — spelt out, since a person reads it by this name. */
+const MISSING_FILES_NAME = "MISSING FILES.txt";
+
 const entryFrom = (name: string, body: string): ZipEntry => ({
   name,
   open: async () =>
@@ -145,6 +148,59 @@ describe("zipStream", () => {
     expect(listing).not.toContain("gone.mp3");
   });
 
+  test("🔴 names differing only in case are TWO files — the later is numbered, never overwrites on a Mac", async () => {
+    // Desk lets a folder hold notes "Todo" and "todo". macOS (APFS) and Windows (NTFS) treat
+    // those as one file, so writing both names verbatim loses one on unzip — silently, or behind
+    // a "replace?" prompt the person did not expect.
+    const archive = await collect(zipStream([entryFrom("F/Todo.md", "upper"), entryFrom("f/todo.md", "lower"), entryFrom("F/TODO (2).md", "third")]));
+    const listing = await unzipList(archive);
+    expect(listing).toContain("F/Todo.md");
+    expect(listing).toContain("f/todo (2).md");
+    expect(listing).toContain("F/TODO (2) (2).md");
+    expect(await unzipRead(archive, "f/todo (2).md")).toBe("lower");
+  });
+
+  test("🔴 one name spelt with a composed and a decomposed accent is ONE name to APFS — numbered too", async () => {
+    const composed = "Caf\u00e9.txt";
+    const decomposed = "Cafe\u0301.txt";
+    expect(composed).not.toBe(decomposed);
+    const listing = await unzipList(await collect(zipStream([entryFrom(composed, "a"), entryFrom(decomposed, "b")])));
+    expect(listing).toContain("(2).txt");
+  });
+
+  test("a folder named twice in different case is written once", async () => {
+    const listing = await unzipList(await collect(zipStream([{ name: "Photos", directory: true }, { name: "photos", directory: true }])));
+    expect(listing.match(/ photos\//gi)?.length).toBe(1);
+  });
+
+  test(`🔴 what was skipped is LISTED in a final ${MISSING_FILES_NAME}, with the reason — a skip is never silent`, async () => {
+    const archive = await collect(
+      zipStream([
+        entryFrom("good.mp3", "here"),
+        { name: "gone.mp3", open: async () => null },
+        {
+          name: "Folder/broken.jpg",
+          open: async () => {
+            throw new Error("store answered 503 https://bytes.example/x?sig=SECRET");
+          },
+        },
+        { name: "Notes/unread.png", missing: "could not be read (timeout at https://store.example/b?token=SECRET2)" },
+      ]),
+    );
+    const report = await unzipRead(archive, MISSING_FILES_NAME);
+    expect(report).toContain("3 files were in the selection but could not be read");
+    expect(report).toContain("gone.mp3 — its bytes are missing from the store");
+    expect(report).toContain("Folder/broken.jpg — could not be read (store answered 503 https://bytes.example/x)");
+    expect(report).toContain("Notes/unread.png — could not be read (timeout at https://store.example/b)");
+    expect(report).not.toContain("SECRET2");
+    expect(report).not.toContain("SECRET");
+    expect(await unzipRead(archive, "good.mp3")).toBe("here");
+  });
+
+  test(`a complete archive carries no ${MISSING_FILES_NAME}`, async () => {
+    expect(await unzipList(await collect(zipStream([entryFrom("a.txt", "a")])))).not.toContain(MISSING_FILES_NAME);
+  });
+
   test("an entry whose open() THROWS is skipped rather than killing the archive", async () => {
     const archive = await collect(
       zipStream([

package/src/server/zipStream.ts

@@ -128,8 +128,24 @@ export type ZipEntry =
       name: string;
       directory: true;
       modified?: Date | string | null;
+    }
+  | {
+      /**
+       * A member the CALLER could not read before naming it (desk reads a picture's bytes to
+       * decide its extension). Nothing is written under this name; it is listed, with `missing`
+       * as the reason, in the archive's `MISSING FILES.txt`.
+       */
+      name: string;
+      missing: string;
     };
 
+/**
+ * The last entry of an archive that left anything out: one line per missing path and why.
+ * A skipped file must not end a 2,000-file download, but a zip that reads as complete when it is
+ * not is a backup that fails on the day it is restored — so the skip is never silent.
+ */
+const MISSING_FILES_NAME = "MISSING FILES.txt";
+
 const encoder = new TextEncoder();
 
 /** ZIP64 needs version 4.5; bit 3 = sizes/CRC follow in a data descriptor; bit 11 = UTF-8
@@ -176,6 +192,24 @@ export function dosDateTime(when: Date | string | null | undefined): { date: num
   };
 }
 
+/**
+ * A name as the extracting disk compares it. APFS and NTFS are case-insensitive by default, and
+ * APFS also ignores Unicode composition (`é` typed as one code point or as `e` + accent), so two
+ * names equal under this fold are ONE file there — and the second would overwrite the first.
+ */
+function foldName(name: string): string {
+  return name.normalize("NFC").toLowerCase();
+}
+
+/** A reason for a person to read: one line, short, and never a signed URL's query string. */
+function readableReason(text: string): string {
+  return text
+    .replace(/(\bhttps?:\/\/[^\s?]*)\?[^\s)]*/g, "$1")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 200);
+}
+
 function asStream(body: ReadableStream<Uint8Array> | Uint8Array): ReadableStream<Uint8Array> {
   if (!(body instanceof Uint8Array)) return body;
   return new ReadableStream<Uint8Array>({
@@ -192,7 +226,12 @@ function asStream(body: ReadableStream<Uint8Array> | Uint8Array): ReadableStream
  * Duplicate file names are disambiguated rather than colliding — two different files that both
  * want `Notes/Summary.md` produce `Summary.md` and `Summary (2).md`, because a zip with two
  * identical names extracts as one file, silently losing the other. A duplicate FOLDER is written
- * once: its files already land in it.
+ * once: its files already land in it. Names are compared the way the person's disk will compare
+ * them — case-folded and Unicode-normalised, since macOS and Windows both treat `Todo.md` and
+ * `todo.md` as ONE file — so the later one is numbered rather than overwriting the first on unzip.
+ *
+ * A member that cannot be read (its `open()` returns `null` or throws, or the caller yielded it
+ * as `missing`) is left out, and listed in a final `MISSING FILES.txt`.
  */
 export function zipStream(entries: Iterable<ZipEntry> | AsyncIterable<ZipEntry>): ReadableStream<Uint8Array> {
   interface Central {
@@ -207,10 +246,82 @@ export function zipStream(entries: Iterable<ZipEntry> | AsyncIterable<ZipEntry>)
 
   const central: Central[] = [];
   let offset = 0n;
+  /** Every name written, as the extracting disk will compare it ({@link foldName}). */
   const used = new Set<string>();
+  const missing: { name: string; reason: string }[] = [];
+  let reported = false;
   const iterator: AsyncIterator<ZipEntry> | Iterator<ZipEntry> =
     Symbol.asyncIterator in entries ? (entries as AsyncIterable<ZipEntry>)[Symbol.asyncIterator]() : (entries as Iterable<ZipEntry>)[Symbol.iterator]();
 
+  /** A name not yet taken: `Summary.md` → `Summary (2).md`, numbering the file, never its folder's dot. */
+  const freeName = (name: string): string => {
+    if (!used.has(foldName(name))) return name;
+    const slash = name.lastIndexOf("/");
+    const dot = name.lastIndexOf(".");
+    const cut = dot > slash + 1 ? dot : name.length;
+    const stem = name.slice(0, cut);
+    const ext = name.slice(cut);
+    let n = 2;
+    while (used.has(foldName(`${stem} (${n})${ext}`))) n++;
+    return `${stem} (${n})${ext}`;
+  };
+
+  /** One local header, the bytes, and the data descriptor; remembered for the central directory. */
+  const writeEntry = async (
+    controller: ReadableStreamDefaultController<Uint8Array>,
+    name: string,
+    body: ReadableStream<Uint8Array> | null,
+    modified: Date | string | null | undefined,
+  ): Promise<void> => {
+    const directory = body === null;
+    used.add(foldName(name));
+    const nameBytes = encoder.encode(name);
+    const { date, time } = dosDateTime(modified);
+
+    // ZIP64 extra field, sizes zeroed — the data descriptor carries the truth.
+    const localExtra = new ByteWriter().u16(0x0001).u16(16).u64(0).u64(0).done();
+    const header = new ByteWriter()
+      .u32(0x04034b50)
+      .u16(VERSION_ZIP64)
+      .u16(FLAG_DATA_DESCRIPTOR | FLAG_UTF8)
+      .u16(METHOD_STORE)
+      .u16(time)
+      .u16(date)
+      .u32(0) // crc, in the descriptor
+      .u32(0xffffffff) // compressed size → see ZIP64 extra
+      .u32(0xffffffff) // uncompressed size → see ZIP64 extra
+      .u16(nameBytes.length)
+      .u16(localExtra.length)
+      .raw(nameBytes)
+      .raw(localExtra)
+      .done();
+
+    controller.enqueue(header);
+    const entryOffset = offset;
+    offset += BigInt(header.length);
+
+    const crc = new Crc32();
+    let size = 0n;
+    if (body) {
+      const reader = body.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        crc.update(value);
+        size += BigInt(value.length);
+        controller.enqueue(value);
+      }
+    }
+    offset += size;
+
+    // ZIP64 data descriptor: 8-byte sizes, unlike the 4-byte classic form.
+    const descriptor = new ByteWriter().u32(0x08074b50).u32(crc.value).u64(size).u64(size).done();
+    controller.enqueue(descriptor);
+    offset += BigInt(descriptor.length);
+
+    central.push({ name: nameBytes, crc: crc.value, size, offset: entryOffset, date, time, directory });
+  };
+
   return new ReadableStream<Uint8Array>({
     async pull(controller) {
       // One entry per pull keeps backpressure honest: the next file is not opened until the
@@ -226,77 +337,40 @@ export function zipStream(entries: Iterable<ZipEntry> | AsyncIterable<ZipEntry>)
         if (next.done) break;
         const entry = next.value;
 
-        const directory = entry.directory === true;
-        let name = safeEntryName(entry.name);
-        if (directory) {
-          name = `${name}/`;
-          if (used.has(name)) continue;
-        } else if (used.has(name)) {
-          const slash = name.lastIndexOf("/");
-          const dot = name.lastIndexOf(".");
-          const cut = dot > slash + 1 ? dot : name.length;
-          const stem = name.slice(0, cut);
-          const ext = name.slice(cut);
-          let n = 2;
-          while (used.has(`${stem} (${n})${ext}`)) n++;
-          name = `${stem} (${n})${ext}`;
+        if ("missing" in entry) {
+          missing.push({ name: safeEntryName(entry.name), reason: readableReason(entry.missing) || "could not be read" });
+          continue;
         }
-
-        let body: ReadableStream<Uint8Array> | null = null;
-        if (!directory) {
-          const opened = await entry.open().catch(() => null);
-          // A file whose bytes have gone is skipped, not fatal: one missing file must not abort
-          // a 2,000-file download that is otherwise fine. `continue`, never `return` — see the
-          // note on the loop above.
-          if (!opened) continue;
-          body = asStream(opened);
+        if (entry.directory === true) {
+          const name = `${safeEntryName(entry.name)}/`;
+          if (used.has(foldName(name))) continue;
+          await writeEntry(controller, name, null, entry.modified);
+          return;
         }
-        used.add(name);
-        const nameBytes = encoder.encode(name);
-        const { date, time } = dosDateTime(entry.modified);
-
-        // ZIP64 extra field, sizes zeroed — the data descriptor carries the truth.
-        const localExtra = new ByteWriter().u16(0x0001).u16(16).u64(0).u64(0).done();
-        const header = new ByteWriter()
-          .u32(0x04034b50)
-          .u16(VERSION_ZIP64)
-          .u16(FLAG_DATA_DESCRIPTOR | FLAG_UTF8)
-          .u16(METHOD_STORE)
-          .u16(time)
-          .u16(date)
-          .u32(0) // crc, in the descriptor
-          .u32(0xffffffff) // compressed size → see ZIP64 extra
-          .u32(0xffffffff) // uncompressed size → see ZIP64 extra
-          .u16(nameBytes.length)
-          .u16(localExtra.length)
-          .raw(nameBytes)
-          .raw(localExtra)
-          .done();
 
-        controller.enqueue(header);
-        const entryOffset = offset;
-        offset += BigInt(header.length);
-
-        const crc = new Crc32();
-        let size = 0n;
-        if (body) {
-          const reader = body.getReader();
-          while (true) {
-            const { done, value } = await reader.read();
-            if (done) break;
-            crc.update(value);
-            size += BigInt(value.length);
-            controller.enqueue(value);
-          }
+        const name = freeName(safeEntryName(entry.name));
+        let failure = "its bytes are missing from the store";
+        const opened = await entry.open().catch((error: unknown) => {
+          failure = `could not be read (${readableReason(error instanceof Error ? error.message : String(error)) || "unknown error"})`;
+          return null;
+        });
+        // A file whose bytes have gone is skipped, not fatal: one missing file must not abort
+        // a 2,000-file download that is otherwise fine. `continue`, never `return` — see the
+        // note on the loop above.
+        if (!opened) {
+          missing.push({ name, reason: failure });
+          continue;
         }
-        offset += size;
-
-        // ZIP64 data descriptor: 8-byte sizes, unlike the 4-byte classic form.
-        const descriptor = new ByteWriter().u32(0x08074b50).u32(crc.value).u64(size).u64(size).done();
-        controller.enqueue(descriptor);
-        offset += BigInt(descriptor.length);
+        await writeEntry(controller, name, asStream(opened), entry.modified);
+        return;
+      }
 
-        central.push({ name: nameBytes, crc: crc.value, size, offset: entryOffset, date, time, directory });
+      if (missing.length > 0 && !reported) {
+        reported = true;
+        const lines = missing.map((m) => `${m.name} — ${m.reason}`);
+        const count = missing.length === 1 ? "1 file was" : `${missing.length} files were`;
+        const text = `${count} in the selection but could not be read, so this archive does NOT contain ${missing.length === 1 ? "it" : "them"}:\n\n${lines.join("\n")}\n`;
+        await writeEntry(controller, freeName(MISSING_FILES_NAME), asStream(encoder.encode(text)), new Date());
         return;
       }