@carbonenginejs/runtime-utils 0.1.1 → 0.1.3

package/docs/architecture.md

@@ -1,102 +1,102 @@
-# Runtime utilities architecture
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-utils`
-Audience: Runtime authors and maintainers
-Summary: Defines the package dependency boundary, ownership rules, and stability expectations.
-
-## Purpose
-
-`runtime-utils` supplies the lowest reusable layer for CarbonEngineJS runtime
-libraries. Consumers can use it without introducing a dependency on another
-organization package or pulling browser and Node tool behavior into the
-runtime graph.
-
-## Dependency contract
-
-Organization-dependency-free means:
-
-- published source must not import another `@carbonenginejs/*` package;
-- public subpaths must remain safe to import independently;
-- published source must not import Node built-ins or reference Node-only
-  globals;
-- module evaluation must not perform environment-specific work.
-
-It does not mean that all third-party dependencies are prohibited. A focused,
-browser-safe dependency such as `gl-matrix` is acceptable when it supplies a
-foundation primitive, preserves independent subpaths, and does not introduce
-organization dependency cycles.
-
-## Dependency direction
-
-```text
-      runtime-* packages       tools-browser (planned; unreleased)
-              \                    /
-               \                  /
-                v                v
-                   runtime-utils
-                         |
-                         v
-       third-party or Web-standard primitives
-```
-
-Dependencies point toward `runtime-utils`; `runtime-utils` never reaches back
-into a runtime, engine, format, browser tool, or Node tool package.
-
-## Admission rules
-
-Code belongs in `runtime-utils` only when all of these are true:
-
-1. More than one runtime-facing package needs the same primitive or contract.
-2. The behavior is useful without application, rendering, resource, or domain
-   policy.
-3. The implementation can satisfy the dependency contract above.
-4. Its public semantics are stable enough for broad reuse.
-5. Owning it here reduces duplicated foundation behavior rather than merely
-   shortening an import.
-
-With foundation consolidation complete, new responsibilities should be
-uncommon. Additions require a demonstrated cross-package need and a clear
-subpath owner.
-
-## Current ownership
-
-The implemented package currently owns:
-
-- neutral array, byte, text, JSON, lookup, and path mechanics;
-- structured operational errors without logging or transport policy;
-- shared `isSomething` predicates and small validation assertions;
-- browser-standard gzip decompression helpers;
-- scalar, vector, quaternion, matrix, geometry, mesh, tangent, noise, and curve
-  math;
-- shared media, graphics, render-context, audio, shader, D3D, and WebGPU
-  constants; and
-- Carbon type descriptors, schema metadata, models, lifecycle state,
-  documents, hydration, and dehydration.
-
-The [API reference](reference/api.md) is the exact current inventory.
-
-## Ownership elsewhere
-
+# Runtime utilities architecture
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-utils`
+Audience: Runtime authors and maintainers
+Summary: Defines the package dependency boundary, ownership rules, and stability expectations.
+
+## Purpose
+
+`runtime-utils` supplies the lowest reusable layer for CarbonEngineJS runtime
+libraries. Consumers can use it without introducing a dependency on another
+organization package or pulling browser and Node tool behavior into the
+runtime graph.
+
+## Dependency contract
+
+Organization-dependency-free means:
+
+- published source must not import another `@carbonenginejs/*` package;
+- public subpaths must remain safe to import independently;
+- published source must not import Node built-ins or reference Node-only
+  globals;
+- module evaluation must not perform environment-specific work.
+
+It does not mean that all third-party dependencies are prohibited. A focused,
+browser-safe dependency such as `gl-matrix` is acceptable when it supplies a
+foundation primitive, preserves independent subpaths, and does not introduce
+organization dependency cycles.
+
+## Dependency direction
+
+```text
+      runtime-* packages                tools-browser
+              \                    /
+               \                  /
+                v                v
+                   runtime-utils
+                         |
+                         v
+       third-party or Web-standard primitives
+```
+
+Dependencies point toward `runtime-utils`; `runtime-utils` never reaches back
+into a runtime, engine, format, browser tool, or Node tool package.
+
+## Admission rules
+
+Code belongs in `runtime-utils` only when all of these are true:
+
+1. More than one runtime-facing package needs the same primitive or contract.
+2. The behavior is useful without application, rendering, resource, or domain
+   policy.
+3. The implementation can satisfy the dependency contract above.
+4. Its public semantics are stable enough for broad reuse.
+5. Owning it here reduces duplicated foundation behavior rather than merely
+   shortening an import.
+
+With foundation consolidation complete, new responsibilities should be
+uncommon. Additions require a demonstrated cross-package need and a clear
+subpath owner.
+
+## Current ownership
+
+The implemented package currently owns:
+
+- neutral array, byte, text, JSON, lookup, and path mechanics;
+- structured operational errors without logging or transport policy;
+- shared `isSomething` predicates and small validation assertions;
+- browser-standard gzip decompression helpers;
+- scalar, vector, quaternion, matrix, geometry, mesh, tangent, noise, and curve
+  math;
+- shared media, graphics, render-context, audio, shader, D3D, and WebGPU
+  constants; and
+- Carbon type descriptors, schema metadata, models, lifecycle state,
+  documents, hydration, and dehydration.
+
+The [API reference](reference/api.md) is the exact current inventory.
+
+## Ownership elsewhere
+
 - Browser-facing demos, clients, remote readers, inspectors, integration
-  helpers, and usable reference implementations have the planned owner
-  `@carbonenginejs/tools-browser`, which is not currently released.
-- Node filesystems, caches, credentials, servers, command-line interfaces, and
-  build orchestration belong in `@carbonenginejs/tools-core`.
-- Runtime graph objects and domain readers belong in their owning
-  `runtime-*` package.
-- Backend objects and realization policy belong in `engine-*` packages.
-- Generated schemas, enums, and domain libraries remain generated artifacts
-  owned by their producer and consuming domain.
-
-## Consolidated foundation boundary
-
-The former math, constant, and Carbon type-system foundations now live under
-coherent `runtime-utils` subpaths. Former math and constant family suffixes
-remain available at the top level for mechanical migration, while `/math/*`
-and `/const/*` aliases group the same implementations.
-
-The root intentionally excludes type/model/document barrels so importing a
-neutral utility does not initialize registry and model families. See
-[Foundation consolidation](concepts/foundation-consolidation.md) for the
-layout and migration status.
+  helpers, and usable reference implementations belong in
+  `@carbonenginejs/tools-browser`.
+- Node filesystems, caches, credentials, servers, command-line interfaces, and
+  build orchestration belong in `@carbonenginejs/tools-core`.
+- Runtime graph objects and domain readers belong in their owning
+  `runtime-*` package.
+- Backend objects and realization policy belong in `engine-*` packages.
+- Generated schemas, enums, and domain libraries remain generated artifacts
+  owned by their producer and consuming domain.
+
+## Consolidated foundation boundary
+
+The former math, constant, and Carbon type-system foundations now live under
+coherent `runtime-utils` subpaths. Former math and constant family suffixes
+remain available at the top level for mechanical migration, while `/math/*`
+and `/const/*` aliases group the same implementations.
+
+The root intentionally excludes type/model/document barrels so importing a
+neutral utility does not initialize registry and model families. See
+[Foundation consolidation](concepts/foundation-consolidation.md) for the
+layout and migration status.

package/docs/concepts/foundation-consolidation.md

@@ -1,85 +1,85 @@
-# Runtime foundation consolidation
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-utils` foundation boundary
-Audience: Runtime authors, integrators, and maintainers
-Summary: Records the consolidated math, constant, and type-system ownership and migration contract.
-
-## Purpose
-
-`runtime-utils` is the single stable, browser-safe foundation commonly
-consumed by CarbonEngineJS runtime libraries.
-
-The surviving repository now contains the former utility, math, constant, and
-Carbon type-system implementations. Their inherited test suites run together,
-and every advertised package subpath is independently importable.
-
-## Current ownership
-
-`@carbonenginejs/runtime-utils` is the sole current source owner for neutral
-mechanics, math, shared constants, Carbon types, schema metadata, registries,
-models, documents, lifecycle, hydration, and dehydration.
-
-## Implemented layout
-
-The moved families map directly enough to preserve useful imports:
-
-| Moved family | `runtime-utils` family |
-| --- | --- |
-| Math | Existing top-level suffixes such as `./vec3`, plus `./math` and matching `./math/*` aliases |
-| Constants | Existing family suffixes such as `./graphics`, plus `./const` and matching `./const/*` aliases |
-| Carbon types/models | `./types`, `./schema`, `./model`, `./document`, `./hydration`, and `./lifecycle` |
-
-The root export may expose common mechanics and family namespaces. It must not
-introduce ambiguous duplicate names or require eager evaluation of every math,
-constant, schema, model, and document module.
-
-The package depends on `gl-matrix`. That is compatible with the boundary
-because `runtime-utils` prohibits organization dependencies, not focused
-browser-safe third-party foundations.
-
-## Shared predicates
-
-There is one curated `runtime-utils/is` surface:
-
-- predicates return literal booleans;
-- generally useful structural checks belong here;
-- vector and matrix checks join only with explicit math semantics;
-- domain checks remain with their domain package;
-- browser-specific checks remain outside this package; their planned,
-  unreleased owner is `tools-browser`;
-- established core predicate behavior wins wherever old names overlap.
-
-The goal is a useful shared predicate library, not a reduced compatibility
-snapshot.
-
-## Migration map
-
-| Former import | Current import |
-| --- | --- |
-| `@carbonenginejs/core-math` | `@carbonenginejs/runtime-utils/math` |
-| `@carbonenginejs/core-math/<subpath>` | `@carbonenginejs/runtime-utils/<subpath>` |
-| `@carbonenginejs/runtime-const` | `@carbonenginejs/runtime-utils/const` |
-| `@carbonenginejs/runtime-const/<subpath>` | `@carbonenginejs/runtime-utils/<subpath>` |
-| `@carbonenginejs/core-types/<subpath>` | The matching `@carbonenginejs/runtime-utils/<subpath>` |
-| `@carbonenginejs/core-types` | The direct runtime-utils type/model/document subpaths used by the consumer |
-
-The former package names are predecessor identities, not compatibility
-packages; maintained source lives here. The one deliberate API correction is
-scalar Hermite interpolation:
-use `cubicHermite` or `cubicHermiteDerivative` with argument order
-`(startValue, startTangent, endValue, endTangent, amount)`.
-
-## Stability target
-
-After consolidation, `runtime-utils` should change infrequently. New
-responsibilities need a demonstrated cross-runtime use case, browser-safe
-semantics, no CarbonEngineJS dependencies, and a coherent public subpath.
-
-The result is a runtime foundation, not a general utility dumping ground.
-
-## Related documentation
-
-- [Package documentation](../README.md)
-- [Architecture and admission rules](../architecture.md)
-- [Current API reference](../reference/api.md)
+# Runtime foundation consolidation
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-utils` foundation boundary
+Audience: Runtime authors, integrators, and maintainers
+Summary: Records the consolidated math, constant, and type-system ownership and migration contract.
+
+## Purpose
+
+`runtime-utils` is the single stable, browser-safe foundation commonly
+consumed by CarbonEngineJS runtime libraries.
+
+The surviving repository now contains the former utility, math, constant, and
+Carbon type-system implementations. Their inherited test suites run together,
+and every advertised package subpath is independently importable.
+
+## Current ownership
+
+`@carbonenginejs/runtime-utils` is the sole current source owner for neutral
+mechanics, math, shared constants, Carbon types, schema metadata, registries,
+models, documents, lifecycle, hydration, and dehydration.
+
+## Implemented layout
+
+The moved families map directly enough to preserve useful imports:
+
+| Moved family | `runtime-utils` family |
+| --- | --- |
+| Math | Existing top-level suffixes such as `./vec3`, plus `./math` and matching `./math/*` aliases |
+| Constants | Existing family suffixes such as `./graphics`, plus `./const` and matching `./const/*` aliases |
+| Carbon types/models | `./types`, `./schema`, `./model`, `./document`, `./hydration`, and `./lifecycle` |
+
+The root export may expose common mechanics and family namespaces. It must not
+introduce ambiguous duplicate names or require eager evaluation of every math,
+constant, schema, model, and document module.
+
+The package depends on `gl-matrix`. That is compatible with the boundary
+because `runtime-utils` prohibits organization dependencies, not focused
+browser-safe third-party foundations.
+
+## Shared predicates
+
+There is one curated `runtime-utils/is` surface:
+
+- predicates return literal booleans;
+- generally useful structural checks belong here;
+- vector and matrix checks join only with explicit math semantics;
+- domain checks remain with their domain package;
+- browser-specific checks remain outside this package and belong in
+  `tools-browser`;
+- established core predicate behavior wins wherever old names overlap.
+
+The goal is a useful shared predicate library, not a reduced compatibility
+snapshot.
+
+## Migration map
+
+| Former import | Current import |
+| --- | --- |
+| `@carbonenginejs/core-math` | `@carbonenginejs/runtime-utils/math` |
+| `@carbonenginejs/core-math/<subpath>` | `@carbonenginejs/runtime-utils/<subpath>` |
+| `@carbonenginejs/runtime-const` | `@carbonenginejs/runtime-utils/const` |
+| `@carbonenginejs/runtime-const/<subpath>` | `@carbonenginejs/runtime-utils/<subpath>` |
+| `@carbonenginejs/core-types/<subpath>` | The matching `@carbonenginejs/runtime-utils/<subpath>` |
+| `@carbonenginejs/core-types` | The direct runtime-utils type/model/document subpaths used by the consumer |
+
+The former package names are predecessor identities, not compatibility
+packages; maintained source lives here. The one deliberate API correction is
+scalar Hermite interpolation:
+use `cubicHermite` or `cubicHermiteDerivative` with argument order
+`(startValue, startTangent, endValue, endTangent, amount)`.
+
+## Stability target
+
+After consolidation, `runtime-utils` should change infrequently. New
+responsibilities need a demonstrated cross-runtime use case, browser-safe
+semantics, no CarbonEngineJS dependencies, and a coherent public subpath.
+
+The result is a runtime foundation, not a general utility dumping ground.
+
+## Related documentation
+
+- [Package documentation](../README.md)
+- [Architecture and admission rules](../architecture.md)
+- [Current API reference](../reference/api.md)

package/docs/concepts/model-lifecycle.md

@@ -0,0 +1,111 @@
+# Model lifecycle
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-utils/model` and the optional lifecycle-state subpath
+Audience: Runtime authors implementing mutable schema-backed models
+Summary: Defines the current dirty-settlement, traversal, initialization, resource, and optional lifecycle-state contracts.
+
+## Runtime state
+
+Every `CjsModel` owns one non-enumerable `__state` value. Its ordinary
+`CjsModelState` contains:
+
+- `dirty`, the one generic “a settle is owed” marker;
+- `flags`, lazy invalidations cleared by the consumer that recomputes them;
+- `rebuild`, work requirements cleared by the work method that succeeds;
+- `updating`, the settle re-entrancy guard; and
+- `suppressEvents`, the counted construction/teardown event gate.
+
+The event emitter adds event storage only while listeners exist. Flags and
+rebuild requirements are deliberately separate from `dirty`: neither makes
+`IsDirty()` true, and a successful settle does not clear either set.
+
+## Cooperative dirty settlement
+
+`SetValues` marks the model dirty only when at least one field changes and
+`markDirty !== false`. Schema-declared flag and rebuild consequences add tokens
+to their respective sets; they do not independently mark the model dirty. Code
+that mutates fields directly must call `MarkDirty()` or explicitly call
+`UpdateValues()` to say “apply these changes.”
+
+`UpdateValues()` always runs at least one `OnModified()` pass. It clears
+`dirty` before each pass and repeats when the hook dirties the model again.
+The model must settle within 32 passes.
+
+- Returning `false` from `OnModified()` rejects the settle and retains
+  `dirty`.
+- Throwing or exceeding the pass limit also retains `dirty`.
+- A successful settle emits one final `modified` event with `{ source }`
+  unless events are suppressed.
+
+The pipeline cannot promise a changed-property list to `OnModified()` or to
+the ordinary settled event. Callers that need changed names use the
+`SetValues` return value. A direct `SetValues(..., { markDirty: false })` path
+may emit an immediate payload containing `properties`; that is not the normal
+settled-event shape.
+
+## Initialization
+
+`CjsModel.from()` constructs or imports the graph, resolves references, then
+initializes models created by the operation. Each initialization walk follows
+owned children in post-order:
+
+1. suppress events for the model;
+2. add every declared flag/rebuild consequence and mark it dirty;
+3. call an optional `Initialize()` with no arguments;
+4. settle anything still dirty with events suppressed; and
+5. release the event gate.
+
+Children therefore initialize before their owning parents. Shared or cyclic
+graphs use the operation's visited set and initialize each model once.
+
+The document hydration adapter has its own `construct`, `applyValues`, and
+`finalize` contract. Its exact `Initialize` argument policy is not normalized
+with `CjsModel.from()` and should not be assumed interchangeable.
+
+## Traversal and resources
+
+`Traverse(visitor, options)` follows only schema-declared model relationships
+and does not revisit cycles. It supports:
+
+- pre-order or post-order visits;
+- forward or reverse field/list order; and
+- all relationships or owned relationships only.
+
+Returning `false` from a pre-order visitor prunes that model's descendants.
+Post-order return values are ignored.
+
+`GetResources(out)` traverses the whole model graph, deduplicates resources,
+and replaces the supplied output array. It collects schema-declared resource
+fields and adds any iterable returned by `OnGetResources()`. A resource hook
+does not prune descendants.
+
+## Optional lifecycle state
+
+The `./lifecycle` subpath can install `CjsLifecycleState` into
+`__state.lifecycle`. Its current statuses are `alive`, `destroyPending`,
+`destroying`, and `destroyed`.
+
+Installing this state is optional. An object without it is ordinarily alive
+and unmanaged. Runtime-utils does not provide a generic lifecycle manager or
+automatic transitions between these statuses.
+
+## Not provided by this foundation
+
+The current model/lifecycle surface does not define:
+
+- a generic `Destroy` operation;
+- ownership-aware cloning or destruction;
+- generic `SetValue` or `GetValue` methods;
+- fetching;
+- pre-modification events;
+- property-level dirty state; or
+- persistent initialization-transition management.
+
+Domain packages may define those behaviors when they own the policy. They
+must not infer them from historical lifecycle proposals.
+
+## Related documentation
+
+- [Carbon type and model guide](../core-types/README.md)
+- [Current API reference](../reference/api.md)