Phase 1: write side of the new core

MpqArchiveWriter builds an archive in memory and writes it when told to.

Saving is explicit (P1-2). The pre-2.0 JMpqEditor rebuilt the archive as
a side effect of close(), so a missed flag or a throw on the way out
could rewrite a file that was only meant to be read. Reading is
MpqArchive, writing is MpqArchiveWriter, and the write happens where the
caller asks for it.

Format version is chosen, not inherited (P1-6). MpqWriteOptions accepts
0 or 1 and rejects the rest at construction, rather than emitting a
208-byte header carrying 32 bytes of meaning as the old writer did for a
version 2 source.

Verbatim copies are conditional on sector size. A file keeps its stored
bytes only when the target archive keeps the source's sector size,
because a sector offset table is expressed in that sector size. This is
the bug the golden harness found in the old recompression path, encoded
as a rule the writer applies rather than a case it can forget.

MpqWriteOptions carries the P1-8 extension points: an explicit hash
table capacity and extra unused block slots, enough for protection
tooling to emit a maximised table without that being a concern of this
library. Also listfile and prefix policy, since a Warcraft III map stops
loading if its 512-byte prefix is dropped.

save(Path) stages to a sibling file and moves it into place, so an
interrupted save cannot leave a half-written archive where a working one
used to be. It cannot target an archive that is still open: a mapped file
cannot be replaced on Windows. The first version of this claimed
otherwise and the test caught it, so the javadoc now spells out the
build-then-write pattern instead.

Verification: the writer preserves 179 files across all fixtures on the
copy path, and the same 179 when re-encoding into a different sector
size, which is the case the old writer corrupted. Plus reproducible
output, explicit format selection, table capacity control, prefix
handling, atomic save, and rejection of the internal names it generates.

Self-review before pushing: block table sizing was int * int, and unlike
the hash table its capacity is caller-influenced through
extraBlockEntries, so it could overflow.

Author: Frotty

src/main/java/org/inwc3/jmpq/MpqArchive.java

@@ -387,6 +387,39 @@ private void readNames() {
         }
     }
 
+    /**
+     * The bytes preceding the archive header.
+     * <p>
+     * Warcraft III maps carry a 512-byte prefix before the archive proper, and
+     * a rebuild that means to stay loadable has to keep it.
+     *
+     * @return the prefix, empty when the archive starts at offset 0.
+     * @throws IOException if the prefix cannot be read.
+     */
+    byte[] prefixBytes() throws IOException {
+        final long length = header.headerOffset();
+        if (length <= 0) {
+            return new byte[0];
+        }
+        if (length > Integer.MAX_VALUE - 8) {
+            throw new JMpqException("Archive is preceded by " + length
+                + " bytes, too many to carry over.");
+        }
+        return source.bytes(0, (int) length);
+    }
+
+    /**
+     * The stored bytes of a file with any encryption removed, for a verbatim
+     * copy into another archive of the same sector size.
+     *
+     * @param entry the file to copy.
+     * @return exactly {@link MpqFileEntry#compressedSize()} bytes.
+     * @throws IOException if the data is damaged.
+     */
+    byte[] storedBytesDecrypted(MpqFileEntry entry) throws IOException {
+        return reader.storedBytesDecrypted(entry);
+    }
+
     /**
      * Releases the archive. For a file-backed archive the file is fully
      * released by the time this returns.