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

package/docs/global/reference/classes/README.md

@@ -1,4 +1,4 @@
-# Runtime global foundation class reference
+# Runtime global foundation class reference
 
 Status: Evolving
 Scope: `@carbonenginejs/runtime` class exports
@@ -25,75 +25,57 @@ Terminal constant-buffer bytes with an explicit upload dirty lifecycle.
 - Visibility: Public
 - Kind: CarbonEngineJS
 
-<!-- class:CjsFrameLifecycle -->
-## `CjsFrameLifecycle`
-
-Dependency-free engine lifecycle required to execute one runtime frame.
-
-- Export: `@carbonenginejs/runtime/contracts`
-- Source: `src/global/contracts/CjsFrameLifecycle.js`
-- Visibility: Public
-- Kind: CarbonEngineJS
-
-<!-- class:CjsInstancedMeshManager -->
-## `CjsInstancedMeshManager`
-
-Dependency-free contract through which Trinity registers CPU instancing data with an engine-owned realization and receives opaque handles that Trinity never inspects or mutates.
-
-- Export: `@carbonenginejs/runtime/contracts`
-- Source: `src/global/contracts/CjsInstancedMeshManager.js`
-- Visibility: Public
-- Kind: CarbonEngineJS
-
-<!-- class:ITr2BoundingBox -->
-## `ITr2BoundingBox`
-
-Dependency-free abstract contract for objects that publish ready world-space axis-aligned bounds, with a mixin for providers that already inherit a model base.
-
-- Export: `@carbonenginejs/runtime/contracts`
-- Source: `src/global/contracts/ITr2BoundingBox.js`
-- Visibility: Public
-- Kind: CarbonEngineJS
-
-<!-- class:ITr2RenderNode -->
-## `ITr2RenderNode`
-
-Dependency-free contract for one node in a Trinity render graph.
-
-- Export: `@carbonenginejs/runtime/contracts`
-- Source: `src/global/contracts/ITr2RenderNode.js`
-- Visibility: Public
-- Kind: CarbonEngineJS
-
-<!-- class:CjsScriptCallback -->
-## `CjsScriptCallback`
-
-Dependency-free callback identity for Carbon-style script invocation.
-
-- Export: `@carbonenginejs/runtime/contracts`
-- Source: `src/global/contracts/CjsScriptCallback.js`
-- Visibility: Public
-- Kind: CarbonEngineJS
-
-<!-- class:CjsFunctionScriptCallback -->
-## `CjsFunctionScriptCallback`
-
-Adapts one ordinary JavaScript function to the nominal callback contract.
-
-- Source: `src/global/contracts/CjsScriptCallback.js`
-- Visibility: Internal
-- Kind: CarbonEngineJS
-
-<!-- class:CjsExternalScriptCallback -->
-## `CjsExternalScriptCallback`
-
-Adapts one externally supplied callback object after boundary validation.
-
-- Source: `src/global/contracts/CjsScriptCallback.js`
-- Visibility: Internal
-- Kind: CarbonEngineJS
-
-<!-- class:CjsError -->
+<!-- class:CjsFrameLifecycle -->
+## `CjsFrameLifecycle`
+
+Dependency-free engine lifecycle required to execute one runtime frame.
+
+- Export: `@carbonenginejs/runtime/contracts`
+- Source: `src/global/contracts/CjsFrameLifecycle.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsInstancedMeshManager -->
+## `CjsInstancedMeshManager`
+
+Dependency-free contract through which Trinity registers CPU instancing data with an engine-owned realization and receives opaque handles that Trinity never inspects or mutates.
+
+- Export: `@carbonenginejs/runtime/contracts`
+- Source: `src/global/contracts/CjsInstancedMeshManager.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:ITr2BoundingBox -->
+## `ITr2BoundingBox`
+
+Dependency-free abstract contract for objects that publish ready world-space axis-aligned bounds, with a mixin for providers that already inherit a model base.
+
+- Export: `@carbonenginejs/runtime/contracts`
+- Source: `src/global/contracts/ITr2BoundingBox.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:ITr2RenderNode -->
+## `ITr2RenderNode`
+
+Dependency-free contract for one node in a Trinity render graph.
+
+- Export: `@carbonenginejs/runtime/contracts`
+- Source: `src/global/contracts/ITr2RenderNode.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsScriptCallback -->
+## `CjsScriptCallback`
+
+A stored script callback that can be invoked later.
+
+- Export: `@carbonenginejs/runtime/blue`
+- Source: `src/global/blue/CjsScriptCallback.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:CjsError -->
 ## `CjsError`
 
 Represents one structured operational failure with a stable CarbonEngineJS code.
@@ -109,7 +91,7 @@ Represents one structured operational failure with a stable CarbonEngineJS code.
 Represents one cancelled operation using Web-compatible abort identity.
 
 - Export: `@carbonenginejs/runtime/utils/errors`
-- Source: `src/global/utils/errors/CjsError.js`
+- Source: `src/global/utils/errors/CjsCancellationError.js`
 - Visibility: Public
 - Kind: CarbonEngineJS
 

package/docs/global/reference/classes/dropped.md

@@ -0,0 +1,16 @@
+# Dropped class catalog
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime` global classes under `src/global/dropped`
+Audience: Users, maintainers, and automated readers  
+Summary: Provides one-sentence purpose descriptors for donor classes that are written but deliberately not live, each carrying the reason it was dropped.
+
+<!-- class:BlueScriptCallbackStatus -->
+## `BlueScriptCallbackStatus`
+
+Retained-only reference shape mirroring Carbon's script-callback result, which carries OK/CALL_ERROR/EXCEPTION and the captured Python exception so a C++ caller can mute or report it; dropped because JavaScript shares one exception mechanism across that boundary and a throwing callback propagates by itself.
+
+- Export: None
+- Source: `src/global/dropped/BlueScriptCallbackStatus.js`
+- Visibility: Internal
+- Kind: Faithful Carbon port

package/docs/resource/README.md

@@ -1,7 +1,7 @@
 # Package documentation
 
 Status: Evolving  
-Scope: `@carbonenginejs/runtime/resource`
+Scope: `@carbonenginejs/runtime/resource`
 Audience: Users and integrators  
 Summary: Documentation home for the GPU-free resource lifecycle, cache, format, and object-loading package.
 
@@ -21,8 +21,8 @@ compiled Carbon container directly.
   selection, `Ready()`/`GetObject()`) without choosing a GPU backend;
 - you need one of the non-shader format readers as a tree-shakeable subpath
   (`@carbonenginejs/runtime/resource/formats/<name>`);
-- you need canonical effect permutation selection or model-backed shader
-  reflection records from `@carbonenginejs/runtime/resource/shader`;
+- you need canonical effect permutation selection or model-backed shader
+  reflection records from `@carbonenginejs/runtime/resource/shader`;
 - you need canonical raw audio resources for complete files or byte windows
   over shared physical sources;
 - you are writing an engine adapter that consumes published CPU payloads and
@@ -30,23 +30,23 @@ compiled Carbon container directly.
 
 ## Where it fits
 
-- Foundations consumed: the combined runtime's event emitter, model contracts,
-  neutral helpers, constants, and math values.
-- Normal consumers: the `core` layer (configures and exposes a `CjsResMan`),
-  the `trinity` and `sof` layers (request GPU-free objects), and engine
-  layers (WebGPU and future WebGL engines) that realize prepared
+- Foundations consumed: the combined runtime's event emitter, model contracts,
+  neutral helpers, constants, and math values.
+- Normal consumers: the `core` layer (configures and exposes a `CjsResMan`),
+  the `trinity` and `sof` layers (request GPU-free objects), and engine
+  layers (WebGPU and future WebGL engines) that realize prepared
   resources.
 - Owned responsibility: resource identity, cache, CPU payload lifecycle,
   format selection and conversion, load/publication queues, and canonical
   device-free effect/shader reflection hydration and selection.
-- Owned elsewhere: WebGL/WebGPU realization, device budgets, and device-loss
-  recovery belong to engine layers. Concrete readers remain opt-in resource
-  format subpaths.
+- Owned elsewhere: WebGL/WebGPU realization, device budgets, and device-loss
+  recovery belong to engine layers. Concrete readers remain opt-in resource
+  format subpaths.
 
-## Start here
-
-The [documentation map](#documentation-map) below routes architecture,
-lifecycle, shader, format and container work.
+## Start here
+
+The [documentation map](#documentation-map) below routes architecture,
+lifecycle, shader, format and container work.
 
 ## Documentation map
 
@@ -57,6 +57,10 @@ lifecycle, shader, format and container work.
 - [concepts/shader-resource-model.md](concepts/shader-resource-model.md): how
   `Tr2EffectRes`, `Tr2Shader` and `Tr2Effect` relate, verified against Carbon —
   one file, many permutations, many effects sharing them.
+- [concepts/shared-format-helpers.md](concepts/shared-format-helpers.md): the
+  helper modules shared across concrete formats, and the one case where
+  apparent duplication is deliberate — read before collapsing a repeated
+  format helper.
 - [concepts/writing-an-engine-adapter.md](concepts/writing-an-engine-adapter.md):
   the coupling rules and the reflection/topology seam for engine packages —
   read before writing a second engine.

package/docs/resource/architecture.md

@@ -111,8 +111,15 @@ dynamic identification run after any worker decode on the main thread.
 
 ## Source layout
 
-Authoring source is decorated JavaScript; published output is built ESM in
-`npm/dist`. Resource owners and their direct Carbon data records live under
+Resource source is directly importable ESM without decorator syntax. Classes
+that need schema metadata install it through `CjsSchema.define`; removing the
+syntax does not remove their identity, fields or model behavior. Source-focused
+resource tests import `src/resource` directly and need no rebuild;
+published-artifact checks still use `npm/dist`.
+This does not change other layers' decorator/build requirements. Published
+output remains built ESM in `npm/dist`.
+
+Resource owners and their direct Carbon data records live under
 `src/resource`, grouped as `audio`, `geometry`, `geometry/granny`, `shader`,
 and `texture`; worker execution and its message protocol live under `src/resource/worker`.
 Reviewed, unresolved active ports live under `src/resource/generated` and are exposed

package/docs/resource/concepts/format-capabilities.md

@@ -1,90 +1,90 @@
-# Format identification and capabilities
-
-Status: Stable
-Scope: `CjsFormat`, `CjsResourceProbe`, and every concrete format facade
-Audience: Format authors, runtime integrators, and diagnostics tooling
-Summary: Separates synchronous routing facts from advisory output support and exact asynchronous proof.
-
+# Format identification and capabilities
+
+Status: Stable
+Scope: `CjsFormat`, `CjsResourceProbe`, and every concrete format facade
+Audience: Format authors, runtime integrators, and diagnostics tooling
+Summary: Separates synchronous routing facts from advisory output support and exact asynchronous proof.
+
 ## One format contract
 
 Accepted and implemented 2026-08-22: every concrete format inherits the same
 canonical capability contract.
-
-Every concrete format extends the decorator-free `CjsFormat` base and declares:
-
-- `id`: stable format identity;
+
+Every concrete format extends the decorator-free `CjsFormat` base and declares:
+
+- `id`: stable format identity;
 - `mediaTypes`: canonical runtime media categories;
-- `extensions`: lowercase dotted file suffixes used for routing;
+- `extensions`: lowercase dotted file suffixes used for routing;
 - `outputs`: a map of exact output selectors and their capabilities;
-- `requestResponseType`: source acquisition response type; and
+- `requestResponseType`: source acquisition response type; and
 - `worker`: `null` or a browser-worker execution descriptor.
-
-An output descriptor records `output`, `payloadType`, `role`, `readMode`,
-`decoded`, `passthrough`, `default`, `probes`, and `requires`. It declares a
-reader path; it never claims that path has run for a particular input.
-
-The former parallel statics and result flags are retired. In particular,
-formats do not declare `type`, `inputTypes`, `outputTypes`,
-`debugOutputTypes`, or `implementationStatus`, and payloads do not use
-`containerOnly`, `isDecoded`, or codec-specific decode booleans. Consumers ask
-the format for the relevant output capability instead.
-
-## The four questions
-
-`Format.is(input, options)` is a synchronous routing predicate. It returns only
-a boolean and answers whether this format recognizes the input. It does not
-claim that a requested decoder output works.
-
-`Format.inspect(input, options)` is synchronous and returns structural
-metadata. It describes what the bytes contain without making runtime support
-or verification claims.
-
-`Format.getSupport(input, options)` is synchronous advice. It combines the
+
+An output descriptor records `output`, `payloadType`, `role`, `readMode`,
+`decoded`, `passthrough`, `default`, `probes`, and `requires`. It declares a
+reader path; it never claims that path has run for a particular input.
+
+The former parallel statics and result flags are retired. In particular,
+formats do not declare `type`, `inputTypes`, `outputTypes`,
+`debugOutputTypes`, or `implementationStatus`, and payloads do not use
+`containerOnly`, `isDecoded`, or codec-specific decode booleans. Consumers ask
+the format for the relevant output capability instead.
+
+## The four questions
+
+`Format.is(input, options)` is a synchronous routing predicate. It returns only
+a boolean and answers whether this format recognizes the input. It does not
+claim that a requested decoder output works.
+
+`Format.inspect(input, options)` is synchronous and returns structural
+metadata. It describes what the bytes contain without making runtime support
+or verification claims.
+
+`Format.getSupport(input, options)` is synchronous advice. It combines the
 format's structural probe with its declared output map and returns a plain
 report. `options.emit` selects one exact output; omitting it selects the
-declared default. Every returned capability has `verified: false` because no
-decode has been executed.
-
-`await Format.verifySupport(input, options)` is exact proof. It calls the real
-`readAsync(input, { ...options, emit })` path for the selected output. Success
-returns `supported: true` and `verified: true`. Failure returns
-`supported: false`, `verified: true`, and a structured error with name, code,
-message, details, and cause.
-
-Normal resource loading does not call `verifySupport()` and then decode again.
-A successful ordinary `readAsync()` is already proof for that load;
-`verifySupport()` exists for diagnostics, setup checks, and consumers that need
-to establish capability before committing to a route.
-
+declared default. Every returned capability has `verified: false` because no
+decode has been executed.
+
+`await Format.verifySupport(input, options)` is exact proof. It calls the real
+`readAsync(input, { ...options, emit })` path for the selected output. Success
+returns `supported: true` and `verified: true`. Failure returns
+`supported: false`, `verified: true`, and a structured error with name, code,
+message, details, and cause.
+
+Normal resource loading does not call `verifySupport()` and then decode again.
+A successful ordinary `readAsync()` is already proof for that load;
+`verifySupport()` exists for diagnostics, setup checks, and consumers that need
+to establish capability before committing to a route.
+
 For example, the `core` layer can prove that the actual DDS RGBA path works for a
-specific payload and environment:
-
-```js
-const report = await CjsDdsFormat.verifySupport(bytes, { emit: "rgba" });
-
-if (!report.supported)
-{
-  throw new Error(report.error.message);
-}
-```
-
+specific payload and environment:
+
+```js
+const report = await CjsDdsFormat.verifySupport(bytes, { emit: "rgba" });
+
+if (!report.supported)
+{
+  throw new Error(report.error.message);
+}
+```
+
 That result says nothing about DDS `texture`, `image`, or `raw`; support is
 always output-specific. An undeclared output fails without running a decoder;
 a declared output is verified only through its normal asynchronous read path.
-
-## Decorator boundary
-
-Format subpaths must remain importable from authored source, so they return
-plain report objects and never import decorated model code. A resource-layer
-consumer that needs persistence or model metadata calls
-`CjsResourceProbe.from(report)`. The model exposes `canUseSelected()` and
-`canUse(output)` without changing the format-layer contract.
-
-## Routing rule
-
-`CjsFormatStore` and `CjsResMan` use `Format.is()` only when content must break
-an extension tie. Support reports do not select routes: a truthy report object
-must never become an accidental match, and a decoder limitation must not make
+
+## Decorator boundary
+
+Format subpaths must remain importable from authored source, so they return
+plain report objects and never import decorated model code. A resource-layer
+consumer that needs persistence or model metadata calls
+`CjsResourceProbe.from(report)`. The model exposes `canUseSelected()` and
+`canUse(output)` without changing the format-layer contract.
+
+## Routing rule
+
+`CjsFormatStore` and `CjsResMan` use `Format.is()` only when content must break
+an extension tie. Support reports do not select routes: a truthy report object
+must never become an accidental match, and a decoder limitation must not make
 the system forget which format the bytes are.
 
 A single candidate may reject through its reader so the caller receives the
@@ -98,9 +98,53 @@ The ungated resource tests cover shared inheritance, the canonical output map
 and extension rules, boolean-only routing, advice that never fabricates
 verification, real-reader asynchronous success, output-specific decoder errors,
 and undeclared-output rejection without decoder execution.
-
-## Related documentation
-
-- [Format subpaths](../formats/README.md)
-- [Resource lifecycle](resource-lifecycle.md)
-- [Browser worker execution](../reference/workers.md)
+
+`test/resource/runtime-resource/format-conformance.test.js` additionally asserts
+the contract across **every** exported format rather than one at a time, because
+a format can only drift out of a shared shape in a way its own suite does not
+run. It checks the canonical identity, dotted lowercase frozen extensions,
+unique ids, one default output, resolvable selectors, a uniform report on
+unrecognized and empty input, and undeclared-output refusal.
+
+Two of its rules are pairings rather than floors:
+
+- **outputs if and only if a reader.** Most formats read. `CjsStaticFormat`
+  declares no outputs on purpose — `.static` is three unrelated containers
+  behind one extension, so that class identifies the family and the sibling
+  router calls whichever format reads it. An identification surface with no
+  reader correctly claims no output.
+- **inputs if and only if a writer.** This is the rule that found a real
+  defect: `CjsCmfFormat`, `CjsFbxFormat`, `CjsGr2Format` and `CjsStlFormat` all
+  wrote while `canWrite()` answered `false`, because none declared `inputs`.
+  Since the documented instruction is to ask rather than probe for the method,
+  the answer was wrong for four of the seven formats that write. They now
+  declare their real input payloads.
+
+## Probe overrides: what a format should NOT restate
+
+A concrete format overrides `probeSupport` only to express a condition its
+declaration cannot. When a probe returns no `variants`, `normalizeSupportReport`
+already reports every declared output as supported if the input was recognised —
+so an override that hand-builds that same answer is a second, drifting copy of
+the declaration.
+
+Seven such overrides were removed in `207e0a57`. They were found by snapshotting
+the normalized `getSupport` report for all 35 formats across 8 input kinds, 280
+reports in all, removing every candidate override, and diffing. Of 18 removed,
+7 changed nothing and were deleted; the other 11 changed a report and stayed.
+**The snapshot alone was not sufficient** — the test suite then caught three more
+(`bnk`, `ogg`, `wem`) whose conditions synthetic inputs could not reach. If you
+repeat this exercise, run both.
+
+Eleven conditional overrides remain, and they still hand-build a 14-key report.
+The open proposal is a per-output `supports(metadata)` predicate on
+`defineOutputs`, which would put the condition beside the output it constrains
+instead of in a parallel table matched back by string through
+`findLegacyVariant`. That is a contract change and is NOT yet decided.
+
+## Related documentation
+
+- [Shared format helpers](shared-format-helpers.md)
+- [Format subpaths](../formats/README.md)
+- [Resource lifecycle](resource-lifecycle.md)
+- [Browser worker execution](../reference/workers.md)

package/docs/resource/concepts/shared-format-helpers.md

@@ -0,0 +1,94 @@
+# Shared format helpers
+
+Status: Stable
+Scope: `src/resource/format/{imageSignatures,jsonPolicies,carbonRecordGuard}.js` and `src/global/utils/checksum.js`
+Audience: Format authors
+Summary: The helper modules shared across concrete formats, and the one case where apparent duplication is deliberate.
+
+## Why this page exists
+
+Three of these modules are files of exported functions rather than classes, so
+the class catalog in [reference/classes/core.md](../reference/classes/core.md)
+cannot list them and `lint:docs` cannot notice they are missing. They are easy
+to rediscover and easy to duplicate back into the formats they came from.
+
+## `format/imageSignatures.js`
+
+Container identification for the raster formats. Exports the four sniffers
+(`isPNG`, `isJPEG`, `isDDS`, `isTGA`), the dispatcher `identifyImageBytes`, and
+the shared record helpers `foreignImageRecord`, `imageMimeType`, `pngChannels`,
+`rawVariant` and `capitalizeFormatId`.
+
+Before this module, `png`, `jpeg`, `tga` and `dds` each carried ALL FOUR
+sniffers and ALL FOUR header inspectors, so each of eight functions existed four
+times. Every caller passes its own id as `expectedType` and a foreign detection
+always throws, so the only value that ever escaped a foreign inspector was the
+format NAME in an error message.
+
+Two behaviours come from the owning copy rather than the majority, and both are
+deliberate:
+
+- `isDDS` validates the 124-byte header size, not only the `DDS ` magic. `DDS `
+  followed by anything is not a DDS file, and accepting it sends the caller into
+  a header parse that cannot succeed.
+- `isTGA` accepts 15bpp.
+
+All four readers therefore now identify a 15bpp TGA and a malformed DDS the same
+way. `isTGA` is a heuristic over an 18-byte header — TGA has no magic number —
+so it must stay LAST in `identifyImageBytes`, after every format that can prove
+itself.
+
+## `format/jsonPolicies.js`
+
+Four named `toJSON` policies. **The obvious reading — that 27 formats carried 27
+copies of one helper — is wrong, and acting on it would be a regression.** They
+fall into four groups whose output is CONTRADICTORY by design:
+
+| Policy | Formats | `Uint8Array` becomes |
+|---|---|---|
+| `toJsonWithByteSummary` | 15 | `{ byteLength }` — the bytes are the file's bulk data |
+| `toJsonWithArrayValues` | 3 | expanded — for geometry the typed array IS the document |
+| `toJsonWithCollections` | 4 | expanded, plus `Map`/`Set` handling |
+| `toJsonAcyclic(value, label, seen)` | 3 | expanded, with a cycle guard that throws |
+
+One function with flags would have picked a winner and silently changed the
+rest. `fbx` and `cmf` keep their own; one caller each.
+
+`toJsonAcyclic` uses a PATH set, not a visited set: a repeated reference is a
+DAG and must serialise, while only a true cycle throws. Getting that backwards
+rejects ordinary shared sub-objects. It also fixes a defect inherited from the
+three readers it replaced, where a cycle reached through an ARRAY was not caught
+— the array branch returned before `seen` was consulted, so `list.push(list)`
+overflowed the stack instead of throwing. Fixed rather than reproduced: these
+policies are ours, and Carbon persists through Blue rather than JSON, so there
+is no donor behaviour to stay faithful to.
+
+## `format/carbonRecordGuard.js`
+
+`assertCarbonRecord(record, noun)` — the plain-object guard that opened
+`fromCarbonBinary` with identical text at 9 call sites across 8 reflection
+classes (`Tr2EffectStageInput` has two). The noun is the only part worth
+keeping, because it says WHICH record was malformed when a graph of them is
+being rebuilt.
+
+## `global/utils/checksum.js`
+
+`crc32(bytes, start, end)` and `adler32(bytes, start, end)`. CRC-32 existed
+three times (cmf, gr2, png) with the same reflected polynomial `0xEDB88320`,
+initial value and final xor; adler32 twice (png, fbx). Verified against
+published vectors including the adler32 modulo rollover above 5552 bytes.
+
+Two independent copies are NOT duplicates of these and must stay:
+
+- the Ogg page checksum in `wem` — different polynomial and direction, and its
+  comment says so;
+- the copy in `gr2/writer.test.mjs`, which is an oracle. A test that imports the
+  implementation it is checking proves nothing.
+
+## The rule these share
+
+A helper is shared when the call sites agree on what it should do. Where they
+disagree — the JSON policies — naming the disagreement is the work, and
+collapsing it is the bug. Not every duplicate resolves toward the shared
+version either: `toRecordFloat` reused a module scratch view while the shared
+`float32FromBits` allocated per call, and the fix was to improve the shared one.