feat(artifacts): inspect classic iNES container regions

This commit is contained in:
64579525
2026-10-12 15:17:50 +08:00
parent b3dec005bc
commit 414307c9d5
25 changed files with 1032 additions and 14 deletions
+20 -5
View File
@@ -1,5 +1,9 @@
import { constants, type Stats } from "node:fs";
import { createHash } from "node:crypto";
import {
nesContainerFormat,
parseInesLayout,
} from "../domain/inesContainer.js";
import {
access,
lstat,
@@ -276,19 +280,30 @@ const detectArtifactFormat = async (
> => {
throwIfTargetResolutionCancelled(signal);
const lower = path.toLowerCase();
const magic = Buffer.alloc(8);
const magic = Buffer.alloc(16);
const observed = await handle.read(magic, 0, magic.length, 0);
throwIfTargetResolutionCancelled(signal);
if (
observed.bytesRead === 8 &&
magic.equals(Buffer.from([0, 0x61, 0x73, 0x6d, 1, 0, 0, 0]))
observed.bytesRead >= 8 &&
magic.subarray(0, 8).equals(Buffer.from([0, 0x61, 0x73, 0x6d, 1, 0, 0, 0]))
)
throw new BinaryTargetError(
path,
"WebAssembly v1 artifacts are not supported by the native opening route",
{ constraint: "wasm_requires_static_inspection" },
);
if (hasZipSignature(magic.subarray(0, observed.bytesRead))) {
const prefix = magic.subarray(0, observed.bytesRead);
const nesFormat = nesContainerFormat(prefix);
if (nesFormat !== undefined) {
const parsed = parseInesLayout(prefix, (await handle.stat()).size);
throwIfTargetResolutionCancelled(signal);
if (!parsed.ok)
throw new BinaryTargetError(path, parsed.error, {
constraint: "file_format_rejected",
});
return "ines";
}
if (hasZipSignature(prefix)) {
// The HarmonyOS App Pack suffix `.app` is a root-input concept; a nested
// ZIP member ending in `.app` keeps the generic zip classification.
if (lower.endsWith(".app")) return "app-pack";
@@ -339,7 +354,7 @@ const isArchiveFormat = (
| "raw-binary"
>,
): format is Extract<BinaryTarget, { kind: "archive" }>["format"] =>
isZipPackageFormat(format) || ["asar", "dmg", "pkg"].includes(format);
isZipPackageFormat(format) || ["asar", "ines", "dmg", "pkg"].includes(format);
const sha256Handle = async (
handle: FileHandle,
+2 -2
View File
@@ -32,7 +32,7 @@ import {
} from "../domain/analysisErrorCore.js";
import { ArtifactOperationError } from "../domain/artifactOperationError.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
import { interfaceBuilderLimitsSchema } from "../domain/apple/interfaceBuilderGraph.js";
import { err, ok, type Result } from "../domain/result.js";
import { ArtifactReaderFailure } from "./ArtifactReader.js";
@@ -349,7 +349,7 @@ class ArtifactClient implements AnalysisClient {
const inventoryEvidence = createEvidence(subject, ARTIFACT_GRAPH_PROVIDER, {
operation: "inventory_artifact",
parameters: inventoryParameters,
result: inventory,
result: jsonValueSchema.parse(inventory),
rawResult: null,
limitations: inventory.limitations,
// The nested inventory already names every occurrence's logical path.
+1 -1
View File
@@ -92,7 +92,7 @@ export const sameArtifactEntry = (
/** Read-only adapter over one directory, archive, or virtual container. */
export interface ArtifactReader {
readonly format: "directory" | ZipPackageFormat | "asar" | "file";
readonly format: "directory" | ZipPackageFormat | "asar" | "ines" | "file";
entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry>;
open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable>;
provenance(): readonly ArtifactCommand[];
+192
View File
@@ -0,0 +1,192 @@
import { createHash } from "node:crypto";
import { lstat } from "node:fs/promises";
import { Readable } from "node:stream";
import {
parseInesLayout,
type InesInventory,
type InesLayout,
} from "../domain/inesContainer.js";
import type { ArtifactCommand } from "../domain/artifactGraph.js";
import {
sameRegularFileState,
type StableRegularFileDescriptor,
} from "../filesystem/RegularFile.js";
import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
import {
ArtifactReaderFailure,
copyArtifactEntry,
sameArtifactEntry,
type ArtifactEntry,
type ArtifactReader,
} from "./ArtifactReader.js";
import { abortIfNeeded } from "./ArtifactHash.js";
import { streamChunkToBuffer } from "./StreamBytes.js";
export const INES_LIMITATION =
"Classic iNES file regions are observed; mapper execution, CPU bank mappings, CHR-RAM contents, 6502 analysis and emulator behavior are not observed. Trailing bytes are retained without interpretation. NES 2.0 and UNIF are unsupported.";
/** Read positional regions from a descriptor retained by the artifact resource scope. */
export class InesArtifactReader implements ArtifactReader {
readonly format = "ines" as const;
readonly #entries = new Map<string, ArtifactEntry>();
#layout: InesLayout | undefined;
#closed = false;
constructor(
private readonly path: string,
private readonly source: StableRegularFileDescriptor,
private readonly ownedSource?: OwnedFileHandle,
) {}
async *entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry> {
abortIfNeeded(signal);
await this.#verifySource();
const prefix = Buffer.alloc(16);
const { bytesRead } = await this.source.handle.read(prefix, 0, 16, 0);
abortIfNeeded(signal);
const parsed = parseInesLayout(
prefix.subarray(0, bytesRead),
this.source.initial.size,
);
if (!parsed.ok) throw new ArtifactReaderFailure("format", parsed.error);
this.#layout = parsed.value;
await this.#verifySource();
this.#entries.clear();
for (const region of parsed.value.regions) {
abortIfNeeded(signal);
const entry: ArtifactEntry = {
path: region.path,
kind: "file",
declaredSize: region.length,
compressedSize: null,
executable: false,
encrypted: false,
byteOffset: region.offset,
declaredSha256: null,
unpacked: false,
limitations: [],
adapterKey: region.path,
};
this.#entries.set(entry.adapterKey, copyArtifactEntry(entry));
yield entry;
}
}
async open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable> {
abortIfNeeded(signal);
const produced = this.#entries.get(entry.adapterKey);
if (produced === undefined || !sameArtifactEntry(entry, produced))
throw new ArtifactReaderFailure(
"integrity",
"iNES region does not match this reader's inventory",
);
await this.#verifySource();
const offset = produced.byteOffset;
const size = produced.declaredSize;
if (offset === null || size === null || size <= 0)
throw new ArtifactReaderFailure("integrity", "Invalid iNES region range");
const stream = readFileHandleChunks(this.source.handle, {
start: offset,
end: offset + size - 1,
signal,
});
const verify = () => this.#verifySource();
return Readable.from(
(async function* () {
let bytes = 0;
try {
for await (const raw of stream) {
abortIfNeeded(signal);
const chunk = streamChunkToBuffer(raw);
bytes += chunk.length;
yield chunk;
}
if (bytes !== size)
throw new ArtifactReaderFailure(
"integrity",
"Truncated iNES region",
);
await verify();
} catch (cause: unknown) {
abortIfNeeded(signal);
if (cause instanceof ArtifactReaderFailure) throw cause;
throw new ArtifactReaderFailure("io", "Could not read iNES region", {
cause,
});
}
})(),
{ objectMode: false },
);
}
/** Hash actual ordered region bytes; per-region digests alone cannot prove concatenation. */
async verifyReconstruction(
expectedSha256: string,
signal?: AbortSignal,
): Promise<InesInventory> {
const layout = this.#layout;
if (layout === undefined || this.#entries.size !== layout.regions.length)
throw new ArtifactReaderFailure("integrity", "Incomplete iNES inventory");
const hash = createHash("sha256");
let bytes = 0;
for (const region of layout.regions) {
if (region.offset !== bytes)
throw new ArtifactReaderFailure(
"integrity",
"Noncontiguous iNES regions",
);
const entry = this.#entries.get(region.path);
if (entry === undefined)
throw new ArtifactReaderFailure("integrity", "Missing iNES region");
for await (const raw of await this.open(entry, signal)) {
const chunk = streamChunkToBuffer(raw);
hash.update(chunk);
bytes += chunk.length;
}
}
const sha256 = hash.digest("hex");
if (bytes !== this.source.initial.size || sha256 !== expectedSha256)
throw new ArtifactReaderFailure(
"integrity",
"iNES reconstruction differs from the source",
);
return {
header: layout.header,
reconstruction: {
region_order: layout.regions.map(({ path }) => path),
bytes,
sha256,
verified: true,
},
};
}
provenance(): readonly ArtifactCommand[] {
return [];
}
close(): Promise<void> {
// Inventory borrows its admitting scope's descriptor. Extraction owns its
// separately opened descriptor and retains this reader if close fails.
this.#closed = true;
return this.ownedSource?.close() ?? Promise.resolve();
}
async #verifySource(): Promise<void> {
if (this.#closed)
throw new ArtifactReaderFailure("unavailable", "iNES reader is closed");
const [opened, selected] = await Promise.all([
this.source.handle.stat(),
lstat(this.path),
]);
if (
!sameRegularFileState(this.source.initial, opened) ||
!sameRegularFileState(this.source.initial, selected)
)
throw new ArtifactReaderFailure(
"integrity",
"iNES source changed during reading",
);
}
}
+29 -1
View File
@@ -3,6 +3,8 @@ import { lstat, realpath } from "node:fs/promises";
import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
import { digestCanonicalValue } from "../../domain/canonicalDigest.js";
import { AsarArtifactReader } from "../AsarArtifactReader.js";
import { InesArtifactReader } from "../InesArtifactReader.js";
import { openRootArtifact } from "../inventory/hashStableRootArtifact.js";
import {
ArtifactPathRegistry,
normalizeArtifactPath,
@@ -421,6 +423,7 @@ const requireExtractableFormat = async (
if (
!directory &&
format !== "asar" &&
format !== "ines" &&
!isMachOFormat(format) &&
!isZipFormat(format)
)
@@ -436,13 +439,38 @@ const createReader = async (
path: string,
input: Pick<
ArtifactExtractionInput,
"inputPath" | "inputFormat" | "environment"
"inputPath" | "inputFormat" | "environment" | "resourceScope"
>,
): Promise<ArtifactReader> => {
const format = input.inputFormat;
if (await requireExtractableFormat(path, input))
return new DirectoryArtifactReader(path);
if (format === "asar") return new AsarArtifactReader(path);
if (format === "ines") {
const owner = await openRootArtifact(path, input.resourceScope);
try {
return new InesArtifactReader(
path,
{
handle: owner.handle,
initial: await owner.handle.stat(),
},
owner,
);
} catch (cause: unknown) {
const attempt = await input.resourceScope.release({
kind: "file-handle",
handle: owner,
resource: `iNES source ${path}`,
});
if (attempt.kind === "failed")
throw ArtifactReaderFailure.withCleanup(
cause,
ArtifactReaderFailure.cleanupObservation(attempt.cause, path),
);
throw cause;
}
}
if (isZipFormat(format)) return new ZipArtifactReader(path, format);
return new MachOSliceArtifactReader(path, input.environment);
};
@@ -19,6 +19,10 @@ import {
type ZipPackageFormat,
} from "../../domain/zipPackageFormat.js";
import { mzWindowsHeaderOffset, parseDosMzHeader } from "../../domain/dosMz.js";
import {
nesContainerFormat,
parseInesLayout,
} from "../../domain/inesContainer.js";
/** Mutable internal occurrence used until root-bound IDs are known. */
export interface MutableOccurrence {
@@ -219,7 +223,7 @@ export const rootOccurrenceFor = (
artifact_kind:
metadata.format === "directory" ||
isZipPackageFormat(metadata.format) ||
["asar", "dmg", "pkg"].includes(metadata.format)
["asar", "ines", "dmg", "pkg"].includes(metadata.format)
? "container"
: artifactRoleForFormat(metadata.path, metadata.format).kind,
artifact_format: metadata.format,
@@ -419,6 +423,7 @@ const artifactRoleForFormat = (
format: zipPackageFormatForPath(path) ?? format,
};
if (format === "plist") return { kind: "plist", format };
if (format === "ines") return { kind: "container", format };
return {
kind: ["native-addon", "dynamic-library"].includes(byPath.kind)
? byPath.kind
@@ -432,6 +437,13 @@ export const classifyArtifactBytes = (
prefix: Buffer,
fileSize = prefix.length,
): ArtifactNode["format"] => {
// A header-only region has the signature but not the declared cartridge
// extent. Keep it as a file instead of inventing another container.
if (
nesContainerFormat(prefix) === "ines" &&
parseInesLayout(prefix, fileSize).ok
)
return "ines";
if (hasZipSignature(prefix)) return "zip";
if (prefix.subarray(0, 8).equals(Buffer.from("bplist00"))) return "plist";
if (prefix.length >= 4) {
+13 -2
View File
@@ -5,6 +5,10 @@ import type { StableRegularFileDescriptor } from "../../filesystem/RegularFile.j
import type { OwnedFileHandle } from "../../filesystem/OwnedFileHandle.js";
import { classifyArtifactContent } from "./ArtifactGraphConstruction.js";
import {
nesContainerFormat,
parseInesLayout,
} from "../../domain/inesContainer.js";
import { ARTIFACT_CLASSIFICATION_PREFIX_BYTES } from "../ArtifactHash.js";
import type { ArtifactOccurrence } from "../../domain/artifactGraph.js";
import {
@@ -71,7 +75,7 @@ export const classifyAndHashRoot = async (
});
};
/** Classify a root and retain its admitted ZIP descriptor for child inventory. */
/** Classify a root and retain its admitted container descriptor for child inventory. */
export const classifyAndHashRootForInventory = async (
path: string,
directory: boolean,
@@ -112,7 +116,9 @@ export const classifyAndHashRootForInventory = async (
options.signal,
);
const retainSource =
isZipPackageFormat(format) || format === "mach-o-universal";
isZipPackageFormat(format) ||
format === "mach-o-universal" ||
format === "ines";
outcome = {
kind: "completed",
value: {
@@ -148,6 +154,11 @@ const classifyRootFormat = async (
const magic = Buffer.alloc(ARTIFACT_CLASSIFICATION_PREFIX_BYTES);
const observed = await handle.read(magic, 0, magic.length, 0);
const prefix = magic.subarray(0, observed.bytesRead);
if (nesContainerFormat(prefix) !== undefined) {
const parsed = parseInesLayout(prefix, (await handle.stat()).size);
if (!parsed.ok) throw new ArtifactReaderFailure("format", parsed.error);
return "ines";
}
const lower = path.toLowerCase();
if (hasZipSignature(prefix)) return zipRootPackageFormat(lower);
if (
+10
View File
@@ -1,4 +1,6 @@
import { AsarArtifactReader } from "../AsarArtifactReader.js";
import { InesArtifactReader, INES_LIMITATION } from "../InesArtifactReader.js";
import { ArtifactReaderFailure } from "../ArtifactReader.js";
import type { ArtifactReader } from "../ArtifactReader.js";
import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
import { MachOSliceArtifactReader } from "../MachOSliceArtifactReader.js";
@@ -20,6 +22,13 @@ export const createReader = (
if (isZipPackageFormat(format))
return new ZipArtifactReader(path, format, undefined, rootSource);
switch (format) {
case "ines":
if (rootSource === undefined)
throw new ArtifactReaderFailure(
"integrity",
"iNES inventory requires its admitted source descriptor",
);
return new InesArtifactReader(path, rootSource);
case "directory":
return new DirectoryArtifactReader(path);
case "asar":
@@ -40,6 +49,7 @@ export const inventoryLimitations = (
format: ArtifactOccurrence["artifact_format"],
reader: ArtifactReader | undefined,
): string[] => {
if (format === "ines") return [INES_LIMITATION];
if (reader !== undefined)
return isZipPackageFormat(reader.format)
? [ZIP_NON_ENTRY_TAIL_LIMITATION]
+4
View File
@@ -2,6 +2,7 @@ import type { ArtifactInventorySnapshot } from "../../domain/artifactInventorySn
import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
import { AsarArtifactReader } from "../AsarArtifactReader.js";
import { InesArtifactReader } from "../InesArtifactReader.js";
import { lstat } from "node:fs/promises";
import type { Stats } from "node:fs";
@@ -270,6 +271,9 @@ const buildInventorySnapshot = async (
});
return {
manifest,
...(reader instanceof InesArtifactReader && rootDigest !== null
? { ines: await reader.verifyReconstruction(rootDigest.sha256, signal) }
: {}),
nodes: orderedNodes,
occurrences: orderedOccurrences,
edges: orderedEdges,
+1 -1
View File
@@ -67,7 +67,7 @@ const artifact = <
export const ARTIFACT_TOOL_CONTRACTS = [
artifact(
"inspect_artifact",
"Inspect an active archive or application package in one call. Returns the complete content-addressed artifact graph once, as the nested inventory Evidence, with root and integrity observations, integrity contradictions, hypotheses, unexplored branches, limitations, and next probes inline. Read-only DMG mounting is used automatically on supported macOS hosts. Integrity mismatches fail by default; record-and-continue keeps mismatches explicitly untrusted. It does not extract files; use extract_artifact to materialize its regular contents.",
"Inspect an active archive or application package in one call. Returns the complete content-addressed artifact graph once, as the nested inventory Evidence, with root and integrity observations, integrity contradictions, hypotheses, unexplored branches, limitations, and next probes inline. Classic iNES includes header facts, PRG/CHR file-region hashes and byte-exact reconstruction evidence; mapper execution and CPU bank mappings remain unobserved. Read-only DMG mounting is used automatically on supported macOS hosts. Integrity mismatches fail by default; record-and-continue keeps mismatches explicitly untrusted. It does not extract files; use extract_artifact to materialize its regular contents.",
artifactInventoryInputSchema,
),
artifact(
@@ -65,6 +65,7 @@ export const targetFormatSchema = z.enum([
"msix",
"appx",
"asar",
"ines",
"dmg",
"pkg",
"plist",
+1
View File
@@ -66,6 +66,7 @@ const formatSchema = z.enum([
"hsp",
"app-pack",
"asar",
"ines",
"dmg",
"pkg",
"plist",
+4
View File
@@ -1,5 +1,6 @@
import { z } from "zod";
import { prefixedDigestSchema } from "./../domain/digests.js";
import { inesInventorySchema } from "./inesContainer.js";
const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/u);
const artifactIdSchema = prefixedDigestSchema("art");
@@ -42,6 +43,7 @@ const artifactFormatSchema = z.enum([
"zip",
"pkg",
"asar",
"ines",
"javascript-bundle",
"source-map",
"mach-o-universal",
@@ -69,6 +71,7 @@ const artifactFormatSchema = z.enum([
/** Formats established from bytes or a virtual directory tree, independent of path roles. */
const artifactContentFormatSchema = artifactFormatSchema.extract([
"ines",
"zip",
"mach-o-universal",
"mach-o",
@@ -196,6 +199,7 @@ export const artifactInventoryResultSchema = z.object({
edges: z.array(artifactEdgeSchema),
provenance: z.array(artifactCommandSchema),
integrity_contradictions: z.array(integrityContradictionSchema).default([]),
ines: inesInventorySchema.optional(),
limitations: z.array(z.string()),
});
+22 -1
View File
@@ -16,7 +16,12 @@ const artifactIdSchema = prefixedDigestSchema("art");
const inspectionObservationSchema = z.strictObject({
observation_id: prefixedDigestSchema("aio"),
kind: z.enum(["root-manifest", "integrity"]),
kind: z.enum([
"root-manifest",
"integrity",
"container-header",
"reconstruction",
]),
subject: textSchema,
value: jsonValueSchema,
evidence_id: evidenceIdSchema,
@@ -209,6 +214,22 @@ const allObservations = (
...inventory.integrity_contradictions.map((value) =>
observation("integrity", value.contradiction_id, value, evidenceId),
),
...(inventory.ines === undefined
? []
: [
observation(
"container-header",
inventory.manifest.root_artifact_id,
inventory.ines.header,
evidenceId,
),
observation(
"reconstruction",
inventory.manifest.root_artifact_id,
inventory.ines.reconstruction,
evidenceId,
),
]),
];
const observation = (
+1
View File
@@ -14,5 +14,6 @@ export interface ArtifactInventorySnapshot {
ArtifactInventoryResult["provenance"][number]
>;
readonly integrity_contradictions: readonly IntegrityContradiction[];
readonly ines?: ArtifactInventoryResult["ines"];
readonly limitations: readonly string[];
}
+1
View File
@@ -127,6 +127,7 @@ export type BinaryTarget =
| "hsp"
| "app-pack"
| "asar"
| "ines"
| "dmg"
| "pkg";
})
+1
View File
@@ -59,6 +59,7 @@ const subjectSchema = z.object({
"hsp",
"app-pack",
"asar",
"ines",
"dmg",
"pkg",
"plist",
+92
View File
@@ -0,0 +1,92 @@
import { expect, it } from "vitest";
import { parseInesLayout } from "./inesContainer.js";
const header = (): Buffer => {
const bytes = Buffer.alloc(16);
bytes.write("NES\x1a", "latin1");
bytes[4] = 1;
return bytes;
};
it("bounds the complete classic header count without inventing RAM regions", () => {
const bytes = header();
bytes[4] = 255;
bytes[5] = 255;
bytes[6] = 0xfe;
bytes[7] = 0xf3;
const parsed = parseInesLayout(bytes, 16 + 512 + 255 * (16_384 + 8_192));
if (!parsed.ok) throw new Error(parsed.error);
expect(parsed.value.header).toMatchObject({
mapper: 255,
trainer_present: true,
battery_flag: true,
mirroring: "four-screen",
});
expect(parsed.value.regions).toHaveLength(512);
expect(parsed.value.regions.at(-1)).toMatchObject({
path: "chr/254.bin",
length: 8_192,
});
});
it.each([
{
label: "short header",
modify: (bytes: Buffer) => bytes.subarray(0, 8),
size: 8,
reason: "truncated iNES header",
},
{
label: "short payload",
modify: (bytes: Buffer) => bytes,
size: 16,
reason: "truncated iNES payload",
},
{
label: "NES 2.0",
modify: (bytes: Buffer) => {
bytes[7] = 8;
return bytes;
},
size: 16_400,
reason: "nes-2.0",
},
{
label: "dirty legacy header",
modify: (bytes: Buffer) => {
bytes[12] = 1;
return bytes;
},
size: 16_400,
reason: "ambiguous iNES mapper",
},
{
label: "empty PRG",
modify: (bytes: Buffer) => {
bytes[4] = 0;
return bytes;
},
size: 16,
reason: "at least one PRG",
},
{
label: "unsupported variant",
modify: (bytes: Buffer) => {
bytes[7] = 4;
return bytes;
},
size: 16_400,
reason: "unsupported iNES header variant",
},
{
label: "unsafe extent",
modify: (bytes: Buffer) => bytes,
size: Number.MAX_SAFE_INTEGER + 1,
reason: "invalid iNES file extent",
},
])("refuses $label before producing regions", ({ modify, size, reason }) => {
expect(parseInesLayout(modify(header()), size)).toMatchObject({
ok: false,
error: expect.stringContaining(reason),
});
});
+131
View File
@@ -0,0 +1,131 @@
import { z } from "zod";
import { err, ok, type Result } from "./result.js";
/** Byte signatures select a container family, never an executable architecture. */
export const nesContainerFormat = (
prefix: Buffer,
): "ines" | "nes-2.0" | "unif" | undefined => {
if (prefix.subarray(0, 4).equals(Buffer.from("UNIF"))) return "unif";
if (!prefix.subarray(0, 4).equals(Buffer.from([0x4e, 0x45, 0x53, 0x1a])))
return undefined;
return prefix.length >= 8 && (prefix.readUInt8(7) & 0x0c) === 0x08
? "nes-2.0"
: "ines";
};
const inesHeaderSchema = z.strictObject({
format: z.literal("ines"),
header_hex: z.string().regex(/^[a-f0-9]{32}$/u),
prg_rom_units_16k: z.number().int().min(1).max(255),
chr_rom_units_8k: z.number().int().min(0).max(255),
mapper: z.number().int().min(0).max(255),
flags_6: z.number().int().min(0).max(255),
flags_7: z.number().int().min(0).max(255),
trainer_present: z.boolean(),
battery_flag: z.boolean(),
mirroring: z.enum(["horizontal", "vertical", "four-screen"]),
});
/** Verified concatenation is a byte identity claim, not an emulator claim. */
export const inesInventorySchema = z.strictObject({
header: inesHeaderSchema,
reconstruction: z.strictObject({
region_order: z.array(z.string().min(1)).min(2),
bytes: z.number().int().min(16).max(Number.MAX_SAFE_INTEGER),
sha256: z.string().regex(/^[a-f0-9]{64}$/u),
verified: z.literal(true),
}),
});
export type InesInventory = z.infer<typeof inesInventorySchema>;
export interface InesRegion {
readonly path: string;
readonly offset: number;
readonly length: number;
}
export interface InesLayout {
readonly header: InesInventory["header"];
readonly regions: readonly InesRegion[];
}
/**
* Classic iNES counts 16 KiB PRG and 8 KiB CHR file units. Those units do not
* establish the mapper's runtime windows. Preserve all other bytes verbatim.
*/
export const parseInesLayout = (
prefix: Buffer,
fileSize: number,
): Result<InesLayout, string> => {
const format = nesContainerFormat(prefix);
if (format !== "ines")
return err(
format === undefined
? "missing iNES byte signature"
: `${format} containers are not supported by the classic iNES lane`,
);
if (!Number.isSafeInteger(fileSize) || fileSize < 0)
return err("invalid iNES file extent: expected a nonnegative safe integer");
if (fileSize < 16 || prefix.length < 16)
return err("truncated iNES header: expected 16 bytes");
const prgUnits = prefix.readUInt8(4);
const chrUnits = prefix.readUInt8(5);
const flags6 = prefix.readUInt8(6);
const flags7 = prefix.readUInt8(7);
if ((flags7 & 0x0c) !== 0) return err("unsupported iNES header variant");
// Dirty legacy headers make the upper mapper bits ambiguous. Do not repair
// them or claim a mapper that the observed header cannot establish.
if (prefix.subarray(12, 16).some((byte) => byte !== 0))
return err(
"ambiguous iNES mapper: reserved header bytes 12..15 are nonzero",
);
if (prgUnits === 0) return err("iNES requires at least one PRG-ROM unit");
const trainer = (flags6 & 4) !== 0;
const declaredEnd =
16 + (trainer ? 512 : 0) + prgUnits * 16_384 + chrUnits * 8_192;
if (declaredEnd > fileSize)
return err(
`truncated iNES payload: header declares ${declaredEnd} bytes; file has ${fileSize}`,
);
const regions: InesRegion[] = [{ path: "header.bin", offset: 0, length: 16 }];
let offset = 16;
if (trainer) {
regions.push({ path: "trainer.bin", offset, length: 512 });
offset += 512;
}
for (const [kind, count, length] of [
["prg", prgUnits, 16_384],
["chr", chrUnits, 8_192],
] as const)
for (let index = 0; index < count; index += 1) {
regions.push({
path: `${kind}/${String(index).padStart(3, "0")}.bin`,
offset,
length,
});
offset += length;
}
if (offset < fileSize)
regions.push({ path: "trailing.bin", offset, length: fileSize - offset });
return ok({
header: {
format: "ines",
header_hex: prefix.subarray(0, 16).toString("hex"),
prg_rom_units_16k: prgUnits,
chr_rom_units_8k: chrUnits,
mapper: (flags6 >>> 4) | (flags7 & 0xf0),
flags_6: flags6,
flags_7: flags7,
trainer_present: trainer,
battery_flag: (flags6 & 2) !== 0,
mirroring:
(flags6 & 8) !== 0
? "four-screen"
: (flags6 & 1) !== 0
? "vertical"
: "horizontal",
},
regions,
});
};