cursedbelt-server 4.45.0 → 4.46.0

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.0",
 	"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/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;
       }