@carbonenginejs/runtime 0.1.0-alpha.0 → 0.1.0-alpha.2

package/docs/resource/formats/static.md

@@ -21,31 +21,30 @@ The six unidentified files are exactly the six with a `.schema` companion —
 `constellations`, `dialogs`, `factionsowningsolarsystems`, `jumps`, `regions`
 and `systems` — so the detector's "unknown" set is not a gap in coverage but the
 family that cannot be read without its companion.
-
-## Boundary
-
-`CjsStaticFormat` identifies. It decodes nothing.
-
-- **SQLite** containers hold `cache(key, value, time)` and
-  `indexes(key, value)`, with a JSON document per record.
-- **Embedded-schema** containers put a schema, not a record, behind that prefix.
-  The prefix is the schema's LENGTH: read `[4, 4 + length)` with
-  `CjsPickleFormat` and hand the rest to `CjsSchemaBoundFormat`.
-- **Sibling-schema** containers report `unknown` with `requires: "schema"`, and
-  are decoded by `CjsSchemaBoundFormat` once the caller has that companion.
-
-Detection is signature-based. It never trusts a file name and never executes
-anything.
-
-## This format identifies; it does not decode
-
-It reports the family, where the payload starts, and what is still missing. The
-caller takes that to the format that owns the family:
-
-```js
-const metadata = CjsStaticFormat.inspect(bytes);
-
-if (metadata.family === CJS_STATIC_FAMILIES.SQLITE)
+
+## Boundary
+
+`CjsStaticFormat` identifies the family, payload offset and missing inputs by
+signature, never by filename. It decodes and executes nothing.
+
+- **SQLite** holds `cache(key, value, time)` and `indexes(key, value)`,
+  with a JSON document per record.
+- **Embedded schema** has a four-byte schema length, then a pickled schema
+  and binary payload; split them as shown below.
+- **Sibling schema** reports `unknown` with `requires: "schema"`;
+  `CjsSchemaBoundFormat` decodes it with the supplied companion.
+
+## This format identifies; it does not decode
+
+Route the inspected family to its decoder:
+
+```js
+import { CjsStaticFormat, CJS_STATIC_FAMILIES } from
+    "@carbonenginejs/runtime/resource/formats/static";
+
+const metadata = CjsStaticFormat.inspect(bytes);
+
+if (metadata.family === CJS_STATIC_FAMILIES.SQLITE)
 {
   return CjsSqliteFormat.readJSON(bytes);
 }
@@ -60,54 +59,33 @@ if (metadata.family === CJS_STATIC_FAMILIES.PICKLE)
   return CjsSchemaBoundFormat.read(bytes.subarray(4 + length), {
     schema: CjsPickleFormat.read(bytes.subarray(4, 4 + length))
   });
-}
-```
-
-**This changed on 2026-08-15.** A `read()` here dispatched to those two formats
-itself, and the SQLite family additionally required a driver injected through
-`options.sqlite`. Both are gone. An identification format should not be the
-routing table for two others, and deciding what to decode belongs to whoever
-asked. Nothing outside this format's own tests ever called `read()`.
-
-
-## Both of the remaining families are the same container
-
-The schema is encoded differently; the payload behind it is identical.
-
-**The pickle behind that prefix is a SCHEMA, not a record.** Protocol 0's `c`
-(`GLOBAL`) and `R` form an import-and-call execution path. These files require
-only `collections.OrderedDict` to preserve schema field order; the reader
-rebuilds it as a plain object and refuses every other global. See
-[the pickle format](pickle.md).
-
-**The sibling-schema family states its layout in YAML:** sizes, types, optional
-flags, list item sizes, vector precision and a key-to-offset footer.
-**Nothing needs deriving** or pinning from an externally defined layout;
-[`CjsSchemaBoundFormat`](schemabound.md) reads the supplied schema. All six
-datasets decode the map skeleton of regions, constellations and systems.
-Celestial detail (moons, planets, belts, stars, gates) belongs to the
-embedded-schema family.
-
-## Use
-
-Identification uses the shared synchronous inspection seam; see
-[format capabilities](../concepts/format-capabilities.md).
-
-```js
-import { CjsStaticFormat, CJS_STATIC_FAMILIES } from
-    "@carbonenginejs/runtime/resource/formats/static";
-
-const metadata = CjsStaticFormat.inspect(bytes);
-
-if (metadata.family === CJS_STATIC_FAMILIES.PICKLE)
-{
-    // See the routing example above: the prefix is a schema length.
-}
-```
-
-`is()` is the boolean routing predicate and `inspect()` returns the identified
-family. `getSupport()` reports `recognized: true` for SQLite and prefixed
-pickle, but `supported: false`: `CjsStaticFormat` deliberately declares no
+}
+```
+
+**Changed 2026-08-15:** the former dispatching `read()` and its injected
+`options.sqlite` driver were removed; only this format's own tests called it.
+Callers choose decoders, or use the separate routing helpers below.
+
+## Both of the remaining families are the same container
+
+Both share the binary payload layout; only schema encoding differs.
+Embedded schemas use the pickle reader's
+[closed OrderedDict exception](pickle.md#one-global-is-rebuilt-and-it-is-a-closed-set),
+not executable Python reconstruction. Sibling YAML declares sizes, types,
+optional flags, list item sizes, vector precision and a key-to-offset footer;
+[schema-bound decoding](schemabound.md) needs no externally derived layout.
+The six sibling-schema datasets decode the regions/constellations/systems map
+skeleton; embedded-schema datasets hold celestial detail (moons, planets,
+belts, stars and gates).
+
+## Use
+
+See [format capabilities](../concepts/format-capabilities.md) for the shared
+synchronous inspection seam.
+
+`is()` is the boolean routing predicate and `inspect()` returns the identified
+family. `getSupport()` reports `recognized: true` for SQLite and prefixed
+pickle, but `supported: false`: `CjsStaticFormat` deliberately declares no
 outputs and decodes nothing. `verifySupport()` therefore returns
 `CJS_FORMAT_OUTPUT_UNDECLARED` instead of pretending family identification is
 a decoder capability.
@@ -118,35 +96,30 @@ building a probe. `payload()` slices at `payloadOffset`: for embedded-schema
 input this removes only the four-byte length prefix, leaving the pickled schema
 and binary payload together. Use the explicit split above or
 `ReadEmbeddedSchemaContainer` to decode that family.
-
-## Reading a container, rather than identifying one
-
-Identifying a family and then routing it to the format that owns it is the same
-twenty lines in every caller, so they are written once here and exported from the
-same subpath:
-
-```js
-import {
+
+## Reading a container, rather than identifying one
+
+Separate routing helpers share the identification subpath:
+
+```js
+import {
     ReadStaticContainer,          // SQLite family
     ReadEmbeddedSchemaContainer,  // schema length, pickled schema, payload
     ReadSchemaBoundContainer,     // payload plus its .schema sibling
 } from "@carbonenginejs/runtime/resource/formats/static";
 
-const skins = await ReadStaticContainer(bytes, "res:/staticdata/skins.static");
-```
-
-The `path` argument only ever names the file in an error.
-
-The routing helpers import the wrapped pickle, schema-bound and SQLite formats;
-they reach nothing outside `formats/`.
-
-`CjsStaticFormat` imports the shared `CjsFormat` base, but no concrete decoding
-formats, and decodes nothing. Routing remains in a sibling module, separate from
-the identification role established on 2026-08-15.
-
-### Errors
-
-| Code | When |
+const skins = await ReadStaticContainer(bytes, "res:/staticdata/skins.static");
+```
+
+The `path` argument only names the file in errors. Helpers in a sibling
+module import the wrapped pickle, schema-bound and SQLite formats, reaching
+nothing outside `formats/`. `CjsStaticFormat` imports the shared
+`CjsFormat` base, not concrete decoders: the 2026-08-15 identification
+boundary remains intact.
+
+### Errors
+
+| Code | When |
 | --- | --- |
 | `CJS_STATIC_FORMAT_FAMILY_UNSUPPORTED` | the bytes are a `.static` of a family this reader does not read; carries `family` |
 | `CJS_STATIC_FORMAT_SHAPE_INVALID` | right family, wrong container - no `cache` table, or a schema length running past the end |

package/docs/resource/formats/webgl/carbon-constant-layouts.md

@@ -130,14 +130,14 @@ plain `memcpy` of the struct). Bound to b3/b4 via
 
 Total = **29 registers**.
 
-**Joints are NOT in this buffer on DX11.** `boneOffsets` (reg 26) index a
-separate `BoneTransforms` ring buffer/SSBO
-(`m_boneOffsets.UploadTransforms(... Float4x3 ...)`, `EveSpaceObject2.cpp:1441`).
-Bones are `Float4x3` (3 vec4 per joint). This is the structured-buffer path
-that `docs/dxbc-lowering/memory-structured.md:131-213` rewrites for WebGL2.
-
-### 2b. `EveSpaceObjectPSData` -> b4
-
+**Joints are NOT in this buffer on DX11.** `boneOffsets` (reg 26) index a
+separate `BoneTransforms` ring buffer/SSBO
+(`m_boneOffsets.UploadTransforms(... Float4x3 ...)`, `EveSpaceObject2.cpp:1441`).
+Bones are `Float4x3` (3 vec4 per joint). See the
+[historical WebGL2 `cb3` rewrite and its recorded August 2 `std140` UBO replacement](memory-structured.md#glsl-lowering--b-webgl2-cb3-joint-matrix-rewrite-contract-the-shipping-path).
+
+### 2b. `EveSpaceObjectPSData` -> b4
+
 | Field | Type | vec4 off | count | Fed from |
 |---|---|---|---|---|
 | worldTransform | Matrix | 0 | 4 | `m_vsData.worldTransform` (`:646`) |