@carbonenginejs/runtime-resource 0.18.0 → 0.19.0

package/dist/formats/static/CjsStaticFormat.js

@@ -0,0 +1,222 @@
+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.
+ * - **Embedded schema** — a four-byte little-endian SCHEMA LENGTH followed by
+ *   that schema as a protocol-0 pickle, and then a payload. The prefix is not a
+ *   wrapper to skip: slice `[4, 4 + length)` for the schema and give the rest
+ *   to `CjsSchemaBoundFormat`. All 25 of these name one global,
+ *   `collections.OrderedDict`, which the pickle reader rebuilds as plain data.
+ * - **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 map skeleton of regions,
+ *   constellations and systems. `CjsSchemaBoundFormat` reads it, given that
+ *   companion, and reads the embedded-schema family above from the same code.
+ *
+ * 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_FORMAT_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 * - **Embedded schema** — a four-byte little-endian SCHEMA LENGTH followed by\n *   that schema as a protocol-0 pickle, and then a payload. The prefix is not a\n *   wrapper to skip: slice `[4, 4 + length)` for the schema and give the rest\n *   to `CjsSchemaBoundFormat`. All 25 of these name one global,\n *   `collections.OrderedDict`, which the pickle reader rebuilds as plain data.\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 map skeleton of regions,\n *   constellations and systems. `CjsSchemaBoundFormat` reads it, given that\n *   companion, and reads the embedded-schema family above from the same code.\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_FORMAT_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,3 @@
+export { CJS_STATIC_FAMILIES, CjsStaticFormat, CjsStaticFormat as default } from './CjsStaticFormat.js';
+export { ReadEmbeddedSchemaContainer, ReadSchemaBoundContainer, ReadStaticContainer } from './staticContainers.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/static/staticContainers.js

@@ -0,0 +1,157 @@
+import { CjsPickleFormat } from '../pickle/CjsPickleFormat.js';
+import { CjsSchemaBoundFormat } from '../schemabound/CjsSchemaBoundFormat.js';
+import { CjsSqliteFormat } from '../sqlite/CjsSqliteFormat.js';
+import { CjsStaticFormat, CJS_STATIC_FAMILIES } from './CjsStaticFormat.js';
+
+/**
+ * Reads a client `.static` container of whichever family it holds.
+ *
+ * `.static` names a role rather than a format, and three unrelated containers
+ * wear the extension, so identification and decoding are separate jobs done by
+ * separate formats. `CjsStaticFormat` says which family the bytes hold and
+ * decodes nothing; these functions take that answer to the format that owns the
+ * family. Nothing routes on the extension, which proves nothing.
+ *
+ * Reading a `.static` needs the three formats that own its families, so this
+ * module imports them. That is the format depending on formats, which is what a
+ * container format that wraps other containers has to do; what a format must not
+ * do is drag the rest of the library in behind it, and nothing here reaches
+ * outside `formats/`.
+ *
+ * It is a sibling of `CjsStaticFormat` rather than part of it, which keeps the
+ * 2026-08-15 decision intact: that class dispatched to two other formats and was
+ * cut back to identifying only, so that identification is not also the routing
+ * table. Routing lives here and the identification stays clean.
+ *
+ * Nothing here is specific to one publisher or one export. Measured 2026-08-16
+ * across three publishers at builds 3466501, 3466054 and 3466057: 45 `.static`
+ * files on each, split 14 SQLite, 25 embedded-schema and 6 schema-companion,
+ * with not one file unique to a publisher and not one that changes family
+ * between them.
+ */
+
+const CACHE_TABLE = "cache";
+
+/** Raises a family mismatch, naming what was found and what was wanted. */
+function FamilyError(path, found, wanted, reason) {
+  const error = new TypeError(`${path} is a ${found} .static container, not a ${wanted} one.${reason ? ` ${reason}` : ""}`);
+  error.code = "CJS_STATIC_FORMAT_FAMILY_UNSUPPORTED";
+  error.family = found;
+  error.path = path;
+  return error;
+}
+
+/**
+ * Reads the SQLite family into records keyed by their container key.
+ *
+ * The record shape is the container's own: a `cache` table of `key`, `value`
+ * and `time`, where every `value` is a JSON document.
+ *
+ * @param {Uint8Array|ArrayBuffer} bytes Container bytes.
+ * @param {string} [path] Logical path, for error messages.
+ * @returns {Promise<object>} Records keyed by their container key.
+ */
+async function ReadStaticContainer(bytes, path = ".static input") {
+  const probe = await CjsStaticFormat.resolveType(bytes);
+  if (probe.preferred !== CJS_STATIC_FAMILIES.SQLITE) {
+    throw FamilyError(path, probe.preferred, CJS_STATIC_FAMILIES.SQLITE, probe.reason);
+  }
+  const tables = CjsSqliteFormat.readJSON(bytes, {
+    tables: [CACHE_TABLE]
+  });
+  const rows = tables[CACHE_TABLE];
+  if (!Array.isArray(rows)) {
+    const error = new TypeError(`${path} has no ${CACHE_TABLE} table.`);
+    error.code = "CJS_STATIC_FORMAT_SHAPE_INVALID";
+    error.path = path;
+    throw error;
+  }
+  const records = {};
+  for (const row of rows) {
+    records[String(row.key)] = ParseRecord(row.value, row.key, path);
+  }
+  return records;
+}
+
+/**
+ * Reads the family whose schema is embedded ahead of the payload.
+ *
+ * The framing is a `uint32` schema length, the schema as a protocol-0 pickle,
+ * and then a payload in exactly the container `CjsSchemaBoundFormat` reads. It
+ * is the same format as the `.schema` sibling family; only the schema's encoding
+ * differs.
+ *
+ * **Slice the schema exactly.** Handing the whole file to a pickle reader fails,
+ * but it fails on the payload's bytes long after the schema has parsed, so the
+ * error names an opcode and points nowhere near the real boundary. That reading
+ * is what left this family classified as a separate self-describing format for
+ * as long as it was.
+ *
+ * @param {Uint8Array|ArrayBuffer} bytes Container bytes.
+ * @param {string} [path] Logical path, for error messages.
+ * @returns {object|Array} Decoded records.
+ */
+function ReadEmbeddedSchemaContainer(bytes, path = ".static input") {
+  const source = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  if (source.byteLength < 4) {
+    const error = new TypeError(`${path} is too short to carry a schema length.`);
+    error.code = "CJS_STATIC_FORMAT_SHAPE_INVALID";
+    error.path = path;
+    throw error;
+  }
+  const view = new DataView(source.buffer, source.byteOffset, source.byteLength);
+  const length = view.getUint32(0, true);
+  if (length <= 0 || length + 4 > source.byteLength) {
+    const error = new TypeError(`${path} does not begin with a usable schema length.`);
+    error.code = "CJS_STATIC_FORMAT_SHAPE_INVALID";
+    error.path = path;
+    throw error;
+  }
+  return CjsSchemaBoundFormat.read(source.subarray(4 + length), {
+    schema: CjsPickleFormat.read(source.subarray(4, 4 + length))
+  });
+}
+
+/**
+ * Reads the family whose layout lives in a `.schema` sibling.
+ *
+ * The family check is worth keeping even though the caller already fetched a
+ * `.schema` alongside the payload, because these bytes carry no signature at
+ * all - given the wrong schema they decode into plausible nonsense rather than
+ * failing, so the one cheap guard there is belongs in the path.
+ *
+ * @param {Uint8Array|ArrayBuffer} bytes Container bytes.
+ * @param {Uint8Array|ArrayBuffer|string|object} schema The sibling `.schema`.
+ * @param {string} [path] Logical path, for error messages.
+ * @returns {Promise<object|Array>} Decoded records.
+ */
+async function ReadSchemaBoundContainer(bytes, schema, path = ".static input") {
+  const probe = await CjsStaticFormat.resolveType(bytes);
+
+  // The schema-bound family is the one with nothing to recognize, so it is
+  // reported as `unknown` with `requires: "schema"` rather than named outright.
+  if (probe.preferred !== CJS_STATIC_FAMILIES.UNKNOWN) {
+    throw FamilyError(path, probe.preferred, "schema-bound", null);
+  }
+  return CjsSchemaBoundFormat.read(bytes, {
+    schema
+  });
+}
+
+/** Parses one stored JSON document, naming the record that failed. */
+function ParseRecord(value, key, path) {
+  try {
+    return JSON.parse(value);
+  } catch (cause) {
+    const error = new TypeError(`${path} record ${key} is not JSON.`, {
+      cause
+    });
+    error.code = "CJS_STATIC_FORMAT_RECORD_INVALID";
+    error.key = String(key);
+    error.path = path;
+    throw error;
+  }
+}
+
+export { ReadEmbeddedSchemaContainer, ReadSchemaBoundContainer, ReadStaticContainer };
+//# sourceMappingURL=staticContainers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"staticContainers.js","sources":["../../../../src/formats/static/staticContainers.js"],"sourcesContent":["import { CjsPickleFormat } from \"../pickle/index.js\";\nimport { CjsSchemaBoundFormat } from \"../schemabound/index.js\";\nimport { CjsSqliteFormat } from \"../sqlite/index.js\";\nimport { CJS_STATIC_FAMILIES, CjsStaticFormat } from \"./CjsStaticFormat.js\";\n\n/**\n * Reads a client `.static` container of whichever family it holds.\n *\n * `.static` names a role rather than a format, and three unrelated containers\n * wear the extension, so identification and decoding are separate jobs done by\n * separate formats. `CjsStaticFormat` says which family the bytes hold and\n * decodes nothing; these functions take that answer to the format that owns the\n * family. Nothing routes on the extension, which proves nothing.\n *\n * Reading a `.static` needs the three formats that own its families, so this\n * module imports them. That is the format depending on formats, which is what a\n * container format that wraps other containers has to do; what a format must not\n * do is drag the rest of the library in behind it, and nothing here reaches\n * outside `formats/`.\n *\n * It is a sibling of `CjsStaticFormat` rather than part of it, which keeps the\n * 2026-08-15 decision intact: that class dispatched to two other formats and was\n * cut back to identifying only, so that identification is not also the routing\n * table. Routing lives here and the identification stays clean.\n *\n * Nothing here is specific to one publisher or one export. Measured 2026-08-16\n * across three publishers at builds 3466501, 3466054 and 3466057: 45 `.static`\n * files on each, split 14 SQLite, 25 embedded-schema and 6 schema-companion,\n * with not one file unique to a publisher and not one that changes family\n * between them.\n */\n\nconst CACHE_TABLE = \"cache\";\n\n/** Raises a family mismatch, naming what was found and what was wanted. */\nfunction FamilyError(path, found, wanted, reason)\n{\n    const error = new TypeError(\n        `${path} is a ${found} .static container, not a ${wanted} one.${reason ? ` ${reason}` : \"\"}`,\n    );\n\n    error.code = \"CJS_STATIC_FORMAT_FAMILY_UNSUPPORTED\";\n    error.family = found;\n    error.path = path;\n\n    return error;\n}\n\n/**\n * Reads the SQLite family into records keyed by their container key.\n *\n * The record shape is the container's own: a `cache` table of `key`, `value`\n * and `time`, where every `value` is a JSON document.\n *\n * @param {Uint8Array|ArrayBuffer} bytes Container bytes.\n * @param {string} [path] Logical path, for error messages.\n * @returns {Promise<object>} Records keyed by their container key.\n */\nexport async function ReadStaticContainer(bytes, path = \".static input\")\n{\n    const probe = await CjsStaticFormat.resolveType(bytes);\n\n    if (probe.preferred !== CJS_STATIC_FAMILIES.SQLITE)\n    {\n        throw FamilyError(path, probe.preferred, CJS_STATIC_FAMILIES.SQLITE, probe.reason);\n    }\n\n    const tables = CjsSqliteFormat.readJSON(bytes, { tables: [ CACHE_TABLE ] });\n    const rows = tables[CACHE_TABLE];\n\n    if (!Array.isArray(rows))\n    {\n        const error = new TypeError(`${path} has no ${CACHE_TABLE} table.`);\n\n        error.code = \"CJS_STATIC_FORMAT_SHAPE_INVALID\";\n        error.path = path;\n        throw error;\n    }\n\n    const records = {};\n\n    for (const row of rows)\n    {\n        records[String(row.key)] = ParseRecord(row.value, row.key, path);\n    }\n\n    return records;\n}\n\n/**\n * Reads the family whose schema is embedded ahead of the payload.\n *\n * The framing is a `uint32` schema length, the schema as a protocol-0 pickle,\n * and then a payload in exactly the container `CjsSchemaBoundFormat` reads. It\n * is the same format as the `.schema` sibling family; only the schema's encoding\n * differs.\n *\n * **Slice the schema exactly.** Handing the whole file to a pickle reader fails,\n * but it fails on the payload's bytes long after the schema has parsed, so the\n * error names an opcode and points nowhere near the real boundary. That reading\n * is what left this family classified as a separate self-describing format for\n * as long as it was.\n *\n * @param {Uint8Array|ArrayBuffer} bytes Container bytes.\n * @param {string} [path] Logical path, for error messages.\n * @returns {object|Array} Decoded records.\n */\nexport function ReadEmbeddedSchemaContainer(bytes, path = \".static input\")\n{\n    const source = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);\n\n    if (source.byteLength < 4)\n    {\n        const error = new TypeError(`${path} is too short to carry a schema length.`);\n\n        error.code = \"CJS_STATIC_FORMAT_SHAPE_INVALID\";\n        error.path = path;\n        throw error;\n    }\n\n    const view = new DataView(source.buffer, source.byteOffset, source.byteLength);\n    const length = view.getUint32(0, true);\n\n    if (length <= 0 || length + 4 > source.byteLength)\n    {\n        const error = new TypeError(`${path} does not begin with a usable schema length.`);\n\n        error.code = \"CJS_STATIC_FORMAT_SHAPE_INVALID\";\n        error.path = path;\n        throw error;\n    }\n\n    return CjsSchemaBoundFormat.read(source.subarray(4 + length), {\n        schema: CjsPickleFormat.read(source.subarray(4, 4 + length)),\n    });\n}\n\n/**\n * Reads the family whose layout lives in a `.schema` sibling.\n *\n * The family check is worth keeping even though the caller already fetched a\n * `.schema` alongside the payload, because these bytes carry no signature at\n * all - given the wrong schema they decode into plausible nonsense rather than\n * failing, so the one cheap guard there is belongs in the path.\n *\n * @param {Uint8Array|ArrayBuffer} bytes Container bytes.\n * @param {Uint8Array|ArrayBuffer|string|object} schema The sibling `.schema`.\n * @param {string} [path] Logical path, for error messages.\n * @returns {Promise<object|Array>} Decoded records.\n */\nexport async function ReadSchemaBoundContainer(bytes, schema, path = \".static input\")\n{\n    const probe = await CjsStaticFormat.resolveType(bytes);\n\n    // The schema-bound family is the one with nothing to recognize, so it is\n    // reported as `unknown` with `requires: \"schema\"` rather than named outright.\n    if (probe.preferred !== CJS_STATIC_FAMILIES.UNKNOWN)\n    {\n        throw FamilyError(path, probe.preferred, \"schema-bound\", null);\n    }\n\n    return CjsSchemaBoundFormat.read(bytes, { schema });\n}\n\n/** Parses one stored JSON document, naming the record that failed. */\nfunction ParseRecord(value, key, path)\n{\n    try\n    {\n        return JSON.parse(value);\n    }\n    catch (cause)\n    {\n        const error = new TypeError(`${path} record ${key} is not JSON.`, { cause });\n\n        error.code = \"CJS_STATIC_FORMAT_RECORD_INVALID\";\n        error.key = String(key);\n        error.path = path;\n        throw error;\n    }\n}\n"],"names":["CACHE_TABLE","FamilyError","path","found","wanted","reason","error","TypeError","code","family","ReadStaticContainer","bytes","probe","CjsStaticFormat","resolveType","preferred","CJS_STATIC_FAMILIES","SQLITE","tables","CjsSqliteFormat","readJSON","rows","Array","isArray","records","row","String","key","ParseRecord","value","ReadEmbeddedSchemaContainer","source","Uint8Array","byteLength","view","DataView","buffer","byteOffset","length","getUint32","CjsSchemaBoundFormat","read","subarray","schema","CjsPickleFormat","ReadSchemaBoundContainer","UNKNOWN","JSON","parse","cause"],"mappings":"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"}

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,7 +3,7 @@ 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 } from '../../../format/effect/effectPermutationGraph.js';
 import { emitGlslWithOptions } from './helpers.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,
@@ -270,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, {