@driftengine/chemistry 3.61.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Drift Technologies
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+DriftEngine
+Copyright 2026 Drift Technologies
+
+This product includes software developed at Drift Technologies
+(https://github.com/drftrun/driftengine).
+
+Licensed under the Apache License, Version 2.0. Section 4(d) of that licence
+requires this NOTICE to be reproduced in any derivative work you distribute,
+in the source, the documentation, or a display generated by the work.

package/README.md

@@ -0,0 +1,194 @@
+# @driftengine/chemistry
+
+Thermochemistry of bulk matter: what a material is made of, what temperature it is, and what it
+turns into. **18.0 KB gzipped**, standalone — it imports no other engine package, so a consumer who
+wants matter and no renderer pays for matter and no renderer.
+
+**This is the whole of Track P, CH-0 through CH-10.**
+
+## What ships today
+
+|                                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Fifteen elements**                 | `C H O N S Cl Si Ca Fe Al Mg Cu Na K P`, with IUPAC conventional atomic weights. A closed set, so every matrix has a fixed width and a totals vector is fifteen doubles                                                                                                                                                                                                                                                                                                                                                                    |
+| **Sixty-eight species**              | Atmospheric and combustion gases, condensed water, three forms of carbon, the wood polymers, the biopolymers, sugars, lipids, fuel surrogates, polymers, minerals and metals. Ten more arrive with the families that need them — wood tar as vapour and as droplets, molten fat, five fuel vapours — rather than being carried by everyone                                                                                                                                                                                                 |
+| **Molar mass, derived**              | A species carries a _formula_; its mass is that formula against the atomic weights. There is no molar-mass field to disagree with it                                                                                                                                                                                                                                                                                                                                                                                                       |
+| **The species-by-element matrix**    | Moles of each element per mole of each species, dense, `Float64Array`, with a scaled-row reduction that allocates nothing                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **`Composition`**                    | Mass fractions that must sum to one, stored sorted by species index so two spellings of the same material reduce bit-identically                                                                                                                                                                                                                                                                                                                                                                                                           |
+| **`elementTotals`**                  | Kilograms of species to moles of elements, into a caller-owned vector, allocating nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **Enthalpy is the state**            | A parcel holds joules and mass; its temperature is **derived from what it is made of right now**. `h = A·ΔT + B·ΔT²/2` inverts in closed form with one square root — no table, no search, and composition-aware by construction                                                                                                                                                                                                                                                                                                            |
+| **A phase change is a reaction**     | Melting and boiling are gated reactions whose enthalpy Hess's law already supplies, and **the plateau emerges from the solver** rather than from a curve. Nothing branches on melting and nothing has to                                                                                                                                                                                                                                                                                                                                   |
+| **`boilingPoint`**                   | Clausius-Clapeyron, so a stew at 3,000 m is pinned at 90 °C and cannot brown. Authoring-time only until CH-4 tabulates it                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **`ParcelStore`**                    | Structure-of-arrays `Float64Array` columns: substance, mass, enthalpy, position. `addHeat` is one addition and `temperatureOf` is one search                                                                                                                                                                                                                                                                                                                                                                                               |
+| **A parcel has depth**               | Nested shells of **equal mass**, so a large object's surface shell is thin and its core is fat. Heat enters shell 0 and conducts inward, and the interface conductivity is the **harmonic mean**, because a boundary is a series resistance                                                                                                                                                                                                                                                                                                |
+| **Thin catches, thick does not**     | Under 20 kW/m², a 2 mm slab's surface passes 300 °C in 29 s and an 80 mm one takes 400 s — and the 80 mm log's _core_ is five hundredths of a kelvin above the room while its surface chars                                                                                                                                                                                                                                                                                                                                                |
+| **Reactions that balance**           | Checked against the element matrix at registration and **refused naming the element and the gap**. Enthalpies derived by Hess's law, never typed in: methane comes out at its published heating values without either being written down                                                                                                                                                                                                                                                                                                   |
+| **Rates as tables**                  | `exp` never runs on a tick. Knots uniform in `1/T`, where `ln k` is exactly linear, measured under 0.5% against the closed form                                                                                                                                                                                                                                                                                                                                                                                                            |
+| **A solver that cannot go negative** | Sub-stepped by stiffness, then clamped: where demand exceeds what is present, every reaction drawing on that species is cut **by the same factor**, so the answer does not depend on registration order                                                                                                                                                                                                                                                                                                                                    |
+| **One atmosphere**                   | Sparse chunks, and empty air costs nothing. Conservative flux transport on the one wind plus buoyancy, a connectivity that makes a sealed room sealed, and a far-field ledger that balances                                                                                                                                                                                                                                                                                                                                                |
+| **Gas-phase combustion**             | The **same solver** a shell uses, given a cell — which is what lets a flame stand off a surface rather than sit on it                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| **Radiation, and `1/r²`**            | A source is declared and every parcel works out what reaches it. Move a log twice as far from a fire and it takes four times as long — one line of arithmetic, and the whole reason distance means anything                                                                                                                                                                                                                                                                                                                                |
+| **The parcels meet the air**         | A burning parcel draws the oxygen its reactions want out of the cell it sits in and pushes the gas they make into it. One relaxation, both directions                                                                                                                                                                                                                                                                                                                                                                                      |
+| **Ignition is a criterion**          | Five conditions, and `ignite` supplies one of them. **Holding a match to wet wood does nothing**, which is the API telling the truth about what a match is                                                                                                                                                                                                                                                                                                                                                                                 |
+| **Extinction is four**               | Fuel gone, oxygen below the limiting index, surface cooled, or blown off — and a smoulder survives air a flame cannot, which is why smothering leaves embers                                                                                                                                                                                                                                                                                                                                                                               |
+| **An event buffer**                  | Twenty-one kinds, drained per tick, in the shape `drift/physics`'s contact buffer established                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| **Char glows for an hour**           | Above about 800 K the chemistry outruns oxygen delivery, so the rate is transport, not kinetics. The two combine as a series resistance — and **blowing on an ember brightens it**                                                                                                                                                                                                                                                                                                                                                         |
+| **A smoulder's smoke is pale**       | Tar leaving a surface cracks to soot and burns where it is hot, and **condenses to droplets where it is not** — a 523 K dew point, which is Clausius-Clapeyron at the loading a plume carries rather than levoglucosan's 658 K boiling point. Two rates that climb with temperature against one gate that closes with it, so a flame blackens its own smoke and a smoulder whitens its own with nothing choosing. `aerosolAt` sums every carried species in the **liquid phase**, so the field never names a species this library invented |
+| **A log dries, smokes and catches**  | The whole of `§21`, asserted: the surface pins at the boiling point while the core stays cold, gas comes off, and it lights. **A green log at the same fire does not**                                                                                                                                                                                                                                                                                                                                                                     |
+| **Thirty-nine substances**           | Across seven entry points — organic, food, fuel, polymer, mineral, metal, biological — each with real compositions, thermophysics and reactions, and **each family costs 625 bytes to 1.3 kilobytes**, so a consumer who wants a campfire pays for a campfire                                                                                                                                                                                                                                                                              |
+
+## The substance library, and what it costs
+
+```ts
+import {
+  installLibrary,
+  ReactionRegistry,
+  SpeciesRegistry,
+  SubstanceRegistry,
+} from '@driftengine/chemistry';
+import { ORGANIC } from '@driftengine/chemistry/library/organic';
+
+installLibrary(ORGANIC, species, reactions, substances);
+const log = parcels.spawn({
+  substance: substances.indexOf('oak'),
+  mass: 8,
+  temperature: 293.15,
+  area: 0.2,
+});
+```
+
+| Entry point          | Substances                                                             | Cost over three you wrote yourself |
+| -------------------- | ---------------------------------------------------------------------- | ---------------------------------- |
+| `library/organic`    | oak, pine, paper, cotton, leather, straw                               | 1,279 B                            |
+| `library/food`       | water, ice, butter, beef-muscle, potato, egg-white, sugar              | 1,062 B                            |
+| `library/fuel`       | ethanol, petrol, diesel, kerosene, paraffin-wax                        | 926 B                              |
+| `library/biological` | compost, hay, flesh, must                                              | 845 B                              |
+| `library/polymer`    | polyethylene, polypropylene, pvc, polystyrene, pmma, polyurethane-foam | 734 B                              |
+| `library/mineral`    | limestone, gypsum-board, sand, clay, concrete, glass                   | 703 B                              |
+| `library/metal`      | iron, steel, aluminium, copper, magnesium                              | 625 B                              |
+
+Installing several is ordinary: they share the water phase changes, the five gas-phase combustion
+steps and the two char oxidations, and `installLibrary` skips what is already registered.
+
+**Some things the library does that nothing in it decides.** A candle is wax melting, then boiling,
+then burning — three gated reactions in series, and the word "candle" appears nowhere. A steak
+cannot brown while it is wet, because Maillard needs 140 °C and a wet surface is pinned at 100.
+PVC self-extinguishes in air and PMMA does not, on one number each. Char makes mostly CO₂ when it
+smoulders cool and mostly CO when it smoulders hot, because two activation energies differ by
+`6240·R` and that ratio **is** Arthur's relation. A hay bale respires, warms itself out of the
+mesophilic band and is picked up by the thermophiles above it. And burning leather gives off
+hydrogen cyanide, because collagen carries 1.3 nitrogens per residue and they have to go somewhere.
+
+**One bias, stated rather than buried.** Pyrolysis endotherms derived over this species set run
+high, because the volatile slate stops at C₂ and char is pure carbon where real volatiles are
+C₁₀–C₄₀ and real char keeps some hydrogen and oxygen. What is _not_ biased is the total: Hess's law
+over the whole path reproduces each material's measured heating value exactly, so what the cap
+distorts is the split between the gasification and the flame, not the heat. It bites hardest on the
+polyolefins and barely at all on wood, whose aggregate lands inside the measured band.
+
+## The one thing worth knowing before reading the code
+
+**A species stores a formation enthalpy and a heat capacity, and nothing reads them yet.** That is
+not an oversight. CH-3 builds the reaction network, and it derives every reaction's `ΔH` from these
+by Hess's law rather than taking a typed-in number — because a reaction enthalpy that disagreed
+with its own species would conserve energy _in the code_ and lose it _against the world_, with no
+symptom anywhere.
+
+So the numbers are checked here instead, where they are written: `standard.test.ts` reconstructs
+eighteen published higher heating values from the stored enthalpies and the element rows, and holds
+them to two percent, which is inside the spread of the published figures themselves.
+
+**Pseudo-species carry a back-derived enthalpy.** Cellulose, lignin, a protein residue and a diesel
+surrogate have never been in a calorimeter; what has been measured is what a kilogram of them gives
+off. Their formation enthalpies are derived from that, so Hess's law reproduces the heat the world
+actually releases. They are marked `pseudo: true`, so a reader can tell an exact number from a mean
+over a population.
+
+## Using it
+
+```ts
+import {
+  ELEMENT_COUNT,
+  SpeciesRegistry,
+  elementTotals,
+  massFractions,
+  registerStandardSpecies,
+} from '@driftengine/chemistry';
+
+const registry = new SpeciesRegistry();
+registerStandardSpecies(registry);
+
+// Seasoned oak, dry basis, as mass fractions that must sum to one.
+const oak = massFractions(registry, {
+  cellulose: 0.43,
+  hemicellulose: 0.26,
+  lignin: 0.26,
+  extractives: 0.04,
+  ash: 0.01,
+});
+
+// Ten kilograms of it, reduced to moles of each of the fifteen elements.
+const mass = new Float64Array(registry.count);
+for (let i = 0; i < oak.species.length; i++) {
+  mass[oak.species[i]!] = oak.fraction[i]! * 10;
+}
+const elements = new Float64Array(ELEMENT_COUNT);
+elementTotals(registry, mass, elements);
+```
+
+**Registration fails fast and never warns.** An unknown element, a duplicate id, a negative
+subscript, an empty formula, a composition that does not sum to one: each throws at init naming the
+offending value. Nothing here runs in a frame, so checking thoroughly costs nothing and not
+checking costs a `NaN` that surfaces twenty ticks into a burn.
+
+## Drawing it
+
+```ts
+import { installChemistry, writeSurface, emitSmoke } from '@driftengine/chemistry/present';
+```
+
+**`present/` imports nothing and names no core type.** Every target is described structurally by
+what it must have — core's `ParticleInstances` satisfies `SmokeTarget` exactly, and neither package
+knows the other exists. Six mappings, and every one is a physical quantity rather than an art
+direction: smoke colour from the soot-to-aerosol ratio, flame height from `L ≈ 0.235·Q^(2/5) −
+1.02·D`, glow from Planck at the surface temperature, albedo lerped by char fraction, roughness from
+the surface water film, and a scale from the cube root of what is left of the volume. Plus three
+audio scalars, and the package never touches `@driftengine/audio`.
+
+**Emissive in this engine is gated on `nightFactor`.** Embers written by `writeSurface` look right at
+dusk and dead at noon. That is `AGENTS.md`'s standing trap and it is said here because this is where
+a consumer meets it.
+
+`demo/dev/chemistry.html` is the scene: a hearth where the kettle sits at 99 °C, the green log sits
+at 100 °C, the ice core sits at −1 °C, the iron nail reaches 611 °C and the copper coin beside it
+reaches 75, and a panel in the corner reports element drift at 2.6e-10 over the whole run.
+
+## Budgets, tiers, and the fingerprint
+
+**A cold stone sleeps.** A parcel whose surface flux and reaction output have both been still for
+thirty ticks is skipped entirely, and wakes on heat, water, mass, a contact, or a fire coming within
+range — the last through a coarse scan spread round-robin over four ticks, so a thousand sleepers
+cost two hundred and fifty range comparisons a tick.
+
+**Four tiers, and every one conserves.** `Hero` is the resolution the substance declared, down to one
+shell every sixteenth tick at `Distant`. Shells are equal-mass by construction, so a fold is a
+proportional redistribution and mass, every element and enthalpy come through exactly — which is what
+makes a tier change safe mid-burn. What it costs is measured and stated: over five hundred seconds of
+fire, `Near` is exact, `Far` drifts 21% and `Distant` 43%, and the coarser tiers char _more_, because
+a lumped parcel has no cold core to hide behind.
+
+**`fingerprintChemistry`** is sixteen hexadecimal digits over parcel compositions, enthalpies, the
+field's elements and the substance registry — order-insensitive over parcels, because a handle is
+the order something was spawned in. Two libraries are two worlds and it says so.
+
+## What is absent
+
+**Nothing the design specified.** Condensed tar was the last of it and closed:
+`tar(l)` is carried the way `C(soot)` is, its formation enthalpy is the number pyrolysis oil's
+heating value measures directly, and the vapour that shipped first turns out to be the derived one.
+
+One thing inside CH-3 is knowingly approximate and is CH-5's gate: a substance's enthalpy curve is
+built from its _initial_ composition, so as reactions run, the temperature read back drifts by
+however much the true heat capacity has moved. Energy stays exact — the joules are added and
+subtracted directly — and the fix is written down in that phase's plan. See `ROADMAP.md`'s Track P row for the
+order, and the design's `§26` for the nine things the track refuses outright.

package/dist/conservation.d.ts

@@ -0,0 +1,9 @@
+import type { SpeciesRegistry } from './species/registry.ts';
+/**
+ * Reduce kilograms per species into moles per element.
+ *
+ * `out` is **overwritten**, not accumulated into, so a caller may hold one vector for the life of a
+ * world and re-derive totals every tick without clearing it first. `speciesMass` is indexed by
+ * species, so it is the registry's width; a species with no mass costs one comparison.
+ */
+export declare function elementTotals(registry: SpeciesRegistry, speciesMass: Float64Array, out: Float64Array): void;

package/dist/conservation.js

@@ -0,0 +1,38 @@
+/**
+ * Moles of each element held by a set of species masses.
+ *
+ * **This is the law `§6` of the design calls the most valuable test in the track**, and it is one
+ * reduction: kilograms of a species become moles through its derived molar mass, and moles of a
+ * species become moles of its elements through the species-by-element matrix.
+ *
+ * A chemistry model that does not conserve elements invents or destroys matter, and every symptom
+ * of that is subtle — fires that will not go out, mass that quietly grows, smoke that never clears.
+ * One assertion catches all of them, which is why this function exists before there is anything to
+ * conserve through.
+ *
+ * Writes into a caller-owned vector and allocates nothing, so it is affordable on a tick rather
+ * than only in a test.
+ */
+import { ELEMENT_COUNT } from './element/elements.js';
+/**
+ * Reduce kilograms per species into moles per element.
+ *
+ * `out` is **overwritten**, not accumulated into, so a caller may hold one vector for the life of a
+ * world and re-derive totals every tick without clearing it first. `speciesMass` is indexed by
+ * species, so it is the registry's width; a species with no mass costs one comparison.
+ */
+export function elementTotals(registry, speciesMass, out) {
+    if (speciesMass.length !== registry.count) {
+        throw new Error(`a mass vector is ${registry.count} wide, not ${speciesMass.length}`);
+    }
+    if (out.length !== ELEMENT_COUNT) {
+        throw new Error(`a totals vector is ${ELEMENT_COUNT} wide, not ${out.length}`);
+    }
+    out.fill(0);
+    for (let species = 0; species < speciesMass.length; species++) {
+        const kilograms = speciesMass[species];
+        if (kilograms === 0)
+            continue;
+        registry.elements.addScaledRow(species, kilograms / registry.molarMass(species), out);
+    }
+}

package/dist/element/elements.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The closed element set, and the atomic weights every molar mass is derived from.
+ *
+ * Fifteen elements, and the set is closed deliberately rather than for want of typing. Every
+ * species this package can hold is built from these, so the species-by-element matrix has a fixed
+ * width, `elementTotals` reduces into a fixed-length array, and the conservation assertion that
+ * `§6` of the design calls the most valuable test in the track is a comparison of two vectors of
+ * fifteen doubles rather than a walk over a dictionary.
+ *
+ * **Adding a sixteenth is a deliberate act with a cost**: every `Float64Array` sized by
+ * `ELEMENT_COUNT` grows, and a stored conservation baseline taken before the change no longer
+ * compares. That is the right amount of friction for a decision that widens the model's universe.
+ *
+ * The values are IUPAC conventional atomic weights in g/mol. They are *conventional* rather than
+ * the interval form the tables now publish, because a molar mass is arithmetic here and an interval
+ * would make every derived mass an interval too — which is honest and useless.
+ */
+/**
+ * The elements, in the order the design lists them: organic first, then the rest.
+ *
+ * The order is the wire format of every matrix row and every totals vector in this package, so it
+ * is frozen. Reordering it invalidates any baseline a consumer has stored, in exactly the way
+ * `AGENTS.md` says the RNG sequence is frozen.
+ */
+export declare const ELEMENTS: readonly ['C', 'H', 'O', 'N', 'S', 'Cl', 'Si', 'Ca', 'Fe', 'Al', 'Mg', 'Cu', 'Na', 'K', 'P'];
+export type ElementSymbol = (typeof ELEMENTS)[number];
+export declare const ELEMENT_COUNT: 15;
+/** Conventional atomic weights, g/mol, indexed the way `ELEMENTS` is. */
+export declare const ATOMIC_MASS: Float64Array<ArrayBuffer>;
+/** The index of an element symbol, or `-1` for anything this package does not carry. */
+export declare function elementIndex(symbol: string): number;

package/dist/element/elements.js

@@ -0,0 +1,73 @@
+/**
+ * The closed element set, and the atomic weights every molar mass is derived from.
+ *
+ * Fifteen elements, and the set is closed deliberately rather than for want of typing. Every
+ * species this package can hold is built from these, so the species-by-element matrix has a fixed
+ * width, `elementTotals` reduces into a fixed-length array, and the conservation assertion that
+ * `§6` of the design calls the most valuable test in the track is a comparison of two vectors of
+ * fifteen doubles rather than a walk over a dictionary.
+ *
+ * **Adding a sixteenth is a deliberate act with a cost**: every `Float64Array` sized by
+ * `ELEMENT_COUNT` grows, and a stored conservation baseline taken before the change no longer
+ * compares. That is the right amount of friction for a decision that widens the model's universe.
+ *
+ * The values are IUPAC conventional atomic weights in g/mol. They are *conventional* rather than
+ * the interval form the tables now publish, because a molar mass is arithmetic here and an interval
+ * would make every derived mass an interval too — which is honest and useless.
+ */
+/**
+ * The elements, in the order the design lists them: organic first, then the rest.
+ *
+ * The order is the wire format of every matrix row and every totals vector in this package, so it
+ * is frozen. Reordering it invalidates any baseline a consumer has stored, in exactly the way
+ * `AGENTS.md` says the RNG sequence is frozen.
+ */
+export const ELEMENTS = [
+    'C',
+    'H',
+    'O',
+    'N',
+    'S',
+    'Cl',
+    'Si',
+    'Ca',
+    'Fe',
+    'Al',
+    'Mg',
+    'Cu',
+    'Na',
+    'K',
+    'P',
+];
+export const ELEMENT_COUNT = ELEMENTS.length;
+/** Conventional atomic weights, g/mol, indexed the way `ELEMENTS` is. */
+export const ATOMIC_MASS = new Float64Array([
+    12.011, // C
+    1.008, // H
+    15.999, // O
+    14.007, // N
+    32.06, // S
+    35.45, // Cl
+    28.085, // Si
+    40.078, // Ca
+    55.845, // Fe
+    26.9815384, // Al
+    24.305, // Mg
+    63.546, // Cu
+    22.98976928, // Na
+    39.0983, // K
+    30.973761998, // P
+]);
+/*
+ * A map rather than an `indexOf`, and case-sensitive rather than folded.
+ *
+ * Case is load-bearing in chemical notation: `Co` is cobalt and `CO` is carbon monoxide, so a
+ * lookup that folded case would accept a molecule where an element was wanted and silently produce
+ * a molar mass for the wrong thing. Nothing here runs in a frame, so the map is for legibility
+ * rather than speed.
+ */
+const INDEX = new Map(ELEMENTS.map((symbol, at) => [symbol, at]));
+/** The index of an element symbol, or `-1` for anything this package does not carry. */
+export function elementIndex(symbol) {
+    return INDEX.get(symbol) ?? -1;
+}

package/dist/element/matrix.d.ts

@@ -0,0 +1,27 @@
+export declare class SpeciesElementMatrix {
+    private store;
+    private used;
+    get rows(): number;
+    /** Append a zeroed row and return its index. */
+    addRow(): number;
+    set(row: number, element: number, moles: number): void;
+    at(row: number, element: number): number;
+    /**
+     * A row as a view of fifteen, sharing storage rather than copying.
+     *
+     * **A view is invalidated by a later `addRow` that grows the table**, because growth reallocates.
+     * Every caller in this package takes a view inside a loop that registers nothing, which is the
+     * only safe pattern and is why this is not handed out as a promise.
+     */
+    rowView(row: number): Float64Array;
+    /**
+     * `out[e] += scale * this[row][e]`, for all fifteen. Allocates nothing.
+     *
+     * The primitive every conservation check is built from, and it exists rather than a loop over
+     * `at` for one reason: `rowView` would be the natural way to write that loop and `subarray`
+     * allocates a view object per call, which is an allocation per species per tick. It adds rather
+     * than replaces so a caller sums a whole world into one vector without a second accumulator.
+     */
+    addScaledRow(row: number, scale: number, out: Float64Array): void;
+    private check;
+}