@carbonenginejs/runtime-resource 0.12.0 → 0.12.1

package/dist/format/CjsFormatError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CjsFormatError.js","sources":["../../../src/format/CjsFormatError.js"],"sourcesContent":["/**\n * Error raised when shared binary format bytes cannot be decoded safely.\n *\n * Format-specific readers substitute their own error class through the\n * `ReadError` static on `CjsByteReader`, so this type is the fallback for\n * readers that do not need a distinguishable name.\n */\nexport class CjsFormatReadError extends Error\n{\n    /**\n     * Creates a read error with structured reader-state details.\n     *\n     * @param {string} message Human-readable failure reason.\n     * @param {object} [details] Extra reader state such as source, offset, or size.\n     */\n    constructor(message, details = {})\n    {\n        super(message);\n        this.name = \"CjsFormatReadError\";\n        this.details = details;\n    }\n}\n\n/**\n * Error raised when shared binary format bytes cannot be encoded safely.\n */\nexport class CjsFormatWriteError extends Error\n{\n    /**\n     * Creates a write error with structured writer-state details.\n     *\n     * @param {string} message Human-readable failure reason.\n     * @param {object} [details] Extra writer state such as offset or value.\n     */\n    constructor(message, details = {})\n    {\n        super(message);\n        this.name = \"CjsFormatWriteError\";\n        this.code = \"CJS_FORMAT_WRITE_ERROR\";\n        this.details = details;\n    }\n}\n\nexport default CjsFormatReadError;\n"],"names":["CjsFormatReadError","Error","constructor","message","details","name","CjsFormatWriteError","code"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMA,kBAAkB,SAASC,KAAK,CAC7C;AACI;AACJ;AACA;AACA;AACA;AACA;AACIC,EAAAA,WAAWA,CAACC,OAAO,EAAEC,OAAO,GAAG,EAAE,EACjC;IACI,KAAK,CAACD,OAAO,CAAC;IACd,IAAI,CAACE,IAAI,GAAG,oBAAoB;IAChC,IAAI,CAACD,OAAO,GAAGA,OAAO;AAC1B,EAAA;AACJ;;AAEA;AACA;AACA;AACO,MAAME,mBAAmB,SAASL,KAAK,CAC9C;AACI;AACJ;AACA;AACA;AACA;AACA;AACIC,EAAAA,WAAWA,CAACC,OAAO,EAAEC,OAAO,GAAG,EAAE,EACjC;IACI,KAAK,CAACD,OAAO,CAAC;IACd,IAAI,CAACE,IAAI,GAAG,qBAAqB;IACjC,IAAI,CAACE,IAAI,GAAG,wBAAwB;IACpC,IAAI,CAACH,OAAO,GAAGA,OAAO;AAC1B,EAAA;AACJ;;;;"}

package/dist/format/CjsStringTable.js

@@ -0,0 +1,268 @@
+import { CjsFormatWriteError } from './CjsFormatError.js';
+
+// Source: trinity/shadercompiler/StringTable.cpp, trinity/shadercompiler/StringTable.h
+
+const textEncoder = new TextEncoder();
+
+/**
+ * The null arena reference. `StringTable::GetOffset` returns this for an
+ * invalid or unknown reference (`StringTable.cpp:52-68`), and Carbon's reader
+ * tolerates it at exactly one wire position: a stage's default-constant-value
+ * offset when the accompanying size is zero
+ * (`Tr2EffectDescription.cpp:80-91`). Everywhere else it fails the load.
+ */
+const CJS_STRING_TABLE_NULL_REFERENCE = 0xffffffff;
+
+/**
+ * Compares two byte runs the way Carbon's `Blob::operator<` does: `memcmp`
+ * over the shorter length, then shorter-wins on a tie
+ * (`StringTable.h:109-122`).
+ *
+ * @param {Uint8Array} a First byte run.
+ * @param {Uint8Array} b Second byte run.
+ * @returns {number} Negative, zero, or positive ordering result.
+ */
+function compareTableBlobs(a, b) {
+  const shared = Math.min(a.length, b.length);
+  for (let index = 0; index < shared; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index];
+  }
+  return a.length - b.length;
+}
+
+/**
+ * FNV-1a over every byte, used only to bucket dedupe candidates.
+ *
+ * Carbon hashes a stride-sampled subset (`StringTable.h:124-134`); hashing all
+ * bytes costs the same asymptotically and collides less. Either way the
+ * decision is made by the full byte comparison that follows, so the choice of
+ * hash cannot change the emitted arena.
+ *
+ * @param {Uint8Array} bytes Byte run to hash.
+ * @returns {number} 32-bit hash.
+ */
+function hashBytes(bytes) {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < bytes.length; index += 1) {
+    hash ^= bytes[index];
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+/**
+ * Carbon's compiled-effect string table: a deduplicated blob arena whose
+ * offsets are assigned by a bytewise sort rather than by insertion order.
+ *
+ * The arena holds three kinds of entry, distinguished only by how the wire
+ * refers to them:
+ *
+ * - NUL-terminated strings, added with the terminator (`strlen + 1`,
+ *   `StringTable.cpp:18-21`), referenced by a bare `u32` offset;
+ * - sized blobs — shader bytecode, program source, default constant values —
+ *   added with exactly their own bytes and no terminator
+ *   (`StringTable.cpp:23-41`), referenced by a `{u32 size, u32 offset}` pair;
+ * - nothing else. Carbon persists no manifest: `StringTable::Write` emits a
+ *   `u32` payload size and the payload (`StringTable.cpp:110-143`), and every
+ *   reference site resolves its own entry.
+ *
+ * Two deliberate departures from Carbon, both of which make byte-identical
+ * output more likely rather than less:
+ *
+ * - `m_size` is initialised. Carbon's constructor leaves it indeterminate
+ *   (`StringTable.cpp:9-12`, `StringTable.h:170`) and gets away with it only
+ *   because the one instance is a zero-initialised global.
+ * - adding after an offset has been handed out is an error rather than a silent
+ *   resort. In Carbon, `GetOffset` re-sorts whenever the table is dirty
+ *   (`StringTable.cpp:59-62`), which reassigns *every* offset — including
+ *   offsets already baked into packed bodies. Carbon avoids the corruption by
+ *   interning all late strings before the packing pass; we fail closed instead.
+ */
+class CjsStringTable {
+  #blobs = [];
+  #buckets = new Map();
+  #byteLength = 0;
+  #offsets = null;
+  #handedOutOffsets = false;
+
+  /**
+   * Returns the arena payload byte count, excluding the `u32` size prefix.
+   *
+   * This is Carbon's `m_size` and the value the reader bounds-checks every
+   * offset against.
+   *
+   * @returns {number} Payload byte count.
+   */
+  get byteLength() {
+    return this.#byteLength;
+  }
+
+  /**
+   * Returns the byte count the arena occupies in the file, including its own
+   * `u32` size prefix.
+   *
+   * This is Carbon's `GetSize()` (`StringTable.cpp:82-85`), the term used by
+   * the body-offset base arithmetic.
+   *
+   * @returns {number} On-disk byte count.
+   */
+  get containerSize() {
+    return this.#byteLength + 4;
+  }
+
+  /**
+   * Returns the number of distinct entries in the arena.
+   *
+   * @returns {number} Deduplicated entry count.
+   */
+  get entryCount() {
+    return this.#blobs.length;
+  }
+
+  /**
+   * Interns a NUL-terminated string and returns its reference.
+   *
+   * @param {string} value Text to intern, stored with a trailing NUL.
+   * @returns {number} Arena reference for later `offsetOf`.
+   */
+  addString(value) {
+    const text = textEncoder.encode(String(value));
+    const bytes = new Uint8Array(text.length + 1);
+    bytes.set(text, 0);
+    return this.#add(bytes);
+  }
+
+  /**
+   * Interns exact bytes with no terminator and returns their reference.
+   *
+   * @param {ArrayBufferView|Uint8Array} value Bytes to intern.
+   * @returns {number} Arena reference for later `offsetOf`.
+   */
+  addBytes(value) {
+    const source = value instanceof Uint8Array ? value : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    return this.#add(Uint8Array.from(source));
+  }
+
+  /**
+   * Assigns every entry its final offset by Carbon's bytewise sort.
+   *
+   * Idempotent while the table is unchanged. Returns this table so it can be
+   * chained onto construction.
+   *
+   * @returns {CjsStringTable} This table.
+   */
+  finish() {
+    if (this.#offsets) return this;
+    const order = this.#blobs.map((blob, index) => index);
+    order.sort((a, b) => compareTableBlobs(this.#blobs[a], this.#blobs[b]));
+    const offsets = new Array(this.#blobs.length);
+    let cursor = 0;
+    for (const index of order) {
+      offsets[index] = cursor;
+      cursor += this.#blobs[index].length;
+    }
+    this.#offsets = offsets;
+    return this;
+  }
+
+  /**
+   * Resolves an arena reference to its byte offset.
+   *
+   * `null` and `undefined` resolve to the `0xffffffff` null reference, so a
+   * caller can pass an absent optional field straight through.
+   *
+   * @param {number|null|undefined} reference Reference from `addString`/`addBytes`.
+   * @returns {number} Byte offset, or `0xffffffff` for a null reference.
+   */
+  offsetOf(reference) {
+    if (reference === null || reference === undefined) {
+      return CJS_STRING_TABLE_NULL_REFERENCE;
+    }
+    if (!Number.isInteger(reference) || reference < 0 || reference >= this.#blobs.length) {
+      throw new CjsFormatWriteError("Unknown string-table reference", {
+        reference,
+        entryCount: this.#blobs.length
+      });
+    }
+    this.finish();
+    this.#handedOutOffsets = true;
+    return this.#offsets[reference];
+  }
+
+  /**
+   * Returns the interned bytes behind a reference.
+   *
+   * @param {number} reference Reference from `addString`/`addBytes`.
+   * @returns {Uint8Array} View over the interned bytes.
+   */
+  bytesOf(reference) {
+    if (!Number.isInteger(reference) || reference < 0 || reference >= this.#blobs.length) {
+      throw new CjsFormatWriteError("Unknown string-table reference", {
+        reference,
+        entryCount: this.#blobs.length
+      });
+    }
+    return this.#blobs[reference];
+  }
+
+  /**
+   * Materialises the arena payload in sorted order.
+   *
+   * @returns {Uint8Array} Arena payload, without the `u32` size prefix.
+   */
+  toBytes() {
+    this.finish();
+    const out = new Uint8Array(this.#byteLength);
+    for (let index = 0; index < this.#blobs.length; index += 1) {
+      out.set(this.#blobs[index], this.#offsets[index]);
+    }
+    return out;
+  }
+
+  /**
+   * Writes the arena exactly as `StringTable::Write` does: a `u32` payload
+   * size followed by the payload (`StringTable.cpp:110-143`).
+   *
+   * @param {import("./CjsByteWriter.js").CjsByteWriter} writer Target writer.
+   */
+  write(writer) {
+    this.finish();
+    writer.u32(this.#byteLength);
+    if (this.#byteLength === 0) return;
+    writer.bytes(this.toBytes());
+  }
+
+  /**
+   * Interns a byte run, returning an existing reference when the bytes match
+   * exactly. Dedupe is on full content and length, with no suffix merging —
+   * Carbon's `Blob::operator==` (`StringTable.h:104-107`).
+   *
+   * @param {Uint8Array} bytes Owned bytes to intern.
+   * @returns {number} Arena reference.
+   */
+  #add(bytes) {
+    const key = hashBytes(bytes);
+    const bucket = this.#buckets.get(key);
+    if (bucket) {
+      for (const candidate of bucket) {
+        if (compareTableBlobs(this.#blobs[candidate], bytes) === 0) {
+          return candidate;
+        }
+      }
+    }
+    if (this.#handedOutOffsets) {
+      throw new CjsFormatWriteError("String-table entry added after offsets were resolved; every offset already handed out would shift", {
+        byteLength: bytes.length
+      });
+    }
+    const reference = this.#blobs.length;
+    this.#blobs.push(bytes);
+    this.#byteLength += bytes.length;
+    this.#offsets = null;
+    if (bucket) bucket.push(reference);else this.#buckets.set(key, [reference]);
+    return reference;
+  }
+}
+
+export { CJS_STRING_TABLE_NULL_REFERENCE, CjsStringTable, compareTableBlobs };
+//# sourceMappingURL=CjsStringTable.js.map

package/dist/format/CjsStringTable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CjsStringTable.js","sources":["../../../src/format/CjsStringTable.js"],"sourcesContent":["import { CjsFormatWriteError } from \"./CjsFormatError.js\";\n\n// Source: trinity/shadercompiler/StringTable.cpp, trinity/shadercompiler/StringTable.h\n\nconst textEncoder = new TextEncoder();\n\n/**\n * The null arena reference. `StringTable::GetOffset` returns this for an\n * invalid or unknown reference (`StringTable.cpp:52-68`), and Carbon's reader\n * tolerates it at exactly one wire position: a stage's default-constant-value\n * offset when the accompanying size is zero\n * (`Tr2EffectDescription.cpp:80-91`). Everywhere else it fails the load.\n */\nexport const CJS_STRING_TABLE_NULL_REFERENCE = 0xffffffff;\n\n/**\n * Compares two byte runs the way Carbon's `Blob::operator<` does: `memcmp`\n * over the shorter length, then shorter-wins on a tie\n * (`StringTable.h:109-122`).\n *\n * @param {Uint8Array} a First byte run.\n * @param {Uint8Array} b Second byte run.\n * @returns {number} Negative, zero, or positive ordering result.\n */\nexport function compareTableBlobs(a, b)\n{\n    const shared = Math.min(a.length, b.length);\n    for (let index = 0; index < shared; index += 1)\n    {\n        if (a[index] !== b[index]) return a[index] - b[index];\n    }\n    return a.length - b.length;\n}\n\n/**\n * FNV-1a over every byte, used only to bucket dedupe candidates.\n *\n * Carbon hashes a stride-sampled subset (`StringTable.h:124-134`); hashing all\n * bytes costs the same asymptotically and collides less. Either way the\n * decision is made by the full byte comparison that follows, so the choice of\n * hash cannot change the emitted arena.\n *\n * @param {Uint8Array} bytes Byte run to hash.\n * @returns {number} 32-bit hash.\n */\nfunction hashBytes(bytes)\n{\n    let hash = 0x811c9dc5;\n    for (let index = 0; index < bytes.length; index += 1)\n    {\n        hash ^= bytes[index];\n        hash = Math.imul(hash, 0x01000193);\n    }\n    return hash >>> 0;\n}\n\n/**\n * Carbon's compiled-effect string table: a deduplicated blob arena whose\n * offsets are assigned by a bytewise sort rather than by insertion order.\n *\n * The arena holds three kinds of entry, distinguished only by how the wire\n * refers to them:\n *\n * - NUL-terminated strings, added with the terminator (`strlen + 1`,\n *   `StringTable.cpp:18-21`), referenced by a bare `u32` offset;\n * - sized blobs — shader bytecode, program source, default constant values —\n *   added with exactly their own bytes and no terminator\n *   (`StringTable.cpp:23-41`), referenced by a `{u32 size, u32 offset}` pair;\n * - nothing else. Carbon persists no manifest: `StringTable::Write` emits a\n *   `u32` payload size and the payload (`StringTable.cpp:110-143`), and every\n *   reference site resolves its own entry.\n *\n * Two deliberate departures from Carbon, both of which make byte-identical\n * output more likely rather than less:\n *\n * - `m_size` is initialised. Carbon's constructor leaves it indeterminate\n *   (`StringTable.cpp:9-12`, `StringTable.h:170`) and gets away with it only\n *   because the one instance is a zero-initialised global.\n * - adding after an offset has been handed out is an error rather than a silent\n *   resort. In Carbon, `GetOffset` re-sorts whenever the table is dirty\n *   (`StringTable.cpp:59-62`), which reassigns *every* offset — including\n *   offsets already baked into packed bodies. Carbon avoids the corruption by\n *   interning all late strings before the packing pass; we fail closed instead.\n */\nexport class CjsStringTable\n{\n    #blobs = [];\n    #buckets = new Map();\n    #byteLength = 0;\n    #offsets = null;\n    #handedOutOffsets = false;\n\n    /**\n     * Returns the arena payload byte count, excluding the `u32` size prefix.\n     *\n     * This is Carbon's `m_size` and the value the reader bounds-checks every\n     * offset against.\n     *\n     * @returns {number} Payload byte count.\n     */\n    get byteLength()\n    {\n        return this.#byteLength;\n    }\n\n    /**\n     * Returns the byte count the arena occupies in the file, including its own\n     * `u32` size prefix.\n     *\n     * This is Carbon's `GetSize()` (`StringTable.cpp:82-85`), the term used by\n     * the body-offset base arithmetic.\n     *\n     * @returns {number} On-disk byte count.\n     */\n    get containerSize()\n    {\n        return this.#byteLength + 4;\n    }\n\n    /**\n     * Returns the number of distinct entries in the arena.\n     *\n     * @returns {number} Deduplicated entry count.\n     */\n    get entryCount()\n    {\n        return this.#blobs.length;\n    }\n\n    /**\n     * Interns a NUL-terminated string and returns its reference.\n     *\n     * @param {string} value Text to intern, stored with a trailing NUL.\n     * @returns {number} Arena reference for later `offsetOf`.\n     */\n    addString(value)\n    {\n        const text = textEncoder.encode(String(value));\n        const bytes = new Uint8Array(text.length + 1);\n        bytes.set(text, 0);\n        return this.#add(bytes);\n    }\n\n    /**\n     * Interns exact bytes with no terminator and returns their reference.\n     *\n     * @param {ArrayBufferView|Uint8Array} value Bytes to intern.\n     * @returns {number} Arena reference for later `offsetOf`.\n     */\n    addBytes(value)\n    {\n        const source = value instanceof Uint8Array\n            ? value\n            : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);\n        return this.#add(Uint8Array.from(source));\n    }\n\n    /**\n     * Assigns every entry its final offset by Carbon's bytewise sort.\n     *\n     * Idempotent while the table is unchanged. Returns this table so it can be\n     * chained onto construction.\n     *\n     * @returns {CjsStringTable} This table.\n     */\n    finish()\n    {\n        if (this.#offsets) return this;\n\n        const order = this.#blobs.map((blob, index) => index);\n        order.sort((a, b) => compareTableBlobs(this.#blobs[a], this.#blobs[b]));\n\n        const offsets = new Array(this.#blobs.length);\n        let cursor = 0;\n        for (const index of order)\n        {\n            offsets[index] = cursor;\n            cursor += this.#blobs[index].length;\n        }\n        this.#offsets = offsets;\n        return this;\n    }\n\n    /**\n     * Resolves an arena reference to its byte offset.\n     *\n     * `null` and `undefined` resolve to the `0xffffffff` null reference, so a\n     * caller can pass an absent optional field straight through.\n     *\n     * @param {number|null|undefined} reference Reference from `addString`/`addBytes`.\n     * @returns {number} Byte offset, or `0xffffffff` for a null reference.\n     */\n    offsetOf(reference)\n    {\n        if (reference === null || reference === undefined)\n        {\n            return CJS_STRING_TABLE_NULL_REFERENCE;\n        }\n        if (!Number.isInteger(reference) || reference < 0 || reference >= this.#blobs.length)\n        {\n            throw new CjsFormatWriteError(\"Unknown string-table reference\", {\n                reference,\n                entryCount: this.#blobs.length\n            });\n        }\n        this.finish();\n        this.#handedOutOffsets = true;\n        return this.#offsets[reference];\n    }\n\n    /**\n     * Returns the interned bytes behind a reference.\n     *\n     * @param {number} reference Reference from `addString`/`addBytes`.\n     * @returns {Uint8Array} View over the interned bytes.\n     */\n    bytesOf(reference)\n    {\n        if (!Number.isInteger(reference) || reference < 0 || reference >= this.#blobs.length)\n        {\n            throw new CjsFormatWriteError(\"Unknown string-table reference\", {\n                reference,\n                entryCount: this.#blobs.length\n            });\n        }\n        return this.#blobs[reference];\n    }\n\n    /**\n     * Materialises the arena payload in sorted order.\n     *\n     * @returns {Uint8Array} Arena payload, without the `u32` size prefix.\n     */\n    toBytes()\n    {\n        this.finish();\n        const out = new Uint8Array(this.#byteLength);\n        for (let index = 0; index < this.#blobs.length; index += 1)\n        {\n            out.set(this.#blobs[index], this.#offsets[index]);\n        }\n        return out;\n    }\n\n    /**\n     * Writes the arena exactly as `StringTable::Write` does: a `u32` payload\n     * size followed by the payload (`StringTable.cpp:110-143`).\n     *\n     * @param {import(\"./CjsByteWriter.js\").CjsByteWriter} writer Target writer.\n     */\n    write(writer)\n    {\n        this.finish();\n        writer.u32(this.#byteLength);\n        if (this.#byteLength === 0) return;\n        writer.bytes(this.toBytes());\n    }\n\n    /**\n     * Interns a byte run, returning an existing reference when the bytes match\n     * exactly. Dedupe is on full content and length, with no suffix merging —\n     * Carbon's `Blob::operator==` (`StringTable.h:104-107`).\n     *\n     * @param {Uint8Array} bytes Owned bytes to intern.\n     * @returns {number} Arena reference.\n     */\n    #add(bytes)\n    {\n        const key = hashBytes(bytes);\n        const bucket = this.#buckets.get(key);\n        if (bucket)\n        {\n            for (const candidate of bucket)\n            {\n                if (compareTableBlobs(this.#blobs[candidate], bytes) === 0)\n                {\n                    return candidate;\n                }\n            }\n        }\n\n        if (this.#handedOutOffsets)\n        {\n            throw new CjsFormatWriteError(\n                \"String-table entry added after offsets were resolved; every offset already handed out would shift\",\n                { byteLength: bytes.length }\n            );\n        }\n\n        const reference = this.#blobs.length;\n        this.#blobs.push(bytes);\n        this.#byteLength += bytes.length;\n        this.#offsets = null;\n        if (bucket) bucket.push(reference);\n        else this.#buckets.set(key, [ reference ]);\n        return reference;\n    }\n}\n\nexport default CjsStringTable;\n"],"names":["textEncoder","TextEncoder","CJS_STRING_TABLE_NULL_REFERENCE","compareTableBlobs","a","b","shared","Math","min","length","index","hashBytes","bytes","hash","imul","CjsStringTable","Map","byteLength","containerSize","entryCount","addString","value","text","encode","String","Uint8Array","set","addBytes","source","buffer","byteOffset","from","finish","order","map","blob","sort","offsets","Array","cursor","offsetOf","reference","undefined","Number","isInteger","CjsFormatWriteError","bytesOf","toBytes","out","write","writer","u32","#add","key","bucket","get","candidate","push"],"mappings":"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"}

package/dist/format/carbonEffect/CjsCarbonEffectReader.js

@@ -0,0 +1,361 @@
+import { CjsByteReader } from '../CjsByteReader.js';
+import { CjsFormatReadError } from '../CjsFormatError.js';
+import { CARBON_EFFECT_DATA_VERSION, readEffectDescription } from './carbonEffectRecords.js';
+
+// Source: trinity/trinity/Resources/Tr2EffectRes.cpp (DoLoad, GetShader)
+// Source: trinity/shadercompiler/ShaderCompiler.cpp:746-845 (file assembly)
+
+
+/** Byte count of the ASCII-hex MD5 source hash in the v15 header. */
+const CARBON_EFFECT_SOURCE_HASH_BYTES = 32;
+
+/** Byte count of one offset-table row: `{u32 index, u32 offset, u32 size}`. */
+const CARBON_EFFECT_RECORD_BYTES = 12;
+
+/**
+ * Plain byte cursor over one description blob, carrying the Carbon effect error
+ * class and message.
+ *
+ * Separate from the container reader because the container reader parses its
+ * header in the constructor; a body needs a cursor, not a second header parse.
+ */
+class CjsCarbonEffectBodyReader extends CjsByteReader {
+  static ReadError = CjsFormatReadError;
+  static endOfDataMessage = "Unexpected end of Carbon effect data";
+}
+
+/**
+ * Reader for Carbon's compiled-effect container at version 15.
+ *
+ * The header is (`ShaderCompiler.cpp:822-831`):
+ *
+ * ```
+ * u32      version = 15
+ * u8[4]    shaderCompilerVersion       <- four bytes, not a u32
+ * char[32] sourceHash                  <- ASCII hex MD5 of the HLSL inputs
+ * u32      stringTableSize | arena
+ * u8       permutationCount | permutation records
+ * u32      recordCount     | recordCount x { u32 index, u32 offset, u32 size }
+ * description blobs
+ * ```
+ *
+ * Only version 15 is accepted. Carbon's own reader takes 2..15
+ * (`Tr2EffectRes.cpp:209`) but marks the v13/v14 field-order boundaries
+ * unverified, and every file in the shipped dx11/dx12 corpus is v15, so a
+ * lower version here means something unexpected rather than something old.
+ */
+class CjsCarbonEffectReader extends CjsCarbonEffectBodyReader {
+  /** Cursor class used for description blobs. */
+  static BodyReader = CjsCarbonEffectBodyReader;
+
+  /**
+   * Reads the container header, arena, permutation axes and offset table.
+   *
+   * @param {ArrayBuffer|ArrayBufferView|Uint8Array} bytes Container bytes.
+   * @param {object} [options] Read options.
+   * @param {string} [options.source] Source name used in error details.
+   * @param {boolean} [options.permissive] Accept a sparse or misordered offset
+   *     table instead of rejecting it. For forensic inspection of a file already
+   *     known to be malformed; never for a load path.
+   */
+  constructor(bytes, options = {}) {
+    super(bytes, options);
+    this.version = this.readUint32();
+    if (this.version !== CARBON_EFFECT_DATA_VERSION) {
+      throw this._error(`Unsupported Carbon effect version ${this.version}; expected ${CARBON_EFFECT_DATA_VERSION}`, {
+        version: this.version
+      });
+    }
+    this.compilerVersion = Array.from(this.readRaw(4));
+    this.sourceHash = Uint8Array.from(this.readRaw(CARBON_EFFECT_SOURCE_HASH_BYTES));
+    this.stringTableSize = this.readUint32();
+    if (this.offset + this.stringTableSize > this.bytes.length) {
+      throw this._error("Invalid Carbon effect string-table size", {
+        stringTableSize: this.stringTableSize,
+        byteLength: this.bytes.length
+      });
+    }
+    this.stringTableBytes = this.bytes.subarray(this.offset, this.offset + this.stringTableSize);
+    this.skip(this.stringTableSize);
+    this.setStringTable(this.stringTableBytes, this.stringTableSize);
+    this.permutations = this.#readPermutations();
+    this.records = this.#readRecords();
+    this.headerEnd = this.offset;
+    this.diagnostics = this.#inspect();
+    if (!options.permissive) {
+      this.requireDensePermutationTable();
+    }
+  }
+
+  /**
+   * Returns the product of the permutation axes' option counts — the number of
+   * offset-table rows a fully populated file has.
+   *
+   * @returns {number} Permutation count.
+   */
+  get permutationProduct() {
+    let product = 1;
+    for (const permutation of this.permutations) {
+      product *= permutation.options.length;
+    }
+    return product;
+  }
+
+  /**
+   * Throws unless the offset table is dense and positionally indexed.
+   *
+   * Carbon indexes `m_offsets` positionally and never reads the stored `index`
+   * field (`Tr2EffectRes.cpp:121-126`), so a sparse or misordered table does
+   * not fail — it silently returns the wrong shader body. Carbon gets density
+   * incidentally, from `g_compiledEffects` being a `std::map` densely keyed by
+   * `AddPermutationsToWorkQueue`, and promises it nowhere.
+   *
+   * Measured across the whole shipped corpus at build 3444265 — 4833 files and
+   * 78,498 rows across `effect.dx11`, `effect.dx12` and `effect.metal` — both
+   * conditions hold in every file, so this runs by default.
+   *
+   * `--ignore-permutations` does make CCP's compiler emit only key 0 while
+   * declaring every axis, so a sparse file is producible. That argues for an
+   * escape hatch, not for permissiveness: because Carbon indexes positionally,
+   * accepting such a file returns the wrong permutation's shader silently, which
+   * is exactly the failure class this container port exists to close.
+   * `{ permissive: true }` is the opt-in, for inspecting a file already known to
+   * be malformed.
+   */
+  requireDensePermutationTable() {
+    if (!this.diagnostics.dense) {
+      throw this._error("Carbon effect offset table is sparse", {
+        recordCount: this.records.length,
+        permutationProduct: this.permutationProduct
+      });
+    }
+    if (!this.diagnostics.indicesMatchPosition) {
+      throw this._error("Carbon effect offset table is not positionally indexed", {
+        firstMismatch: this.diagnostics.firstIndexMismatch
+      });
+    }
+  }
+
+  /**
+   * Reads and parses one permutation's description blob.
+   *
+   * `backend` is **optional**, and omitting it is the interesting case. A
+   * Carbon file ends each pass at the render states; ours adds one eight-byte
+   * block reference. Nothing in the header distinguishes the two, and we
+   * deliberately do not add anything — no envelope, no version of our own,
+   * because CCP owns the version space and a container that announces itself
+   * is an invention nothing requires.
+   *
+   * Instead the blob describes itself, using a rule the format already has.
+   * Every sized record must parse to exactly its declared end (Rule 1), and a
+   * body's declared size is in the offset table. So the wrong interpretation
+   * either throws or leaves the cursor somewhere other than the end, and one
+   * retry settles it.
+   *
+   * Pass `backend` explicitly when the caller knows — the loader does, because
+   * backend selection is by resource path, mirroring Carbon's
+   * `effect.dx11`/`effect.dx12`/`effect.metal`. Auto-detection is for bytes
+   * that arrive without that context: tooling, caches, inspection.
+   *
+   * @param {number} index Permutation index, positional in the offset table.
+   * @param {object} [options] Read options.
+   * @param {boolean} [options.backend] Expect our optional per-pass trailing
+   *     block. Omit to detect it from the blob's declared end.
+   * @returns {object} Description record tree.
+   */
+  readDescription(index, options = {}) {
+    const record = this.records[index];
+    if (!record) {
+      throw this._error(`No Carbon effect body at permutation index ${index}`, {
+        index,
+        recordCount: this.records.length
+      });
+    }
+    if (options.backend !== undefined) {
+      return this.#readDescriptionAs(record, options.backend === true);
+    }
+
+    // Plain Carbon first: it is the larger population, and it is the reading
+    // that must stay cheap.
+    try {
+      return this.#readDescriptionAs(record, false);
+    } catch (withoutBlocks) {
+      try {
+        return this.#readDescriptionAs(record, true);
+      } catch {
+        // Report the plain-Carbon failure. If neither reading works the
+        // blob is malformed, and the Carbon diagnosis is the useful one;
+        // the backend attempt's error would describe a misparse of bytes
+        // that were never a backend block.
+        throw withoutBlocks;
+      }
+    }
+  }
+
+  /**
+   * Parses one body under an exact backend-block assumption.
+   *
+   * @param {object} record Offset-table row.
+   * @param {boolean} backend Whether to expect the per-pass block.
+   * @returns {object} Description record tree.
+   */
+  #readDescriptionAs(record, backend) {
+    const reader = new this.constructor.BodyReader(this.bytes, {
+      source: this.source,
+      offset: record.offset,
+      end: record.offset + record.size,
+      stringTable: this.stringTableBytes,
+      stringTableSize: this.stringTableSize
+    });
+    return readEffectDescription(reader, {
+      backend
+    });
+  }
+
+  /**
+   * Returns the raw description-blob bytes for one permutation.
+   *
+   * @param {number} index Permutation index, positional in the offset table.
+   * @returns {Uint8Array} View over the body bytes.
+   */
+  bodyBytes(index) {
+    const record = this.records[index];
+    if (!record) {
+      throw this._error(`No Carbon effect body at permutation index ${index}`, {
+        index
+      });
+    }
+    return this.bytes.subarray(record.offset, record.offset + record.size);
+  }
+
+  /**
+   * Reads the permutation axis records (`ShaderCompiler.cpp:769-795`,
+   * `Tr2EffectRes.cpp:263-292`).
+   *
+   * @returns {object[]} Permutation axes with arena references retained.
+   */
+  #readPermutations() {
+    const permutations = [];
+    const count = this.readUint8();
+    for (let index = 0; index < count; index += 1) {
+      const nameOffset = this.readUint32();
+      const name = this.readStringAt(nameOffset);
+      const defaultOption = this.readUint8();
+      const descriptionOffset = this.readUint32();
+      const description = this.readStringAt(descriptionOffset);
+      const type = this.readUint8();
+      const options = [];
+      const optionCount = this.readUint8();
+      for (let optionIndex = 0; optionIndex < optionCount; optionIndex += 1) {
+        const offset = this.readUint32();
+        options.push({
+          offset,
+          value: this.readStringAt(offset)
+        });
+      }
+      permutations.push({
+        name: {
+          offset: nameOffset,
+          value: name
+        },
+        defaultOption,
+        description: {
+          offset: descriptionOffset,
+          value: description
+        },
+        type,
+        options
+      });
+    }
+    return permutations;
+  }
+
+  /**
+   * Reads the offset table (`ShaderCompiler.cpp:800-820`,
+   * `Tr2EffectRes.cpp:294-311`).
+   *
+   * @returns {object[]} Offset-table rows.
+   */
+  #readRecords() {
+    const count = this.readUint32();
+    if (count === 0) {
+      throw this._error("Carbon effect contains no compiled bodies");
+    }
+    if (this.offset + count * CARBON_EFFECT_RECORD_BYTES > this.bytes.length) {
+      throw this._error("Carbon effect offset table runs past the end of the file", {
+        recordCount: count,
+        byteLength: this.bytes.length
+      });
+    }
+    const records = [];
+    for (let index = 0; index < count; index += 1) {
+      records.push({
+        index: this.readUint32(),
+        offset: this.readUint32(),
+        size: this.readUint32()
+      });
+    }
+    return records;
+  }
+
+  /**
+   * Validates every row's byte range and collects the structural diagnostics
+   * Carbon relies on without stating.
+   *
+   * @returns {object} Structural diagnostics.
+   */
+  #inspect() {
+    const headerEnd = this.headerEnd;
+    const byteLength = this.bytes.length;
+    let firstIndexMismatch = null;
+    const uniqueOffsets = new Set();
+    for (let index = 0; index < this.records.length; index += 1) {
+      const record = this.records[index];
+      if (record.index !== index && firstIndexMismatch === null) {
+        firstIndexMismatch = {
+          position: index,
+          storedIndex: record.index
+        };
+      }
+      const end = record.offset + record.size;
+      if (record.offset < headerEnd || end > byteLength || record.size === 0) {
+        throw this._error(`Carbon effect body record ${index} is out of range`, {
+          position: index,
+          offset: record.offset,
+          size: record.size,
+          headerEnd,
+          byteLength
+        });
+      }
+      uniqueOffsets.add(record.offset);
+    }
+
+    // The body region must begin exactly where the header ends. Carbon computes
+    // its first body offset as `4 + 4 + 32 + headerSize + stringTable.GetSize()`
+    // (`ShaderCompiler.cpp:801`), so a gap or an overlap means our reconstruction
+    // of that arithmetic disagrees with the writer's — which would silently
+    // misread every body rather than fail. Carbon's own reader does not check
+    // this; measured across 4833 shipped files, every one starts its body region
+    // flush against the header with no slack.
+    const firstBody = Math.min(...this.records.map(record => record.offset));
+    if (firstBody !== headerEnd) {
+      throw this._error("Carbon effect body region does not start where the header ends", {
+        firstBody,
+        headerEnd,
+        slack: firstBody - headerEnd
+      });
+    }
+    return {
+      recordCount: this.records.length,
+      permutationProduct: this.permutationProduct,
+      dense: this.records.length === this.permutationProduct,
+      indicesMatchPosition: firstIndexMismatch === null,
+      firstIndexMismatch,
+      uniqueBodyCount: uniqueOffsets.size,
+      aliasedRowCount: this.records.length - uniqueOffsets.size
+    };
+  }
+}
+
+export { CARBON_EFFECT_RECORD_BYTES, CARBON_EFFECT_SOURCE_HASH_BYTES, CjsCarbonEffectBodyReader, CjsCarbonEffectReader };
+//# sourceMappingURL=CjsCarbonEffectReader.js.map