@carbonenginejs/runtime-trinity 0.6.0 → 0.7.0

package/docs/architecture.md

@@ -0,0 +1,162 @@
+# Runtime Trinity architecture
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity`
+Audience: Runtime authors, engine authors, and maintainers
+Summary: Defines Trinity graph ownership and the boundary between portable state and backend realization.
+
+## Purpose
+
+`@carbonenginejs/runtime-trinity` preserves Carbon's serializable object graph and portable
+runtime behavior while keeping graphics-device work outside the package.
+Trinity classes can therefore be registered, hydrated, inspected, updated, and
+serialized in browsers, workers, Node.js tools, and test hosts.
+
+## Composition and data flow
+
+```text
+@carbonenginejs/tools-core -- reviewed source --> @carbonenginejs/runtime-trinity
+@carbonenginejs/runtime-trinity -- depends on --> runtime-utils + runtime-resource
+
+@carbonenginejs/runtime-resource -- decoded values --> application composition
+@carbonenginejs/runtime-trinity -- graph and intents --> application composition
+application composition --> host WebGL engine
+application composition --> @carbonenginejs/engine-webgpu
+```
+
+Runtime dependencies point from `@carbonenginejs/runtime-trinity` to
+`@carbonenginejs/runtime-utils` and `@carbonenginejs/runtime-resource`.
+Schema scanning and source emission flow from `@carbonenginejs/tools-core`
+during development, but generated source never imports that Node toolchain.
+
+## Owned responsibilities
+
+The current package owns:
+
+- Carbon-compatible class identity, schema fields, enums, and graph structure;
+- CPU-side curves, controllers, cameras, transforms, behaviors, and effects;
+- renderer-neutral render batches and ordered render-job intent;
+- per-object semantic values that can be established from graph state;
+- portable lifecycle, distribution, post-process graph, and scene behavior;
+- generated schema intake and the maintained implementations promoted from it.
+
+`TriDevice`, render contexts, targets, authored shader options, effect/material
+facades, parameters, buffers, and presentation records remain Trinity graph
+classes. Canonical `Tr2EffectRes`, `Tr2Shader`, and immutable reflection records
+are resource-owned. Serialized identity never makes either package the owner of
+live backend handles.
+
+## Ownership elsewhere
+
+- `@carbonenginejs/runtime-utils` owns shared models, schema decorators, math,
+  constants, and general runtime primitives.
+- `@carbonenginejs/runtime-resource` owns resource acquisition, decoding,
+  reusable CPU resource representations, compiled-effect selection/cache, and
+  the canonical device-free `Tr2Shader` reflection graph.
+- `@carbonenginejs/runtime-character` owns character GState behavior.
+- `@carbonenginejs/tools-core` owns source scanning, schema compilation, and
+  generated-class emission.
+- WebGL and WebGPU engines own devices, contexts, uploads, bindings, pipelines,
+  draw or dispatch encoding, presentation, synchronization, and loss recovery.
+- Applications or `@carbonenginejs/runtime-core` choose and compose engines and
+  domain runtimes.
+
+## Render-job contract
+
+`TriRenderJob` and `Tr2RenderJobs` preserve ordered step execution, resumable
+in-progress cursors, nested result mapping, recurring and chained scheduling,
+and deterministic target/depth stack cleanup.
+
+`Run(realTime, simTime, executor)` receives an injected executor. A WebGL
+executor may perform work immediately while a WebGPU executor may encode pass
+boundaries, but both preserve the observable step order and yield boundary.
+Nested jobs receive the same executor identity. `TriRenderJob` and
+`TriRenderStep` expose their status and result vocabularies as class statics.
+The default `Tr2RenderContext` is a GPU-free intent and diagnostic surface.
+
+## Render-batch contract
+
+`Tr2RenderBatch`, `TriRenderBatchAccumulator`, and `TriRenderBatchMap` collect,
+sort, group, and expose neutral CPU data. Geometry references, effect keys,
+per-object values, render modes, and draw arguments describe work; they are
+not live GPU resources.
+
+`CjsBatchManager` is the current GPU-free orchestrator. It registers producer
+types, invokes injected `Realize` and `Build` hooks, collects renderables,
+finalizes accumulators, and observes shared rebuild tokens. The backend
+realizers supplied through those hooks remain engine-owned.
+
+## Per-frame and per-object data
+
+Trinity can expose per-object values proven by graph state, including world
+transforms and maintained Eve per-object records. It does not invent missing
+renderer state.
+
+The active engine supplies complete per-frame values such as previous
+matrices, shadow state, resolution, jitter, presentation policy, and other
+backend-owned semantics before serialization or upload.
+
+### Constant-data ownership
+
+Trinity owns the constant-data layout outright: field names, element counts, an
+encoding kind per field, and the byte offsets. There is ONE layout and no
+per-engine packing, because these buffers are not backend-specific — every
+backend declares them as a flat array of `vec4`, and std140's stride for an
+array of `vec4` matches tight C++ packing. A struct the catalog does not cover
+fails at registration rather than at draw time. An engine that genuinely needs
+different memory transforms it downstream.
+
+`RawDataStore` leases payloads from a per-engine arena; `RawData` is the
+write-mostly view over one slice. Values are written through the encoding
+(matrices transposed, integers bit-cast), never read back, and the arena is
+rewound rather than freed per payload. Declared defaults are re-applied on
+lease; an unwritten field otherwise retains the previous tenant's bytes, which
+preserves the source engine's own contract that a fill writes every field it
+relies on.
+
+A renderable returns whichever shape its constant data actually has:
+
+- one payload, when a single buffer is bound;
+- a `{ vs, ps }` record, when the vertex and pixel stages take DIFFERENT
+  payloads and are therefore two separate buffers;
+- `null`, when the renderable cannot produce one — no geometry, or no
+  accumulator to lease from.
+
+The record itself belongs to one of Carbon's two tiers, chosen statically by
+class rather than by a runtime branch. A TRANSIENT record is leased from the
+frame arena and dies at reset. A PERSISTENT record is a member the owner keeps
+across frames, because it fills the record during update and reads it back
+afterwards; `EveSpaceObject2` is the reference case, and `Invalidate` marks it
+for re-upload once per frame.
+
+A struct declares the stages it binds to, so one payload bound to several
+stages stays one payload rather than being duplicated per stage. The batch
+pipeline threads whichever shape it receives without inspecting it.
+
+## Post-process graph
+
+`Tr2PostProcess2` and `Tr2PostProcessAttributes` own device-free activation,
+quality gates, lookup-table ordering, volume blending, and authored effect
+records. Engines independently realize temporary textures, exposure state,
+history, compute or fragment passes, readback, and loss recovery while
+preserving observable graph order.
+
+## Constraints
+
+- Package evaluation must not create a canvas, graphics context, audio
+  context, network request, or filesystem dependency.
+- Persisted schema fields must not hold live backend handles.
+- A generated class is generator-owned schema intake. It is promoted before
+  its first substantive manual source change, even when review leaves explicit
+  implementation gaps.
+- Backend-specific behavior must be injected through a narrow capability or
+  remain with the owning engine.
+
+## Related documentation
+
+- [Package documentation](README.md)
+- [Current API](reference/api.md)
+- [Main semantic extraction](reference/main-semantic-extraction.md)
+- [Eve runtime behavior](concepts/eve-runtime-behavior.md)
+- [Generated-class lifecycle](concepts/generated-class-lifecycle.md)
+- [Implementation status and audits](reference/implementation-status.md)

package/docs/concepts/eve-runtime-behavior.md

@@ -0,0 +1,86 @@
+# Eve runtime behavior
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity/eve`
+Audience: Runtime authors, engine authors, and integrators
+Summary: Describes maintained CPU behavior for Eve combat effects, morph state, and distributions.
+
+## Purpose
+
+The maintained Eve tree implements portable object-graph behavior without
+claiming renderer, resource-loader, or character-runtime ownership. These
+contracts let engines consume faithful CPU state through explicit seams.
+
+## Turrets and missiles
+
+`EveMobile` maps authored `locator_*` transforms and optional animated bone
+transforms into `EveTurretSet` instances. Turret sets own portable state
+changes, paired turret and damage-locator selection, looping-fire checks,
+tracking fades, muzzle transforms, target updates, firing effects, and
+controller forwarding.
+
+`EveSpaceObject2` supplies damage locators, miss positions, radius,
+impact-material data, and the shield-ellipsoid collision surface consumed by
+turrets and missiles.
+
+`EveTransform`, `EveMissile`, and `EveMissileWarhead` own CPU transforms,
+launch, eject, and tracking state, fixed-seed Perlin path offsets, target
+switching, impacts, explosion callbacks, particles, visibility, and dynamic
+MIRV bounds. Per-object records expose the world transform and missile size;
+an engine packs and uploads those logical values.
+
+`EveEffectRoot2` and `EveRootTransform` own detached effect placement,
+controller and curve propagation, targetable-sphere behavior, child update and
+renderable traversal, and authored effect level of detail.
+
+Native pose realization, geometry loading, quad submission, device buffers,
+and shader upload remain outside this package. A data-only generated child
+does not gain invented rendering behavior merely because a maintained root
+traverses it.
+
+## Animation and morph state
+
+Character GState ownership belongs to
+`@carbonenginejs/runtime-character`. `Tr2GStateAnimation` and
+`Tr2GStateParameter` are not Trinity exports.
+
+The generic `Tr2GrannyAnimation` graph remains in Trinity for non-character
+skinned geometry. Its updater samples legacy scalar vector tracks and modern
+morph channels, composes layers in native lexical order, exposes a detached
+morph snapshot, and applies `GrannyBoneOffset` corrections after animation
+sampling and before world-transform composition.
+
+`Tr2GrannyStateRes` remains owned by
+`@carbonenginejs/runtime-resource`.
+
+`Tr2Mesh` owns LOD-0 indexed morph-weight state, including manual weights and
+baked flags. `EveChildMesh` rebuilds its CPU morph records during asynchronous
+updates. Exact-name animation values override mesh weights; values below
+`0.001` remain inactive; active runtime and baked records are partitioned
+before an engine uploads or evaluates them.
+
+Trinity prepares morph records but does not perform GPU deformation or baking.
+
+## Distribution contract
+
+The Eve distribution family is browser-portable CPU behavior. Locator,
+parent-locator, and volume placement generators build the initial placement
+pool. Spawn and lifetime modifiers transform those records. Burst, interval,
+controller, sphere, plane, and snake spawners drive the shared
+`IEveDistributionRulesParent` contract.
+
+Carbon's mutable `uint32_t&` placement counter is represented by one explicit
+`{ value }` object.
+
+Sphere, ellipsoid, and box volumes expose point generation and change
+callbacks without creating renderer resources. Parent-locator generation uses
+`EveSpaceObject2.GetLocatorsForSet`; volume generation uses
+`IEveVolume.GeneratePointsInVolume`. These paths do not probe alternate method
+names or infer renderer capabilities.
+
+## Related documentation
+
+- [Architecture and ownership boundaries](../architecture.md)
+- [Current API](../reference/api.md)
+- [Main semantic extraction](../reference/main-semantic-extraction.md)
+- [Implementation status and audits](../reference/implementation-status.md)

package/docs/concepts/generated-class-lifecycle.md

@@ -0,0 +1,116 @@
+# Generated-class lifecycle
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity` generated and maintained classes
+Audience: Runtime authors, schema-tool authors, and maintainers
+Summary: Defines how schema intake becomes reviewed runtime-trinity source.
+
+## Purpose
+
+Generated classes establish Carbon-compatible identity, inheritance, fields,
+decorators, and exposed method obligations. They are review input rather than
+the permanent home of manually maintained runtime behavior.
+
+The lifecycle keeps generated output reproducible while giving every manually
+edited class a stable, human-readable source tree.
+
+## Current lifecycle
+
+1. `@carbonenginejs/tools-core` scans Carbon declarations and compiles the
+   reviewed schema.
+2. The class emitter produces schema-shaped JavaScript in its tooling-owned
+   output corpus.
+3. Reviewed generated source is copied into `runtime-trinity/src/generated`;
+   the runtime does not depend on the tooling workspace.
+4. Runtime work verifies portable behavior against the public source,
+   interfaces, schema, and tests.
+5. Before the first substantive manual source change, the complete class moves
+   into the maintained source area that owns its responsibility.
+6. Manual implementation and review continue in that maintained home.
+   Unresolved obligations remain explicit with `@impl.notImplemented`.
+7. The maintained barrel exports the promoted class and the generated copy is
+   removed.
+8. Generation records that a hand-maintained source exists instead of
+   recreating a competing class.
+
+Inspection, tests outside the class, and unchanged emitter output do not
+trigger promotion. Manual behavior, source-corrected defaults or fields,
+inheritance changes, decorator corrections, runtime-specific dependencies,
+and class-owned enum work do.
+
+The parity audit remains active after promotion because later schema or
+interface-contract improvements can reveal additional obligations. A promoted
+class with a newly visible gap stays in its maintained home; the gap is made
+explicit and completed there instead of recreating a generated duplicate.
+
+Examples of maintained homes include:
+
+- `src/eve/camera` for camera state;
+- `src/eve/attachment/decal` for space-object decals;
+- `src/eve/child/behaviors/lifecycle` and `tunnels` for cohesive behaviors;
+- `src/eve/effect/multiEffect` for multi-effect graphs; and
+- `src/trinityCore/binding` for dynamic and value binding classes.
+
+## Enum ownership
+
+An enum associated with one Carbon class normally becomes a named frozen
+static on that canonical owner, for example `Owner.EnumType.MEMBER`. A
+serialized integer field uses `@schema.enum("EnumType")` so inspectors and
+user interfaces resolve the class static and discover its accepted
+vocabulary.
+
+Ownerless vocabulary used only inside this package remains beside its
+maintained family. Genuinely shared cross-package vocabulary belongs in
+`@carbonenginejs/runtime-utils`, which allows runtime and graphics packages to
+share the identity without importing one another. A standalone generated enum
+file alone is not evidence that the enum should move to runtime-utils.
+
+## Generated source
+
+Generated source may include explicit `@impl.notImplemented` methods. These
+markers preserve known obligations and allow the implementation-gap audit to
+report them. Generated code must not silently invent device, resource,
+filesystem, or native behavior.
+
+Generated output is deterministic and should not be hand-edited as a
+substitute for changing its owning schema or emitter. Runtime-specific
+implementations belong in the maintained tree before the manual edit is made.
+
+Generation runs into a tooling-owned scratch corpus or another staging
+directory. Reviewed output is then copied only into generator-owned paths.
+The class emitter refuses to overwrite a differing `--out` file unless
+`--force` is supplied; `--force` must not target runtime source.
+
+The generated provenance banner is not an ownership lock. Durable protection
+comes from maintained and dropped skip sets, staging-first generation,
+duplicate-class checks, and comparison of installed generated source with
+fresh output. Newly promoted files replace the generated banner with a
+hand-maintained provenance header and exact Carbon source paths.
+
+## Dropped quarantine
+
+`src/dropped` is separate from `src/generated`. It contains deliberately
+quarantined source with a file-specific disposition and is excluded from the
+normal implementation and parity ownership surface.
+
+A dropped class is not treated as an incomplete generated class and is not a
+supported public implementation. Its disposition records why this package
+owns the identity, why it is rejected as a runtime model, its replacement, and
+the condition for revival. Dropped files are not imported, exported,
+registered, or implemented in place.
+
+## Planned class descriptors
+
+The schema emitter is planned to carry a reviewed purpose, visibility, kind,
+source path, and public export for each generated class. That metadata will
+produce deterministic class-purpose catalogs without guessing responsibility
+from a class name.
+
+The catalog becomes part of the documentation validation gate after the
+shared checker can exclude the deliberate dropped quarantine.
+
+## Related documentation
+
+- [Architecture and ownership boundaries](../architecture.md)
+- [Current API](../reference/api.md)
+- [Implementation status and audits](../reference/implementation-status.md)

package/docs/reference/api.md

@@ -0,0 +1,76 @@
+# Runtime Trinity API
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity`
+Audience: Runtime authors, engine authors, and integrators
+Summary: Lists the current public subpaths and their owned source families.
+
+## Contract
+
+All public entries are ECMAScript modules. Importing them creates no graphics
+device or backend context. The root entry aggregates the complete runtime;
+focused subpaths allow consumers to state a narrower dependency.
+
+The root entry also contains the maintained `sprite2d` family. There is no
+focused `./sprite2d` package export in the current manifest.
+
+## Current subpaths
+
+| Import | Purpose |
+| --- | --- |
+| `@carbonenginejs/runtime-trinity` | Complete public Trinity and Eve runtime surface. |
+| `@carbonenginejs/runtime-trinity/controllers` | Controller actions, variables, state machines, and expression behavior. |
+| `@carbonenginejs/runtime-trinity/curves` | Scalar, vector, quaternion, event, sequencer, and animation curve families. |
+| `@carbonenginejs/runtime-trinity/eve` | Maintained Eve cameras, scenes, objects, attachments, effects, behaviors, and UI graph classes. |
+| `@carbonenginejs/runtime-trinity/generated` | Aggregate generated schema-intake classes that have not been promoted. |
+| `@carbonenginejs/runtime-trinity/generated/*` | Generated family barrel selected by package export pattern. |
+| `@carbonenginejs/runtime-trinity/generated/*.js` | Exact generated module selected by package export pattern. |
+| `@carbonenginejs/runtime-trinity/particle` | Maintained CPU particle data, emitters, forces, constraints, and systems. |
+| `@carbonenginejs/runtime-trinity/postProcess` | Device-free post-process graph and attribute models. |
+| `@carbonenginejs/runtime-trinity/renderJob` | Ordered render-job and render-step graph classes. |
+| `@carbonenginejs/runtime-trinity/shader` | Mutable effect/material facade, parameters, options, sampler overrides, shader buffers, and identity-preserving compatibility reexports of resource-owned reflection classes. |
+| `@carbonenginejs/runtime-trinity/trinityCore` | Core Trinity resources, batches, views, projections, bindings, and graph records. |
+| `@carbonenginejs/runtime-trinity/ui` | Maintained Trinity UI graph classes. |
+| `@carbonenginejs/runtime-trinity/utilities` | Package-specific portable runtime helpers. |
+
+Promoted classes are exported through their maintained family and no longer
+remain under `generated`. For example:
+
+```js
+import { EveCamera } from "@carbonenginejs/runtime-trinity/eve";
+import {
+    Tr2DynamicBinding,
+    TriValueBinding
+} from "@carbonenginejs/runtime-trinity/trinityCore";
+```
+
+## Schema and enum metadata
+
+Runtime classes use `@type.define` for Carbon class identity and field
+decorators from `@carbonenginejs/runtime-utils/schema`. Enum-backed integer
+fields use `@schema.enum` so metadata consumers can present the maintained enum
+vocabulary. Class-associated enums normally live as named frozen statics on
+their canonical class. Ownerless single-package vocabulary remains with its
+family; only genuinely shared cross-package vocabulary belongs in
+`@carbonenginejs/runtime-utils`.
+
+Public methods that implement Carbon exposure use `@carbon.method`. The parity
+audit checks promoted classes for omitted and present-but-unexposed methods.
+
+## Constraints
+
+- Generated wildcard subpaths are intake surfaces and can change when a class
+  is promoted to its maintained family.
+- A graph class describing a device or buffer does not expose a live backend
+  object.
+- Resource and engine capabilities are supplied by their owning packages.
+- Explicit implementation gaps remain visible rather than receiving guessed
+  behavior.
+
+## Related documentation
+
+- [Architecture and ownership boundaries](../architecture.md)
+- [Main semantic extraction](main-semantic-extraction.md)
+- [Eve runtime behavior](../concepts/eve-runtime-behavior.md)
+- [Generated-class lifecycle](../concepts/generated-class-lifecycle.md)
+- [Implementation status and audits](implementation-status.md)

package/docs/reference/classes/eve-runtime.md

@@ -0,0 +1,106 @@
+# Eve runtime classes
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity/eve`
+Audience: Users and integrators
+Summary: Catalogs promoted Eve runtime classes with renderer-neutral behavior.
+
+<!-- class:EvePlanet -->
+## `EvePlanet`
+
+Represents a planet scene object with CPU-side visibility state for its depth-only child mesh.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/spaceObject/planet/EvePlanet.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveLensflare -->
+## `EveLensflare`
+
+Represents a lens-flare graph with CPU-side visibility and controller state.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/effect/lensflare/EveLensflare.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveLineSet -->
+## `EveLineSet`
+
+Stores editable tactical line records before renderer submission.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/ui/lines/EveLineSet.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveTacticalTrails -->
+## `EveTacticalTrails`
+
+Tracks tactical trail objects without requiring a graphics device.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/ui/tacticalOverlay/EveTacticalTrails.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveComponentCollection -->
+## `EveComponentCollection`
+
+Stores entities belonging to one Eve component type.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/scene/components/EveComponentCollection.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveComponentRegistry -->
+## `EveComponentRegistry`
+
+Indexes Eve entities and their component collections for scene processing.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/scene/components/EveComponentRegistry.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveShip2 -->
+## `EveShip2`
+
+A ship space object: booster drive, speed state, and ship shader data.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/spaceObject/EveShip2.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveSpherePin -->
+## `EveSpherePin`
+
+A UI sphere pin: authored SRT placement plus the pin constant record.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/ui/EveSpherePin.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:EveChildBulletStorm -->
+## `EveChildBulletStorm`
+
+Locator-driven bullet-storm child: instances, target blobs, and the clip-sphere state machine.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/child/EveChildBulletStorm.js`
+- Visibility: Public
+- Kind: CarbonEngine
+
+<!-- class:IEveSpaceObject2ParentData -->
+## `IEveSpaceObject2ParentData`
+
+The per-frame parent state a space object hands to its attachments.
+
+- Export: `@carbonenginejs/runtime-trinity/eve`
+- Source: `src/eve/spaceObject/IEveSpaceObject2ParentData.js`
+- Visibility: Public
+- Kind: CarbonEngine

package/docs/reference/classes/trinity-core.md

@@ -0,0 +1,26 @@
+# Trinity core classes
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity/trinityCore`
+Audience: Engine authors and integrators
+Summary: Catalogs the GPU-free constant-data classes an engine binds when it realizes the Trinity graph.
+
+<!-- class:RawData -->
+## `RawData`
+
+A packed constant-data slice bound to a resolved layout.
+
+- Export: `@carbonenginejs/runtime-trinity/trinityCore`
+- Source: `src/trinityCore/rawData/RawData.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:RawDataStore -->
+## `RawDataStore`
+
+Registers constant-data struct shapes and leases packed payloads from a per-engine arena.
+
+- Export: `@carbonenginejs/runtime-trinity/trinityCore`
+- Source: `src/trinityCore/rawData/RawDataStore.js`
+- Visibility: Public
+- Kind: CarbonEngineJS

package/docs/reference/implementation-status.md

@@ -0,0 +1,104 @@
+# Runtime Trinity implementation status
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-trinity`
+Audience: Runtime authors, engine authors, and maintainers
+Summary: Defines the implementation audits and records current user-visible graph limitations.
+
+## Purpose
+
+Two complementary audits keep incomplete behavior explicit. Their command
+output is authoritative for the checked source state; this page explains how
+to interpret that output and records the current package-level limitation.
+
+## Explicit implementation gaps
+
+Run:
+
+```sh
+npm run audit:gaps
+```
+
+The gap audit inventories `@impl.notImplemented` methods and `@type.unknown`
+properties in generated and maintained source. It excludes the deliberate
+`src/dropped` quarantine by default.
+
+The current source contains:
+
+- 154 explicit methods across 50 classes; and
+- no unknown properties.
+
+The remaining methods are concentrated in native, GPU, font, bitmap/atlas,
+particle, scene-picking, smart-light, and related backend-facing families.
+Markers are intentional: the runtime does not fabricate behavior before a
+portable contract or engine seam is established.
+
+## Promoted-class parity
+
+Run the parity audit against a compiled Carbon schema supplied by the caller:
+
+```sh
+npm run audit:parity -- --schema-root path/to/schema-build
+```
+
+The `CARBON_SCHEMA_ROOT` environment variable may provide the same location.
+The audit resolves JavaScript inheritance, checks `@carbon.method` exposure,
+and excludes deliberately quarantined classes.
+
+The current audit checks 344 promoted classes and excludes 19 quarantined
+classes. Ten classes have 26 omitted methods:
+
+| Contract | Classes | Omitted surface |
+| --- | --- | --- |
+| Pickable (16 omissions) | `EveMissile`, `EveMissileWarhead`, `EveMobile`, `EveRootTransform`, `EveSpaceObject2`, `EveSpaceObjectDecal`, `EveTransform`, `EveUiObject` | `GetPickingBatches` and `GetID` on each class. |
+| Renderable (10 omissions) | `EveSpaceObjectDecal`, `EveStretch2`, `EveTurretSet` | Batch, transparency, sort-value, and per-object-data methods as applicable to each class. |
+
+`EveSpaceObjectDecal` participates in both groups. The audit reports:
+
+- no present-but-unexposed Carbon methods;
+- no missing JavaScript classes;
+- no missing or ambiguous schemas; and
+- no unresolved non-`CjsModel` base classes.
+
+## Current runtime limits
+
+- Device creation, GPU resources, draw submission, presentation, and
+  device-loss recovery require an engine package.
+- Per-frame scene semantics remain engine-supplied because the Trinity graph
+  does not own complete frame, history, jitter, shadow, and presentation
+  state.
+- Per-object constant data is complete on the CPU side: every catalogued struct
+  with a Carbon producer in this package is filled. The exceptions are values
+  that are literally GPU addresses - bone-ring and morph-ring offsets - which
+  keep their defaults until an engine supplies them, and `Tr2PerObjectVSData`,
+  whose only Carbon filler is an interior placeable that is not a
+  runtime-trinity class.
+- Generated classes may expose explicit obligations, but manual behavior
+  belongs in maintained source from the first substantive edit. Some legacy
+  generated files already contain portable implementations and are being
+  promoted without waiting for every native or backend gap to close.
+- The child reference and socket resource seam is synchronous and injected.
+- Socket parameter auto-creation currently covers the emitted string
+  parameter type; additional types require corresponding schema emission.
+- Calculated whole-object bounds remain planned as a separate lazy cache and
+  are not inferred through generic graph traversal.
+
+## Planned completion gates
+
+Promotion occurs before the first substantive manual source change. Portable
+behavior, decorators, exports, enum ownership, and focused tests are then
+reviewed in the maintained home. When later schema improvements reveal an
+inherited or interface obligation, the maintained class remains promoted and
+the parity audit keeps that new gap explicit. Backend-only methods remain
+explicit until an owning engine exposes a proven capability.
+
+The public class-purpose catalog is populated as classes receive reviewed
+descriptors during promotion. Completing the remaining catalog still requires
+descriptor metadata and documentation validation that excludes the dropped
+quarantine.
+
+## Related documentation
+
+- [Architecture and ownership boundaries](../architecture.md)
+- [Generated-class lifecycle](../concepts/generated-class-lifecycle.md)
+- [Current API](api.md)