@carbonenginejs/runtime-resource 0.17.0 → 0.18.1

package/dist/formats/static/CjsStaticFormat.js

@@ -0,0 +1,220 @@
+const SQLITE_SIGNATURE = "SQLite format 3\0";
+const PICKLE_PREFIX_BYTES = 4;
+
+/** Container families found behind the single `.static` extension. */
+const CJS_STATIC_FAMILIES = Object.freeze({
+  SQLITE: "sqlite",
+  PICKLE: "pickle",
+  UNKNOWN: "unknown"
+});
+
+/**
+ * Identifies which container a client `.static` file actually holds.
+ *
+ * The extension names a role, not a format. Three unrelated containers ship
+ * under it, and each fails in its own way when guessed at:
+ *
+ * - **SQLite 3** — a `cache(key, value, time)` plus `indexes(key, value)`
+ *   database whose values are JSON documents. `CjsSqliteFormat` reads it.
+ * - **Prefixed pickle** — a four-byte little-endian prefix followed by a
+ *   protocol-0 pickle. Many of these carry class-construction opcodes, which
+ *   the data-only pickle reader refuses by design; that refusal is correct and
+ *   is surfaced rather than worked around.
+ * - **Schema-bound** — a binary record container whose `.schema` companion is
+ *   YAML describing its own layout: attribute sizes and types, optional flags,
+ *   lists with a fixed item size, vectors with a precision, and a key footer of
+ *   key-to-offset pairs. Nothing needs deriving, because the build ships the
+ *   layout. Six datasets are stored this way, the celestial tables among them.
+ *   `CjsSchemaBoundFormat` reads it, given that companion.
+ *
+ * Detection is signature-based and never executes or trusts file names.
+ *
+ * **This class identifies and does not decode.** It reports the family, the
+ * payload offset and what is still missing; the caller takes that answer to the
+ * format that owns the family. It carried a `read()` that dispatched to
+ * `CjsPickleFormat` and `CjsSqliteFormat` until 2026-08-15, which made an
+ * identification format the routing table for two others and put the decision
+ * about what to decode in the wrong place. Nothing outside its own tests ever
+ * called it.
+ */
+class CjsStaticFormat {
+  /**
+   * Report which family a container holds, on the declaration seam.
+   *
+   * `.static` declares nothing: the extension names a role and every family
+   * wears it. The signature is therefore the only claim there is, which is why
+   * this format reads it here rather than trusting a name.
+   *
+   * @param {ArrayBuffer|ArrayBufferView} input Container bytes.
+   * @param {object} [options] Probe options.
+   * @returns {CjsResourceProbe} Declaration-derived probe.
+   */
+  static isSupported(input, options = null) {
+    return Probe(this.describe(input), false, options);
+  }
+
+  /**
+   * Alias for canonical naming.
+   *
+   * @param {ArrayBuffer|ArrayBufferView} input Container bytes.
+   * @param {object} [options] Probe options.
+   * @returns {CjsResourceProbe} Declaration-derived probe.
+   */
+  static inspect(input, options = null) {
+    return this.isSupported(input, options);
+  }
+
+  /**
+   * Content-verified family resolution.
+   *
+   * Contract: docs/concepts/format-type-resolution.md. There is no declared
+   * type to disagree with here — the extension is silent — so the signature is
+   * both the claim and the evidence, and the resolution is always verified.
+   * `preferred` names the decode route, and all three now lead into this
+   * package: `CjsPickleFormat`, `CjsSqliteFormat`, and `CjsSchemaBoundFormat`
+   * once the caller has the `.schema` companion to hand it.
+   *
+   * @param {ArrayBuffer|ArrayBufferView} input Container bytes.
+   * @param {object} [options] Probe options.
+   * @returns {Promise<CjsResourceProbe>} Verified probe.
+   */
+  static async resolveType(input, options = null) {
+    return Probe(this.describe(input), true, options);
+  }
+
+  /**
+   * Describe one container without decoding it or building a probe.
+   *
+   * @param {ArrayBuffer|ArrayBufferView} input Container bytes.
+   * @returns {object} Family, payload offset, and whether this package decodes it.
+   */
+  static describe(input) {
+    const bytes = Normalize(input);
+    if (MatchesSqlite(bytes)) {
+      return Object.freeze({
+        family: CJS_STATIC_FAMILIES.SQLITE,
+        byteLength: bytes.byteLength,
+        payloadOffset: 0,
+        prefix: null,
+        // Decodable outright since CjsSqliteFormat landed. This reported
+        // `requires: "sqlite"` while a caller had to supply an engine, and was
+        // the example behind the argument that a capability can depend on the
+        // caller's environment - an argument that now needs a different one.
+        decodable: true,
+        requires: null,
+        reason: "Recognized a SQLite container."
+      });
+    }
+    if (MatchesPickle(bytes)) {
+      const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+      return Object.freeze({
+        family: CJS_STATIC_FAMILIES.PICKLE,
+        byteLength: bytes.byteLength,
+        payloadOffset: PICKLE_PREFIX_BYTES,
+        prefix: view.getUint32(0, true),
+        decodable: true,
+        requires: null,
+        reason: null
+      });
+    }
+    return Object.freeze({
+      family: CJS_STATIC_FAMILIES.UNKNOWN,
+      byteLength: bytes.byteLength,
+      payloadOffset: 0,
+      prefix: null,
+      decodable: false,
+      requires: "schema",
+      // `decodable` is this format's own answer, and it stays false: these bytes
+      // carry nothing to identify, so the family is an inference from the absence
+      // of the other two signatures rather than a reading. `requires` names what
+      // closes that gap - with the companion, CjsSchemaBoundFormat decodes it.
+      reason: "No signature. A schema-bound container needs its .schema companion, " + "which is YAML describing the layout. CjsSchemaBoundFormat reads it from there."
+    });
+  }
+
+  /**
+   * Return the decodable payload for a container, without its wrapper.
+   *
+   * @param {ArrayBuffer|ArrayBufferView} input Container bytes.
+   * @returns {Uint8Array} Payload bytes.
+   */
+  static payload(input) {
+    const bytes = Normalize(input);
+    const detected = this.describe(bytes);
+    return bytes.subarray(detected.payloadOffset);
+  }
+  static id = "static";
+  static extensions = Object.freeze([".static"]);
+  static type = Object.freeze(["data"]);
+  static mediaTypes = Object.freeze(["data"]);
+
+  /**
+   * The extension is the only input this format claims.
+   *
+   * Naming the three families here would be a lie in the other direction: a
+   * caller cannot hand this format "a pickle" or "a sqlite" and expect it to
+   * route, because the whole point of the class is that `.static` declares
+   * nothing and the signature has to be read. The family belongs in
+   * `describe()`, which measures it, not in a static that asserts it.
+   */
+  static inputTypes = Object.freeze(["static"]);
+  static outputTypes = Object.freeze(["json", "payload"]);
+  static debugOutputTypes = Object.freeze(["raw"]);
+}
+
+/**
+ * Build the shared probe payload.
+ *
+ * Formats report a plain probe-shaped object rather than constructing a
+ * `CjsResourceProbe`, which keeps this module free of the decorated class and
+ * of the build transform it needs.
+ */
+function Probe(detected, verified, options) {
+  return {
+    format: "static",
+    source: "buffer",
+    supported: detected.decodable ? "full" : "partial",
+    confidence: detected.family === CJS_STATIC_FAMILIES.UNKNOWN ? 0.5 : 1,
+    preferred: detected.family,
+    verified,
+    reason: detected.reason ?? `Recognized a ${detected.family} container.`,
+    variants: [{
+      kind: "container",
+      codec: detected.family,
+      supported: detected.decodable
+    }],
+    metadata: verified ? {
+      ...detected,
+      declared: null,
+      resolved: detected.family,
+      mismatch: false
+    } : detected,
+    ...(options || {})
+  };
+}
+function MatchesSqlite(bytes) {
+  if (bytes.byteLength < SQLITE_SIGNATURE.length) return false;
+  for (let index = 0; index < SQLITE_SIGNATURE.length; index++) {
+    if (bytes[index] !== SQLITE_SIGNATURE.charCodeAt(index)) return false;
+  }
+  return true;
+}
+function MatchesPickle(bytes) {
+  // A protocol-0 pickle opens a container then names it: "(dp1\n" or "(lp1\n".
+  if (bytes.byteLength < PICKLE_PREFIX_BYTES + 3) return false;
+  if (bytes[PICKLE_PREFIX_BYTES] !== 0x28) return false;
+  const kind = bytes[PICKLE_PREFIX_BYTES + 1];
+  return kind === 0x64 || kind === 0x6c;
+}
+function Normalize(input) {
+  if (input instanceof ArrayBuffer) return new Uint8Array(input);
+  if (ArrayBuffer.isView(input)) {
+    return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+  }
+  const error = new TypeError("A .static container must be an ArrayBuffer or a view over one.");
+  error.code = "CJS_STATIC_INPUT_INVALID";
+  throw error;
+}
+
+export { CJS_STATIC_FAMILIES, CjsStaticFormat };
+//# sourceMappingURL=CjsStaticFormat.js.map

package/dist/formats/static/CjsStaticFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CjsStaticFormat.js","sources":["../../../../src/formats/static/CjsStaticFormat.js"],"sourcesContent":["\nconst SQLITE_SIGNATURE = \"SQLite format 3\\0\";\nconst PICKLE_PREFIX_BYTES = 4;\n\n/** Container families found behind the single `.static` extension. */\nexport const CJS_STATIC_FAMILIES = Object.freeze({\n  SQLITE: \"sqlite\",\n  PICKLE: \"pickle\",\n  UNKNOWN: \"unknown\"\n});\n\n/**\n * Identifies which container a client `.static` file actually holds.\n *\n * The extension names a role, not a format. Three unrelated containers ship\n * under it, and each fails in its own way when guessed at:\n *\n * - **SQLite 3** — a `cache(key, value, time)` plus `indexes(key, value)`\n *   database whose values are JSON documents. `CjsSqliteFormat` reads it.\n * - **Prefixed pickle** — a four-byte little-endian prefix followed by a\n *   protocol-0 pickle. Many of these carry class-construction opcodes, which\n *   the data-only pickle reader refuses by design; that refusal is correct and\n *   is surfaced rather than worked around.\n * - **Schema-bound** — a binary record container whose `.schema` companion is\n *   YAML describing its own layout: attribute sizes and types, optional flags,\n *   lists with a fixed item size, vectors with a precision, and a key footer of\n *   key-to-offset pairs. Nothing needs deriving, because the build ships the\n *   layout. Six datasets are stored this way, the celestial tables among them.\n *   `CjsSchemaBoundFormat` reads it, given that companion.\n *\n * Detection is signature-based and never executes or trusts file names.\n *\n * **This class identifies and does not decode.** It reports the family, the\n * payload offset and what is still missing; the caller takes that answer to the\n * format that owns the family. It carried a `read()` that dispatched to\n * `CjsPickleFormat` and `CjsSqliteFormat` until 2026-08-15, which made an\n * identification format the routing table for two others and put the decision\n * about what to decode in the wrong place. Nothing outside its own tests ever\n * called it.\n */\nexport class CjsStaticFormat\n{\n\n  /**\n   * Report which family a container holds, on the declaration seam.\n   *\n   * `.static` declares nothing: the extension names a role and every family\n   * wears it. The signature is therefore the only claim there is, which is why\n   * this format reads it here rather than trusting a name.\n   *\n   * @param {ArrayBuffer|ArrayBufferView} input Container bytes.\n   * @param {object} [options] Probe options.\n   * @returns {CjsResourceProbe} Declaration-derived probe.\n   */\n  static isSupported(input, options = null)\n  {\n    return Probe(this.describe(input), false, options);\n  }\n\n  /**\n   * Alias for canonical naming.\n   *\n   * @param {ArrayBuffer|ArrayBufferView} input Container bytes.\n   * @param {object} [options] Probe options.\n   * @returns {CjsResourceProbe} Declaration-derived probe.\n   */\n  static inspect(input, options = null)\n  {\n    return this.isSupported(input, options);\n  }\n\n  /**\n   * Content-verified family resolution.\n   *\n   * Contract: docs/concepts/format-type-resolution.md. There is no declared\n   * type to disagree with here — the extension is silent — so the signature is\n   * both the claim and the evidence, and the resolution is always verified.\n   * `preferred` names the decode route, and all three now lead into this\n   * package: `CjsPickleFormat`, `CjsSqliteFormat`, and `CjsSchemaBoundFormat`\n   * once the caller has the `.schema` companion to hand it.\n   *\n   * @param {ArrayBuffer|ArrayBufferView} input Container bytes.\n   * @param {object} [options] Probe options.\n   * @returns {Promise<CjsResourceProbe>} Verified probe.\n   */\n  static async resolveType(input, options = null)\n  {\n    return Probe(this.describe(input), true, options);\n  }\n\n  /**\n   * Describe one container without decoding it or building a probe.\n   *\n   * @param {ArrayBuffer|ArrayBufferView} input Container bytes.\n   * @returns {object} Family, payload offset, and whether this package decodes it.\n   */\n  static describe(input)\n  {\n    const bytes = Normalize(input);\n\n    if (MatchesSqlite(bytes))\n    {\n      return Object.freeze({\n        family: CJS_STATIC_FAMILIES.SQLITE,\n        byteLength: bytes.byteLength,\n        payloadOffset: 0,\n        prefix: null,\n        // Decodable outright since CjsSqliteFormat landed. This reported\n        // `requires: \"sqlite\"` while a caller had to supply an engine, and was\n        // the example behind the argument that a capability can depend on the\n        // caller's environment - an argument that now needs a different one.\n        decodable: true,\n        requires: null,\n        reason: \"Recognized a SQLite container.\"\n      });\n    }\n\n    if (MatchesPickle(bytes))\n    {\n      const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n\n      return Object.freeze({\n        family: CJS_STATIC_FAMILIES.PICKLE,\n        byteLength: bytes.byteLength,\n        payloadOffset: PICKLE_PREFIX_BYTES,\n        prefix: view.getUint32(0, true),\n        decodable: true,\n        requires: null,\n        reason: null\n      });\n    }\n\n    return Object.freeze({\n      family: CJS_STATIC_FAMILIES.UNKNOWN,\n      byteLength: bytes.byteLength,\n      payloadOffset: 0,\n      prefix: null,\n      decodable: false,\n      requires: \"schema\",\n      // `decodable` is this format's own answer, and it stays false: these bytes\n      // carry nothing to identify, so the family is an inference from the absence\n      // of the other two signatures rather than a reading. `requires` names what\n      // closes that gap - with the companion, CjsSchemaBoundFormat decodes it.\n      reason: \"No signature. A schema-bound container needs its .schema companion, \"\n        + \"which is YAML describing the layout. CjsSchemaBoundFormat reads it from there.\"\n    });\n  }\n\n  /**\n   * Return the decodable payload for a container, without its wrapper.\n   *\n   * @param {ArrayBuffer|ArrayBufferView} input Container bytes.\n   * @returns {Uint8Array} Payload bytes.\n   */\n  static payload(input)\n  {\n    const bytes = Normalize(input);\n    const detected = this.describe(bytes);\n\n    return bytes.subarray(detected.payloadOffset);\n  }\n\n\n  static id = \"static\";\n  static extensions = Object.freeze([ \".static\" ]);\n  static type = Object.freeze([ \"data\" ]);\n  static mediaTypes = Object.freeze([ \"data\" ]);\n\n  /**\n   * The extension is the only input this format claims.\n   *\n   * Naming the three families here would be a lie in the other direction: a\n   * caller cannot hand this format \"a pickle\" or \"a sqlite\" and expect it to\n   * route, because the whole point of the class is that `.static` declares\n   * nothing and the signature has to be read. The family belongs in\n   * `describe()`, which measures it, not in a static that asserts it.\n   */\n  static inputTypes = Object.freeze([ \"static\" ]);\n  static outputTypes = Object.freeze([ \"json\", \"payload\" ]);\n  static debugOutputTypes = Object.freeze([ \"raw\" ]);\n\n}\n\n/**\n * Build the shared probe payload.\n *\n * Formats report a plain probe-shaped object rather than constructing a\n * `CjsResourceProbe`, which keeps this module free of the decorated class and\n * of the build transform it needs.\n */\nfunction Probe(detected, verified, options)\n{\n  return {\n    format: \"static\",\n    source: \"buffer\",\n    supported: detected.decodable ? \"full\" : \"partial\",\n    confidence: detected.family === CJS_STATIC_FAMILIES.UNKNOWN ? 0.5 : 1,\n    preferred: detected.family,\n    verified,\n    reason: detected.reason ?? `Recognized a ${detected.family} container.`,\n    variants: [ { kind: \"container\", codec: detected.family, supported: detected.decodable } ],\n    metadata: verified\n      ? { ...detected, declared: null, resolved: detected.family, mismatch: false }\n      : detected,\n    ...(options || {})\n  };\n}\n\nfunction MatchesSqlite(bytes)\n{\n  if (bytes.byteLength < SQLITE_SIGNATURE.length) return false;\n\n  for (let index = 0; index < SQLITE_SIGNATURE.length; index++)\n  {\n    if (bytes[index] !== SQLITE_SIGNATURE.charCodeAt(index)) return false;\n  }\n\n  return true;\n}\n\nfunction MatchesPickle(bytes)\n{\n  // A protocol-0 pickle opens a container then names it: \"(dp1\\n\" or \"(lp1\\n\".\n  if (bytes.byteLength < PICKLE_PREFIX_BYTES + 3) return false;\n  if (bytes[PICKLE_PREFIX_BYTES] !== 0x28) return false;\n\n  const kind = bytes[PICKLE_PREFIX_BYTES + 1];\n\n  return kind === 0x64 || kind === 0x6c;\n}\n\nfunction Normalize(input)\n{\n  if (input instanceof ArrayBuffer) return new Uint8Array(input);\n\n  if (ArrayBuffer.isView(input))\n  {\n    return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);\n  }\n\n  const error = new TypeError(\"A .static container must be an ArrayBuffer or a view over one.\");\n\n  error.code = \"CJS_STATIC_INPUT_INVALID\";\n  throw error;\n}\n"],"names":["SQLITE_SIGNATURE","PICKLE_PREFIX_BYTES","CJS_STATIC_FAMILIES","Object","freeze","SQLITE","PICKLE","UNKNOWN","CjsStaticFormat","isSupported","input","options","Probe","describe","inspect","resolveType","bytes","Normalize","MatchesSqlite","family","byteLength","payloadOffset","prefix","decodable","requires","reason","MatchesPickle","view","DataView","buffer","byteOffset","getUint32","payload","detected","subarray","id","extensions","type","mediaTypes","inputTypes","outputTypes","debugOutputTypes","verified","format","source","supported","confidence","preferred","variants","kind","codec","metadata","declared","resolved","mismatch","length","index","charCodeAt","ArrayBuffer","Uint8Array","isView","error","TypeError","code"],"mappings":"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"}

package/dist/formats/static/index.js

@@ -0,0 +1,2 @@
+export { CJS_STATIC_FAMILIES, CjsStaticFormat, CjsStaticFormat as default } from './CjsStaticFormat.js';
+//# sourceMappingURL=index.js.map

package/dist/formats/static/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/formats/webgl/core/buildGlslEffectContainer.js

@@ -55,9 +55,11 @@ const GLSL_CONTAINER_BACKEND = Object.freeze({
  * Builds the complete WebGL 2 effect container.
  *
  * @param {object} effectRes Loaded version-15 `Tr2EffectRes`.
- * @param {object} permutationGraph Validated `PGRF` document.
+ * @param {object} permutationGraph Validated derived `CJS_EFFECT_PERMUTATION_GRAPH` document (no chunk is stored).
  * @param {object} backendBodySet Translated GLSL bodies.
  * @param {object} [options] Container options.
+ * @param {number} [options.version] Container data version to emit; defaults to
+ *     the current version. Independent of the source effect's version.
  * @param {number[]|Uint8Array} [options.compilerVersion] Four version bytes.
  * @param {string} [options.sourceHash] 32 ASCII hash characters.
  * @returns {{bytes:Uint8Array, permutationCount:number, bodyCount:number}} Container and its body accounting.

package/dist/formats/webgl/core/buildGlslEffectContainer.js.map

@@ -1 +1 @@
-{"version":3,"file":"buildGlslEffectContainer.js","sources":["../../../../../src/formats/webgl/core/buildGlslEffectContainer.js"],"sourcesContent":["import {\n    buildCarbonEffectContainer\n} from \"../../../format/carbonEffect/buildCarbonEffectContainer.js\";\nimport { writeGlslBackendBlock } from \"./glslBackendBlock.js\";\n\n/**\n * The WebGL 2 backend adapter for the shared Carbon container builder.\n *\n * The record layout, the permutation walk and the description mapping are shared\n * with WebGPU and live in `format/carbonEffect/buildCarbonEffectContainer.js`.\n * What remains here is the two backend-varying decisions: a program is GLSL ES\n * 3.00 text, and a pass's trailing block is the GLSL lowering data.\n *\n * There is no entry-point assertion to make. GLSL's entry point is `main` by\n * language rule rather than by our emitter's choice, so unlike WGSL there is\n * nothing a future lowerer could change.\n */\n\n/**\n * Encodes one GLSL stage program.\n *\n * @param {object} shader Translated shader record.\n * @returns {Uint8Array} Program bytes.\n */\nfunction encodeProgram(shader)\n{\n    return new TextEncoder().encode(shader.code);\n}\n\n/**\n * Builds the per-pass backend block for one pass of one translated body.\n *\n * A pass whose stages added no lowering data emits no block at all rather than\n * an empty one, so the description ends where Carbon's would and the optional\n * block stays genuinely optional.\n *\n * @param {object} unit Pass translation unit.\n * @param {string} passKey Enclosing pass key.\n * @returns {Uint8Array|null} Block bytes, or null when the pass has none.\n */\nfunction encodeBackendBlock(unit, passKey)\n{\n    const stages = unit.block;\n    const transforms = (unit.resourceTransforms ?? [])\n        .filter((transform) => transform.layoutKey === passKey);\n\n    if (!stages && !transforms.length) return null;\n\n    return writeGlslBackendBlock({ stages: stages ?? {}, transforms });\n}\n\n/** The WebGL encoders, as the shared builder's backend argument. */\nexport const GLSL_CONTAINER_BACKEND = Object.freeze({ encodeProgram, encodeBackendBlock });\n\n/**\n * Builds the complete WebGL 2 effect container.\n *\n * @param {object} effectRes Loaded version-15 `Tr2EffectRes`.\n * @param {object} permutationGraph Validated `PGRF` document.\n * @param {object} backendBodySet Translated GLSL bodies.\n * @param {object} [options] Container options.\n * @param {number[]|Uint8Array} [options.compilerVersion] Four version bytes.\n * @param {string} [options.sourceHash] 32 ASCII hash characters.\n * @returns {{bytes:Uint8Array, permutationCount:number, bodyCount:number}} Container and its body accounting.\n */\nexport function buildGlslEffectContainer(\n    effectRes,\n    permutationGraph,\n    backendBodySet,\n    options = {}\n)\n{\n    return buildCarbonEffectContainer(\n        effectRes,\n        permutationGraph,\n        backendBodySet,\n        GLSL_CONTAINER_BACKEND,\n        options\n    );\n}\n\nexport default buildGlslEffectContainer;\n"],"names":["encodeProgram","shader","TextEncoder","encode","code","encodeBackendBlock","unit","passKey","stages","block","transforms","resourceTransforms","filter","transform","layoutKey","length","writeGlslBackendBlock","GLSL_CONTAINER_BACKEND","Object","freeze","buildGlslEffectContainer","effectRes","permutationGraph","backendBodySet","options","buildCarbonEffectContainer"],"mappings":";;;AAKA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,aAAaA,CAACC,MAAM,EAC7B;EACI,OAAO,IAAIC,WAAW,EAAE,CAACC,MAAM,CAACF,MAAM,CAACG,IAAI,CAAC;AAChD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,kBAAkBA,CAACC,IAAI,EAAEC,OAAO,EACzC;AACI,EAAA,MAAMC,MAAM,GAAGF,IAAI,CAACG,KAAK;AACzB,EAAA,MAAMC,UAAU,GAAG,CAACJ,IAAI,CAACK,kBAAkB,IAAI,EAAE,EAC5CC,MAAM,CAAEC,SAAS,IAAKA,SAAS,CAACC,SAAS,KAAKP,OAAO,CAAC;EAE3D,IAAI,CAACC,MAAM,IAAI,CAACE,UAAU,CAACK,MAAM,EAAE,OAAO,IAAI;AAE9C,EAAA,OAAOC,qBAAqB,CAAC;AAAER,IAAAA,MAAM,EAAEA,MAAM,IAAI,EAAE;AAAEE,IAAAA;AAAW,GAAC,CAAC;AACtE;;AAEA;MACaO,sBAAsB,GAAGC,MAAM,CAACC,MAAM,CAAC;EAAEnB,aAAa;AAAEK,EAAAA;AAAmB,CAAC;;AAEzF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASe,wBAAwBA,CACpCC,SAAS,EACTC,gBAAgB,EAChBC,cAAc,EACdC,OAAO,GAAG,EAAE,EAEhB;EACI,OAAOC,0BAA0B,CAC7BJ,SAAS,EACTC,gBAAgB,EAChBC,cAAc,EACdN,sBAAsB,EACtBO,OACJ,CAAC;AACL;;;;"}
+{"version":3,"file":"buildGlslEffectContainer.js","sources":["../../../../../src/formats/webgl/core/buildGlslEffectContainer.js"],"sourcesContent":["import {\n    buildCarbonEffectContainer\n} from \"../../../format/carbonEffect/buildCarbonEffectContainer.js\";\nimport { writeGlslBackendBlock } from \"./glslBackendBlock.js\";\n\n/**\n * The WebGL 2 backend adapter for the shared Carbon container builder.\n *\n * The record layout, the permutation walk and the description mapping are shared\n * with WebGPU and live in `format/carbonEffect/buildCarbonEffectContainer.js`.\n * What remains here is the two backend-varying decisions: a program is GLSL ES\n * 3.00 text, and a pass's trailing block is the GLSL lowering data.\n *\n * There is no entry-point assertion to make. GLSL's entry point is `main` by\n * language rule rather than by our emitter's choice, so unlike WGSL there is\n * nothing a future lowerer could change.\n */\n\n/**\n * Encodes one GLSL stage program.\n *\n * @param {object} shader Translated shader record.\n * @returns {Uint8Array} Program bytes.\n */\nfunction encodeProgram(shader)\n{\n    return new TextEncoder().encode(shader.code);\n}\n\n/**\n * Builds the per-pass backend block for one pass of one translated body.\n *\n * A pass whose stages added no lowering data emits no block at all rather than\n * an empty one, so the description ends where Carbon's would and the optional\n * block stays genuinely optional.\n *\n * @param {object} unit Pass translation unit.\n * @param {string} passKey Enclosing pass key.\n * @returns {Uint8Array|null} Block bytes, or null when the pass has none.\n */\nfunction encodeBackendBlock(unit, passKey)\n{\n    const stages = unit.block;\n    const transforms = (unit.resourceTransforms ?? [])\n        .filter((transform) => transform.layoutKey === passKey);\n\n    if (!stages && !transforms.length) return null;\n\n    return writeGlslBackendBlock({ stages: stages ?? {}, transforms });\n}\n\n/** The WebGL encoders, as the shared builder's backend argument. */\nexport const GLSL_CONTAINER_BACKEND = Object.freeze({ encodeProgram, encodeBackendBlock });\n\n/**\n * Builds the complete WebGL 2 effect container.\n *\n * @param {object} effectRes Loaded version-15 `Tr2EffectRes`.\n * @param {object} permutationGraph Validated derived `CJS_EFFECT_PERMUTATION_GRAPH` document (no chunk is stored).\n * @param {object} backendBodySet Translated GLSL bodies.\n * @param {object} [options] Container options.\n * @param {number} [options.version] Container data version to emit; defaults to\n *     the current version. Independent of the source effect's version.\n * @param {number[]|Uint8Array} [options.compilerVersion] Four version bytes.\n * @param {string} [options.sourceHash] 32 ASCII hash characters.\n * @returns {{bytes:Uint8Array, permutationCount:number, bodyCount:number}} Container and its body accounting.\n */\nexport function buildGlslEffectContainer(\n    effectRes,\n    permutationGraph,\n    backendBodySet,\n    options = {}\n)\n{\n    return buildCarbonEffectContainer(\n        effectRes,\n        permutationGraph,\n        backendBodySet,\n        GLSL_CONTAINER_BACKEND,\n        options\n    );\n}\n\nexport default buildGlslEffectContainer;\n"],"names":["encodeProgram","shader","TextEncoder","encode","code","encodeBackendBlock","unit","passKey","stages","block","transforms","resourceTransforms","filter","transform","layoutKey","length","writeGlslBackendBlock","GLSL_CONTAINER_BACKEND","Object","freeze","buildGlslEffectContainer","effectRes","permutationGraph","backendBodySet","options","buildCarbonEffectContainer"],"mappings":";;;AAKA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,aAAaA,CAACC,MAAM,EAC7B;EACI,OAAO,IAAIC,WAAW,EAAE,CAACC,MAAM,CAACF,MAAM,CAACG,IAAI,CAAC;AAChD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,kBAAkBA,CAACC,IAAI,EAAEC,OAAO,EACzC;AACI,EAAA,MAAMC,MAAM,GAAGF,IAAI,CAACG,KAAK;AACzB,EAAA,MAAMC,UAAU,GAAG,CAACJ,IAAI,CAACK,kBAAkB,IAAI,EAAE,EAC5CC,MAAM,CAAEC,SAAS,IAAKA,SAAS,CAACC,SAAS,KAAKP,OAAO,CAAC;EAE3D,IAAI,CAACC,MAAM,IAAI,CAACE,UAAU,CAACK,MAAM,EAAE,OAAO,IAAI;AAE9C,EAAA,OAAOC,qBAAqB,CAAC;AAAER,IAAAA,MAAM,EAAEA,MAAM,IAAI,EAAE;AAAEE,IAAAA;AAAW,GAAC,CAAC;AACtE;;AAEA;MACaO,sBAAsB,GAAGC,MAAM,CAACC,MAAM,CAAC;EAAEnB,aAAa;AAAEK,EAAAA;AAAmB,CAAC;;AAEzF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASe,wBAAwBA,CACpCC,SAAS,EACTC,gBAAgB,EAChBC,cAAc,EACdC,OAAO,GAAG,EAAE,EAEhB;EACI,OAAOC,0BAA0B,CAC7BJ,SAAS,EACTC,gBAAgB,EAChBC,cAAc,EACdN,sBAAsB,EACtBO,OACJ,CAAC;AACL;;;;"}

package/dist/formats/webgl/core/effectPackage.js

@@ -3,9 +3,9 @@ import { HlslRenderContextEnum, hlslShaderStageName } from '../../hlsl/core/tr2/
 import '@carbonenginejs/runtime-utils/bytes';
 import '../../hlsl/core/carbonDescriptionToRuntime.js';
 import '../../../format/CjsByteReader.js';
-import '../../../format/compareUtf8.js';
+import { resolveWriteVersion } from '../../../format/carbonEffect/carbonEffectRecords.js';
 import { HlslEffectBindingManifest } from '../../hlsl/core/tr2/shader/HlslEffectBindingManifest.js';
-import { buildEffectPermutationGraph, EFFECT_PERMUTATION_GRAPH_VERSION, EFFECT_PERMUTATION_GRAPH_FORMAT, EFFECT_PERMUTATION_GRAPH_CHUNK } from '../../../format/effect/effectPermutationGraph.js';
+import { buildEffectPermutationGraph, EFFECT_PERMUTATION_GRAPH_VERSION, EFFECT_PERMUTATION_GRAPH_FORMAT } from '../../../format/effect/effectPermutationGraph.js';
 import { emitGlslWithOptions } from './helpers.js';
 import { inspectGlslEffectContainer } from './inspectGlslEffectContainer.js';
 import { inspectRasterCompleteness } from './glslEffectCompleteness.js';
@@ -38,6 +38,9 @@ const PACKAGE_VERSION = "0.11.1";
  */
 function buildEffectPackage(input, options = {}) {
   const values = normalizeOptions(input, options);
+  // Resolved before any translation work, so an unwritable version is refused
+  // up front. What lands in `info.containerVersion` is what was emitted.
+  const containerVersion = resolveWriteVersion(options.version);
   const effectRes = CjsHlslFormat.read(values.sourceBytes, {
     emit: CjsHlslFormat.OUTPUT_RAW,
     source: values.source
@@ -155,6 +158,11 @@ function buildEffectPackage(input, options = {}) {
     format: "CARBON_WEBGL",
     formatVersion: EFFECT_INFO_VERSION,
     packageKind: values.allPermutations ? "tr2-effect-webgl-permutations" : "tr2-effect-webgl",
+    // What these bytes ARE, next to `sourceEffectVersion` below, which is
+    // what they were read FROM. The reader accepts 8..15; the writer emits
+    // 15 only, so the two are not the same number and a consumer must not
+    // infer one from the other.
+    containerVersion,
     targetBackend: "webgl",
     backendPackage: "@carbonenginejs/runtime-resource/formats/webgl",
     backendPackageVersion: PACKAGE_VERSION,
@@ -181,7 +189,6 @@ function buildEffectPackage(input, options = {}) {
     sourcePermutationCount: permutationGraph.variants.length,
     sourceUniqueBodyCount: permutationGraph.bodies.length,
     permutationGraph: {
-      chunk: EFFECT_PERMUTATION_GRAPH_CHUNK,
       format: EFFECT_PERMUTATION_GRAPH_FORMAT,
       formatVersion: EFFECT_PERMUTATION_GRAPH_VERSION,
       sha256: sha256Utf8(`${JSON.stringify(permutationGraph)}\n`),
@@ -271,7 +278,8 @@ function buildEffectPackage(input, options = {}) {
     permutationGraph
   });
   const container = buildGlslEffectContainer(effectRes, permutationGraph, backendBodySet, {
-    compilerVersion: effectRes.m_compilerVersionBytes
+    compilerVersion: effectRes.m_compilerVersionBytes,
+    version: containerVersion
   });
   const bytes = container.bytes;
   const inspection = inspectGlslEffectContainer(bytes, {
@@ -330,7 +338,7 @@ function normalizeOptions(input, options) {
     // bit 0, so the shader's own guard skips the lookup for every light. A
     // dropped profile is therefore observationally identical today and a
     // real loss only once profile indices are written.
-    // See /docs/contracts/carbon-light-data.md.
+    // Revisit when a profile index is actually written to those bits.
     lightProfile: normalizeLightProfileMode(options.lightProfile),
     emitterOptions: {
       ...(options.emitterOptions ?? {})