nitro-patcher 0.3.0 → 1.1.0

package/src/nitro/twl.ts

@@ -1,10 +1,13 @@
-import { hashDigest, hmacSha1, readFileSync, verifyRsaSha1 } from "#nitro-runtime";
+import { hmacSha1, readFileSync, verifyRsaSha1 } from "#nitro-runtime";
 
 import type { BinaryWriter } from "./binary";
+import { DEFAULT_MAX_SIZE } from "./binary";
 import type { Arm9Header } from "./blz";
 import { compressArm9, decompressArm9 } from "./blz";
 import type { ModcryptHeader } from "./crypto";
 import { aes128CtrCrypt, encryptSecureArea, modcryptKey } from "./crypto";
+import { Header } from "./header";
+import { CompleteTWL } from "./twl-complete";
 
 export interface TwlHeader extends ModcryptHeader {
   digest_sector_size: number;
@@ -108,9 +111,46 @@ export class TWL {
   readonly Header2Data: Buffer[] | null;
   readonly Overlays9Sha1Hmac: Buffer[];
   readonly twlEncrypted: boolean;
-  DSi9Data: Buffer;
-  DSi7Data: Buffer;
-  constructor(header: TwlHeader, overlays: readonly OverlayRange[], original: Buffer) {
+  readonly complete: CompleteTWL | undefined;
+  private dsi9Data: Buffer = Buffer.alloc(0);
+  private dsi7Data: Buffer = Buffer.alloc(0);
+  get DSi9Data(): Buffer {
+    return this.complete?.DSi9Data ?? this.dsi9Data;
+  }
+  set DSi9Data(data: Buffer) {
+    if (this.complete) this.complete.DSi9Data = data;
+    else this.dsi9Data = data;
+  }
+  get DSi7Data(): Buffer {
+    return this.complete?.DSi7Data ?? this.dsi7Data;
+  }
+  set DSi7Data(data: Buffer) {
+    if (this.complete) this.complete.DSi7Data = data;
+    else this.dsi7Data = data;
+  }
+  constructor(
+    header: TwlHeader,
+    overlays: readonly OverlayRange[],
+    original: Buffer,
+    options: { dsiMode?: "legacy" | "complete"; maxOutputSize?: number } = {},
+  ) {
+    if (options.dsiMode === "complete") {
+      if (!(header instanceof Header)) throw new TypeError("Complete DSi handling requires a parsed Header");
+      this.complete = new CompleteTWL(
+        header,
+        overlays.map((overlay) => slice(original, overlay.offset, overlay.size, "Signed ARM9 overlay")),
+        original,
+        options.maxOutputSize ?? DEFAULT_MAX_SIZE,
+      );
+      this.firstDSiHashOffset = this.complete.firstDSiHashOffset;
+      this.dsiHashSize = this.complete.dsiHashSize;
+      this.Hashtable1Data = this.complete.Hashtable1Data;
+      this.Hashtable2Data = this.complete.Hashtable2Data;
+      this.Header2Data = this.complete.Header2Data;
+      this.Overlays9Sha1Hmac = this.complete.Overlays9Sha1Hmac;
+      this.twlEncrypted = this.complete.twlEncrypted;
+      return;
+    }
     validate(header);
     const h = header;
     this.firstDSiHashOffset = (h.digest_ntr_size / h.digest_sector_size) * 20;
@@ -167,9 +207,11 @@ export class TWL {
     }
   }
   importArm9iData(data: Buffer | string, offset = 0, size?: number): void {
+    if (this.complete) return this.complete.importArm9iData(data, offset, size);
     this.DSi9Data = this.importData(data, offset, size);
   }
   importArm7iData(data: Buffer | string, offset = 0, size?: number): void {
+    if (this.complete) return this.complete.importArm7iData(data, offset, size);
     this.DSi7Data = this.importData(data, offset, size);
   }
   private importData(data: Buffer | string, offset: number, size?: number): Buffer {
@@ -181,6 +223,7 @@ export class TWL {
     return out;
   }
   updateOverlays9Sha1Hmac(arm9Data: Buffer, header: Arm9Header, overlays: readonly Buffer[]): Buffer {
+    if (this.complete) return this.complete.updateOverlays9Sha1Hmac(arm9Data, header, overlays);
     if (overlays.length !== this.Overlays9Sha1Hmac.length)
       throw new Error("Changing ARM9 overlay count is unsupported");
     const hashes = overlays.map(hash);
@@ -203,6 +246,7 @@ export class TWL {
     return unpacked.compressed ? compressArm9(unpacked.data, header, arm9Data.length - hdrptr) : unpacked.data;
   }
   writeTo(writer: BinaryWriter, h: TwlHeader): Buffer {
+    if (this.complete) throw new Error("Complete DSi serialization requires NDSFile.toBuffer()");
     validate(h);
     // Fixed DSi regions cannot be shifted safely without rewriting the header.
     if (writer.position > h.sector_hashtable_start) {
@@ -266,32 +310,22 @@ export class TWL {
   }
 }
 
-/** Refresh the digest and keep valid RSA signatures; optional no$gba hash mask. */
+/** Refresh the master digest while preserving the cartridge signature. */
 export const updateHeaderSignatures = (
   writer: BinaryWriter,
   header: SignedTwlHeader,
   originalHeader: Buffer,
-  keepOriginal: boolean,
+  _keepOriginal = true,
 ): void => {
   const signedData = Buffer.from(slice(originalHeader, 0, 0xe00, "Signed header"));
   const digest = slice(header.hmac_digest_master, 0, 20, "Master digest");
   const signature = slice(header.rsa_signature, 0, 128, "RSA signature");
   digest.copy(signedData, 0x328);
-  const valid = verifyRsaSha1(signedData, signature);
+  verifyRsaSha1(signedData, signature);
   const position = writer.position;
   writer.position = 0x328;
   writer.write(digest);
-  if (!valid) {
-    if (!keepOriginal) {
-      const mask = Buffer.alloc(128, 0xff);
-      mask[0] = 0;
-      mask[1] = 1;
-      mask[107] = 0;
-      hashDigest("sha1", signedData).copy(mask, 108);
-      header.rsa_signature = mask;
-    }
-    writer.position = 0xf80;
-    writer.write(header.rsa_signature);
-  }
+  writer.position = 0xf80;
+  writer.write(signature);
   writer.position = position;
 };

package/src/nitro-helper.ts

@@ -6,9 +6,10 @@ export { FileAllocationTable, FileNameTable, OverlayTable } from "./nitro/filesy
 export type { FatEntry, NitroFile, NitroFolder, OverlayItem } from "./nitro/filesystem";
 export { BinaryWriter } from "./nitro/binary";
 export { crc16, crc32 } from "./nitro/crc";
-export { aes128CtrCrypt, encryptSecureArea, modcryptKey } from "./nitro/crypto";
+export { aes128CtrCrypt, decryptSecureArea, encryptSecureArea, modcryptKey } from "./nitro/crypto";
 export type { ModcryptHeader } from "./nitro/crypto";
 export { compressArm9, compressBLZ, decompressArm9, decompressBLZ } from "./nitro/blz";
 export type { Arm9Header } from "./nitro/blz";
 export { TWL, updateHeaderSignatures } from "./nitro/twl";
 export type { OverlayRange, SignedTwlHeader, TwlHeader } from "./nitro/twl";
+export type { DsiCheck, DsiVerification } from "./nitro/twl-complete";

package/src/nitro-patch-helper.ts

@@ -2,9 +2,11 @@
 import { hashDigest, readFile } from "#nitro-runtime";
 
 import { bytes } from "./nitro/binary";
+import { OverlayTable } from "./nitro/filesystem";
 import { NDSFile } from "./nitro/nds-file";
+import type { DsiVerification } from "./nitro/twl-complete";
 import { decodeXdelta } from "./patch/xdelta";
-import { extractZipEntry as extractEntry, readZip } from "./patch/zip";
+import { extractZipEntry as extractEntry, readZip, readZipEntries } from "./patch/zip";
 
 export const PatchReturnValue = Object.freeze({
   SUCCESS: "SUCCESS",
@@ -19,6 +21,7 @@ export interface PatchResult {
   /** MD5 of the original input, before preprocessing. */
   inputMd5: string;
   outputMd5: string;
+  dsi?: DsiVerification;
 }
 
 export interface PatchOptions {
@@ -33,6 +36,7 @@ export interface PatchOptions {
 }
 
 export interface PatchMetadata {
+  formatVersion?: number;
   id?: string;
   author?: string;
   name?: string;
@@ -77,6 +81,13 @@ const readMetadata = (files: Map<string, Buffer>): PatchMetadata | null => {
 
   const value = metadata as Record<string, unknown>;
   const result: PatchMetadata = {};
+  if (value.formatVersion !== undefined) {
+    const version = value.formatVersion;
+    if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1)
+      throw new Error("metadata.json formatVersion must be a positive safe integer");
+    if (version !== 1 && version !== 2) throw new Error(`Unsupported XZP format version: ${version}`);
+    result.formatVersion = version;
+  }
   for (const field of ["id", "author", "name", "homepage", "version"] as const) {
     const fieldValue = value[field];
     if (fieldValue === undefined) continue;
@@ -146,10 +157,18 @@ export const readPatchInfoFile = async (patchPath: string, options: PatchOptions
 /** Apply an existing NitroPatcher ZIP package entirely in memory. */
 export const patchBuffer = (original: Uint8Array, patch: Uint8Array, options: PatchOptions = {}): PatchResult => {
   const input = bytes(original, "original ROM");
-  const patches = readZip(patch, options);
+  const entries = readZipEntries(patch, options);
+  const patches = new Map([...entries].map(([name, entry]) => [name, entry.data]));
+  const formatVersion = readMetadata(patches)?.formatVersion ?? 1;
   const inputMd5 = md5(input);
   const preprocessing = patches.get(`preprocessing/${inputMd5}.xdelta`);
-  const rom = new NDSFile(preprocessing ? decodeXdelta(input, preprocessing, options) : input, options);
+  const romOptions = { ...options, dsiMode: formatVersion === 2 ? ("complete" as const) : ("legacy" as const) };
+  const rom = new NDSFile(preprocessing ? decodeXdelta(input, preprocessing, options) : input, romOptions);
+  if (formatVersion === 2)
+    for (const name of ["arm9i.bin", "arm7i.bin"]) {
+      if ((patches.has(name) || patches.has(`xdelta/${name}`)) && !rom.hasFile(name))
+        throw new Error(`${name} requires a complete DSi-enhanced cartridge`);
+    }
   let matched = true;
   const md5File = patches.get("md5.txt");
   if (md5File) {
@@ -171,12 +190,54 @@ export const patchBuffer = (original: Uint8Array, patch: Uint8Array, options: Pa
     const replacement = delta ? decodeXdelta(rom.getFile(path), delta, options) : patches.get(normalized);
     if (replacement) rom.replaceFile(path, replacement);
   }
+  if (formatVersion === 2) {
+    for (const name of ["overarm9.bin", "overarm7.bin"])
+      if (!rom.hasFile(name)) {
+        const delta = patches.get(`xdelta/${name}`);
+        const replacement = delta ? decodeXdelta(Buffer.alloc(0), delta, options) : patches.get(name);
+        if (replacement) rom.replaceFile(name, replacement);
+      }
+    const candidates = new Map<string, { path: string; data: Buffer; delta: boolean }>();
+    for (const [name, entry] of entries) {
+      const delta = name.startsWith("xdelta/");
+      const target = delta ? name.slice(7) : name;
+      if ((!target.startsWith("data/") && !target.startsWith("overlay/")) || rom.hasFile(target)) continue;
+      if (!delta && entries.has(`xdelta/${target}`)) continue;
+      candidates.set(target, { path: delta ? entry.path.slice(7) : entry.path, data: entry.data, delta });
+    }
+    if (candidates.size && (patches.has("fnt.bin") || patches.has("xdelta/fnt.bin")))
+      throw new Error("Adding files conflicts with an fnt.bin replacement");
+    const overlayTables = new Map<string, OverlayTable>();
+    for (const name of ["overarm9.bin", "overarm7.bin"])
+      if (rom.hasFile(name)) {
+        const raw = rom.getFile(name);
+        overlayTables.set(name, new OverlayTable(raw, 0, raw.length, name === "overarm9.bin"));
+      }
+    const additions = [...candidates.values()].sort((a, b) => Buffer.compare(Buffer.from(a.path), Buffer.from(b.path)));
+    for (const entry of additions) {
+      const content = entry.delta ? decodeXdelta(Buffer.alloc(0), entry.data, options) : entry.data;
+      if (entry.path.toLowerCase().startsWith("overlay/")) {
+        const match = /^overlay\/overlay(7)?_(\d{4,})\.bin$/i.exec(entry.path);
+        const overlayId = match?.[2];
+        const arm9 = !match?.[1];
+        if (!overlayId || String(Number(overlayId)).padStart(4, "0") !== overlayId)
+          throw new Error(`Invalid overlay path: ${entry.path}`);
+        const name = arm9 ? "overarm9.bin" : "overarm7.bin";
+        const table = overlayTables.get(name);
+        if (!table) throw new Error(`New overlay requires ${name}: ${entry.path}`);
+        const metadata = table.entries.find((item) => item.overlayId === Number(overlayId));
+        if (!metadata) throw new Error(`New overlay is missing its table entry: ${entry.path}`);
+        rom.addOverlay(arm9, metadata, content);
+      } else rom.addFile(entry.path, content);
+    }
+  }
   const buffer = rom.toBuffer();
   return {
     buffer,
     returnValue: matched ? PatchReturnValue.SUCCESS : PatchReturnValue.MD5_MISMATCH,
     inputMd5,
     outputMd5: md5(buffer),
+    ...(formatVersion === 2 && rom.header.unitCode === 2 && { dsi: new NDSFile(buffer, romOptions).verifyDsi() }),
   };
 };
 
@@ -202,5 +263,7 @@ export const PatchHelper = Object.freeze({
   readPatchReadme,
   readPatchReadmeFile,
 });
+export { createPatch } from "./patch/create";
+export type { CreatePatchOptions, CreatePatchResult } from "./patch/create";
 export { decodeXdelta } from "./patch/xdelta";
 export type { XdeltaOptions } from "./patch/xdelta";

package/src/patch/create.ts

@@ -0,0 +1,341 @@
+import { encode } from "@limrun/xdelta3-wasm";
+import { zipSync } from "fflate";
+
+import { hashDigest } from "#nitro-runtime";
+
+import { decodeXdelta } from "./xdelta";
+import { bytes } from "../nitro/binary";
+import { crc16 } from "../nitro/crc";
+import { decryptSecureArea, encryptSecureArea } from "../nitro/crypto";
+import type { NitroFolder } from "../nitro/filesystem";
+import { Header } from "../nitro/header";
+import { NDSFile } from "../nitro/nds-file";
+import { patchBuffer } from "../nitro-patch-helper";
+import type { PatchMetadata, PatchOptions } from "../nitro-patch-helper";
+
+export interface CreatePatchOptions extends PatchOptions {
+  metadata?: Omit<PatchMetadata, "formatVersion">;
+  readme?: string;
+}
+
+export interface CreatePatchResult {
+  buffer: Uint8Array<ArrayBuffer>;
+  changedFiles: number;
+  warnings: string[];
+}
+
+const normalizePath = (path: string): string => path.replaceAll("\\", "/").toLowerCase();
+const listFiles = (rom: NDSFile) => new Map(rom.listFiles().map((file) => [normalizePath(file.path), file]));
+const listDirectories = (folder: NitroFolder, prefix = "data"): string[] =>
+  [prefix, ...folder.folders.flatMap((child) => listDirectories(child, `${prefix}/${child.name}`))].sort();
+const getUnnamedFiles = (rom: NDSFile): Buffer[] => {
+  const namedIds = new Set(
+    rom
+      .listFiles()
+      .filter((file) => /^(data|overlay)\//i.test(file.path))
+      .map((file) => file.id),
+  );
+  return rom.fatTable.entries
+    .filter((entry) => !namedIds.has(entry.id))
+    .map((entry) => rom.original.subarray(entry.offset, entry.offset + entry.size));
+};
+
+// Repacking assigns physical locations, capacities and derived checksums.
+const normalizeHeader = (rom: NDSFile): Buffer => {
+  const header = new Header(rom.getFile("header.bin"));
+  header.size = 0x20000;
+  for (const field of [
+    "ARM9romOffset",
+    "ARM9size",
+    "ARM7romOffset",
+    "ARM7size",
+    "FNToffset",
+    "FNTsize",
+    "FAToffset",
+    "FATsize",
+    "ARM9overlayOffset",
+    "ARM9overlaySize",
+    "ARM7overlayOffset",
+    "ARM7overlaySize",
+    "bannerOffset",
+    "secureCRC16",
+    "ROMsize",
+    "logoCRC16",
+    "headerCRC16",
+  ] as const)
+    header[field] = 0;
+  if (header.unitCode === 2) {
+    for (const field of [
+      "ntr_region_end",
+      "twl_region_start",
+      "dsi9_rom_offset",
+      "dsi7_rom_offset",
+      "digest_ntr_start",
+      "digest_ntr_size",
+      "digest_twl_start",
+      "digest_twl_size",
+      "sector_hashtable_start",
+      "sector_hashtable_size",
+      "block_hashtable_start",
+      "block_hashtable_size",
+      "total_rom_size",
+      "modcrypt1_start",
+      "modcrypt1_size",
+      "modcrypt2_start",
+      "modcrypt2_size",
+    ] as const)
+      header[field] = 0;
+    for (const field of [
+      "hmac_arm9",
+      "hmac_arm7",
+      "hmac_digest_master",
+      "hmac_icon_title",
+      "hmac_arm9i",
+      "hmac_arm7i",
+      "hmac_arm9_no_secure",
+      "rsa_signature",
+    ] as const)
+      header[field] = Buffer.alloc(header[field].length);
+  }
+  return header.raw;
+};
+
+const compareContent = (actual: Buffer, expected: Buffer, path: string, warnings: string[]): void => {
+  if (!actual.equals(expected)) warnings.push(`重建内容与修改后的 ROM 不同：${path}`);
+};
+
+const errorMessage = (reason: unknown): string => (reason instanceof Error ? reason.message : String(reason));
+
+const parseRom = (input: Buffer, label: string, warnings: string[]): NDSFile => {
+  try {
+    const rom = new NDSFile(input, { dsiMode: "complete" });
+    rom.listFiles();
+    return rom;
+  } catch (reason) {
+    try {
+      const rom = new NDSFile(input);
+      rom.listFiles();
+      warnings.push(`${label} 使用常规模式解析：${errorMessage(reason)}`);
+      return rom;
+    } catch (error) {
+      throw new Error(`无法解析${label}：${errorMessage(error)}`, { cause: error });
+    }
+  }
+};
+
+const createDelta = async (before: Buffer, after: Buffer): Promise<Buffer> => {
+  const chunks: Buffer[] = [];
+  async function* targetChunks() {
+    yield after;
+  }
+  for await (const chunk of encode(targetChunks(), {
+    size: before.length,
+    read(offset, into) {
+      const part = before.subarray(offset, offset + into.length);
+      into.set(part);
+      return part.length;
+    },
+  }))
+    chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks);
+};
+
+const verifyContent = (actual: NDSFile, expected: NDSFile, arm9: Buffer, warnings: string[]): void => {
+  const actualFiles = listFiles(actual);
+  const expectedFiles = listFiles(expected);
+  if ([...actualFiles.keys()].sort().join("\n") !== [...expectedFiles.keys()].sort().join("\n"))
+    warnings.push("重建 ROM 的文件路径集合与修改后的 ROM 不同。");
+  const actualDirectories = new Set(listDirectories(actual.data));
+  const expectedDirectories = new Set(listDirectories(expected.data));
+  for (const path of expectedDirectories)
+    if (!actualDirectories.has(path)) {
+      if ([...expectedFiles.keys()].some((name) => name.startsWith(normalizePath(`${path}/`))))
+        warnings.push(`重建 ROM 缺少目录：${path}`);
+      else warnings.push(`新增空目录已忽略：${path}`);
+    }
+  for (const path of actualDirectories)
+    if (!expectedDirectories.has(path)) {
+      if ([...actualFiles.keys()].some((name) => name.startsWith(normalizePath(`${path}/`))))
+        warnings.push(`重建 ROM 保留了原始目录：${path}`);
+      else warnings.push(`已保留原始 ROM 的空目录：${path}`);
+    }
+  for (const [path, file] of expectedFiles) {
+    if (["header.bin", "fnt.bin", "fat.bin", "banner.bin", "overarm9.bin", "overarm7.bin"].includes(path)) continue;
+    if (!actualFiles.has(path)) continue;
+    let content = path === "arm9.bin" ? Buffer.from(arm9) : expected.getFile(file.path);
+    if (path === "arm9.bin" && expected.header.unitCode === 2) {
+      const plain = expected.header.decrypted ? content : decryptSecureArea(expected.header.gameCode, content);
+      plain.writeUInt16LE(crc16(plain.subarray(0x10, 0x800)), 0xe);
+      content = expected.header.decrypted ? plain : encryptSecureArea(expected.header.gameCode, plain);
+    }
+    compareContent(actual.getFile(file.path), content, file.path, warnings);
+  }
+  compareContent(actual.banner.toBuffer(), expected.banner.toBuffer(), "banner.bin", warnings);
+  compareContent(normalizeHeader(actual), normalizeHeader(expected), "header.bin", warnings);
+  compareContent(actual.header.dlp_signature, expected.header.dlp_signature, "Download Play 签名", warnings);
+  for (const [left, right] of [
+    [actual.overlay9Table, expected.overlay9Table],
+    [actual.overlay7Table, expected.overlay7Table],
+  ]) {
+    if (left.entries.length !== right.entries.length) warnings.push("重建 ROM 的覆盖模块数量与修改后的 ROM 不同。");
+    for (const entry of right.entries) {
+      const other = left.entries.find((item) => item.overlayId === entry.overlayId);
+      if (!other) {
+        warnings.push(`重建 ROM 缺少覆盖模块：${entry.overlayId}`);
+        continue;
+      }
+      for (const field of [
+        "ramAddress",
+        "ramSize",
+        "bssSize",
+        "staticInitialiserStartAddress",
+        "staticInitialiserEndAddress",
+        "reserved",
+      ] as const)
+        if (other[field] !== entry[field])
+          warnings.push(`重建覆盖模块 ${entry.overlayId} 的 ${field} 与修改后的 ROM 不同。`);
+    }
+  }
+  const actualUnnamed = getUnnamedFiles(actual);
+  const expectedUnnamed = getUnnamedFiles(expected);
+  if (actualUnnamed.length !== expectedUnnamed.length)
+    warnings.push("重建 ROM 的未命名 FAT 项数量与修改后的 ROM 不同。");
+  actualUnnamed.forEach((content, index) => {
+    if (expectedUnnamed[index]) compareContent(content, expectedUnnamed[index], `未命名 FAT 项 ${index}`, warnings);
+  });
+  if (actual.header.unitCode === 2)
+    for (const [name, check] of Object.entries(actual.verifyDsi()))
+      if (check.status === "invalid") warnings.push(`重建 ROM 的 DSi 校验结果为 invalid：${name}`);
+};
+
+const verifyPatch = (
+  input: Buffer,
+  archive: Uint8Array,
+  target: NDSFile,
+  arm9: Buffer,
+  options: PatchOptions,
+  warnings: string[],
+): boolean => {
+  let output: Buffer;
+  try {
+    output = patchBuffer(input, archive, options).buffer;
+  } catch (reason) {
+    warnings.push(`补丁应用检查未完成：${errorMessage(reason)}`);
+    return false;
+  }
+  try {
+    verifyContent(parseRom(output, "重建 ROM", warnings), target, arm9, warnings);
+  } catch (reason) {
+    warnings.push(`补丁数据核对未完成：${errorMessage(reason)}`);
+  }
+  return true;
+};
+
+/** Create an XZP; differences and application checks are returned as warnings. */
+export const createPatch = async (
+  original: Uint8Array,
+  modified: Uint8Array,
+  options: CreatePatchOptions = {},
+): Promise<CreatePatchResult> => {
+  const input = bytes(original, "original ROM");
+  const targetBytes = bytes(modified, "modified ROM");
+  const warnings: string[] = [];
+  const source = parseRom(input, "原始 ROM", warnings);
+  const target = parseRom(targetBytes, "修改后的 ROM", warnings);
+  let preprocessing = false;
+  if (source.header.gameCode !== target.header.gameCode)
+    warnings.push(`两个 ROM 的游戏代码不同：${source.header.gameCode} / ${target.header.gameCode}`);
+  if (source.header.unitCode !== target.header.unitCode)
+    warnings.push(`两个 ROM 的 unitCode 不同：${source.header.unitCode} / ${target.header.unitCode}`);
+  if (source.header.ROMversion !== target.header.ROMversion)
+    warnings.push(`两个 ROM 的修订版本不同：${source.header.ROMversion} / ${target.header.ROMversion}`);
+  if (source.header.gameCode !== target.header.gameCode || source.header.unitCode !== target.header.unitCode)
+    preprocessing = true;
+  const sourceFiles = listFiles(source);
+  const targetFiles = listFiles(target);
+  const headerChanged = !normalizeHeader(source).equals(normalizeHeader(target));
+  const sourceArm9 = source.getFile("arm9.bin");
+  const targetArm9 = target.getFile("arm9.bin");
+  const sourcePostData = sourceArm9.subarray(source.header.ARM9size);
+  const targetPostData = targetArm9.subarray(target.header.ARM9size);
+  if (!sourcePostData.equals(targetPostData)) warnings.push("两个 ROM 的 ARM9 尾部记录不同。");
+  for (const [label, rom, entries] of [
+    ["原始 ROM", source, sourceFiles],
+    ["修改后的 ROM", target, targetFiles],
+  ] as const) {
+    const file = entries.get("arm9.bin")!;
+    const end = file.offset + file.size;
+    if (rom.header.nitrocode && rom.original.subarray(end, end + 4).equals(Buffer.from("2106c0de", "hex")))
+      warnings.push(`${label} 的 ARM9 含有额外尾部记录。`);
+  }
+  const targetProgram = targetArm9.subarray(0, target.header.ARM9size);
+  const arm9 =
+    sourcePostData.length && targetProgram.subarray(-sourcePostData.length).equals(sourcePostData)
+      ? targetProgram
+      : Buffer.concat([targetProgram, sourcePostData]);
+  const removed = [...sourceFiles.keys()].filter((path) => !targetFiles.has(path));
+  if (removed.length) {
+    warnings.push(`修改后的 ROM 缺少原始 ROM 中的 ${removed.length} 个文件。`);
+    preprocessing = true;
+  }
+  const sourceUnnamed = getUnnamedFiles(source);
+  const targetUnnamed = getUnnamedFiles(target);
+  if (
+    sourceUnnamed.length !== targetUnnamed.length ||
+    sourceUnnamed.some((content, index) => !content.equals(targetUnnamed[index] ?? Buffer.alloc(0)))
+  ) {
+    warnings.push("两个 ROM 的未命名 FAT 数据不同。");
+    preprocessing = true;
+  }
+  const entries: Record<string, Uint8Array> = {};
+  let changedFiles = 0;
+  for (const [path, file] of targetFiles) {
+    if (path === "fnt.bin" || path === "fat.bin") continue;
+    if (path === "header.bin" && !headerChanged) continue;
+    const before = sourceFiles.has(path) ? source.getFile(file.path) : Buffer.alloc(0);
+    const after = path === "arm9.bin" ? arm9 : target.getFile(file.path);
+    if (sourceFiles.has(path) && before.equals(after)) continue;
+    if (!sourceFiles.has(path) && !/^(data|overlay)\//.test(path) && !/^overarm[97]\.bin$/.test(path))
+      warnings.push(`新增系统文件：${file.path}`);
+    try {
+      const delta = await createDelta(before, after);
+      if (decodeXdelta(before, delta, options).equals(after)) entries[`xdelta/${file.path}`] = delta;
+      else {
+        warnings.push(`文件差分解码内容不同，已保存完整替换内容：${file.path}`);
+        entries[file.path] = after;
+      }
+    } catch (reason) {
+      warnings.push(`文件差分检查未完成，已保存完整替换内容：${file.path}：${errorMessage(reason)}`);
+      entries[file.path] = after;
+    }
+    changedFiles++;
+  }
+  const metadata: PatchMetadata = { ...options.metadata, formatVersion: 2 };
+  const inputMd5 = hashDigest("md5", input).toString("hex");
+  entries["metadata.json"] = Buffer.from(JSON.stringify(metadata, null, 2));
+  entries["md5.txt"] = Buffer.from(inputMd5);
+  entries["readme.md"] = Buffer.from(options.readme ?? "");
+  let archive = zipSync(entries, { level: 9 });
+  if (!preprocessing) preprocessing = !verifyPatch(input, archive, target, arm9, options, warnings);
+  if (preprocessing) {
+    try {
+      const delta = await createDelta(input, targetBytes);
+      const formatVersion = target.header.unitCode & 2 && !target.twl?.complete ? 1 : 2;
+      archive = zipSync(
+        {
+          [`preprocessing/${inputMd5}.xdelta`]: delta,
+          "metadata.json": Buffer.from(JSON.stringify({ ...metadata, formatVersion }, null, 2)),
+          "md5.txt": entries["md5.txt"],
+          "readme.md": entries["readme.md"],
+        },
+        { level: 9 },
+      );
+      changedFiles = 1;
+      warnings.push("补丁使用整份 ROM 的预处理差分保存修改。");
+      verifyPatch(input, archive, target, targetArm9, options, warnings);
+    } catch (reason) {
+      warnings.push(`预处理差分生成未完成，已保留按文件补丁包：${errorMessage(reason)}`);
+    }
+  }
+  return { buffer: new Uint8Array(archive), changedFiles, warnings };
+};