@driftengine/chemistry 3.61.0

package/dist/species/standard.js

@@ -0,0 +1,436 @@
+/**
+ * The species a world starts knowing about: sixty-eight of them, in thirteen groups.
+ *
+ * **Every formation enthalpy is J/mol at 298.15 K and every heat capacity is J/(kg·K).** Real
+ * molecules carry published values. Pseudo-species — a lumped repeat unit, an average residue, a
+ * fuel surrogate — carry a value **back-derived from a measured higher heating value**, so that
+ * Hess's law over this table reproduces the heat the world actually releases. `standard.test.ts`
+ * asserts eighteen of them against published figures to within two percent, which is inside the
+ * spread of the published figures themselves.
+ *
+ * That derivation is the honest way round. A pseudo-species has no measured formation enthalpy,
+ * because it is not a substance anyone has put in a calorimeter; what *has* been measured is what
+ * a kilogram of it gives off. Deriving from the latter makes the table agree with the world at the
+ * only point the world was ever asked.
+ *
+ * **Argon is not here, and the design's §6 listed it.** It is 0.93% of air and chemically inert, so
+ * the only thing it contributes is heat capacity and dilution — and carrying it would have meant a
+ * sixteenth element for nothing else. It is lumped into N2, which is inert in the same way and
+ * makes up 78%.
+ *
+ * **Char and soot are graphite thermochemically**, all three at zero, because they are the same
+ * element in the same standard state. What separates them is density, conductivity, porosity and
+ * which reactions they take part in — every one of which is a property of a *substance* or a
+ * reaction rather than of a species.
+ */
+import { PHASE_GAS, PHASE_LIQUID, PHASE_SOLID } from './species.js';
+export const STANDARD_SPECIES = [
+    /* Atmospheric gases. The far field is these four plus whatever a fire has put into it. */
+    { id: 'O2', formula: { O: 2 }, phase: PHASE_GAS, formationEnthalpy: 0, cpA: 918 },
+    { id: 'N2', formula: { N: 2 }, phase: PHASE_GAS, formationEnthalpy: 0, cpA: 1040 },
+    {
+        id: 'CO2',
+        formula: { C: 1, O: 2 },
+        phase: PHASE_GAS,
+        formationEnthalpy: -393510,
+        cpA: 844,
+        cpB: 0.6,
+    },
+    {
+        id: 'H2O(g)',
+        formula: { H: 2, O: 1 },
+        phase: PHASE_GAS,
+        formationEnthalpy: -241826,
+        cpA: 1996,
+        cpB: 0.4,
+    },
+    /* Combustion gases. CO and HCN are the two that kill; both are reported in ppm, never judged. */
+    { id: 'CO', formula: { C: 1, O: 1 }, phase: PHASE_GAS, formationEnthalpy: -110530, cpA: 1040 },
+    {
+        id: 'CH4',
+        formula: { C: 1, H: 4 },
+        phase: PHASE_GAS,
+        formationEnthalpy: -74600,
+        cpA: 2220,
+        cpB: 5.2,
+    },
+    { id: 'H2', formula: { H: 2 }, phase: PHASE_GAS, formationEnthalpy: 0, cpA: 14300 },
+    { id: 'C2H4', formula: { C: 2, H: 4 }, phase: PHASE_GAS, formationEnthalpy: 52400, cpA: 1530 },
+    { id: 'C2H6', formula: { C: 2, H: 6 }, phase: PHASE_GAS, formationEnthalpy: -84000, cpA: 1750 },
+    { id: 'NH3', formula: { N: 1, H: 3 }, phase: PHASE_GAS, formationEnthalpy: -45900, cpA: 2190 },
+    {
+        id: 'HCN',
+        formula: { H: 1, C: 1, N: 1 },
+        phase: PHASE_GAS,
+        formationEnthalpy: 135100,
+        cpA: 1330,
+    },
+    { id: 'HCl', formula: { H: 1, Cl: 1 }, phase: PHASE_GAS, formationEnthalpy: -92310, cpA: 799 },
+    { id: 'SO2', formula: { S: 1, O: 2 }, phase: PHASE_GAS, formationEnthalpy: -296840, cpA: 640 },
+    { id: 'NO', formula: { N: 1, O: 1 }, phase: PHASE_GAS, formationEnthalpy: 91290, cpA: 995 },
+    { id: 'NO2', formula: { N: 1, O: 2 }, phase: PHASE_GAS, formationEnthalpy: 33200, cpA: 805 },
+    /* Condensed water. Ice sits one heat of fusion below liquid, which is where the plateau is. */
+    {
+        id: 'H2O(l)',
+        formula: { H: 2, O: 1 },
+        phase: PHASE_LIQUID,
+        formationEnthalpy: -285830,
+        cpA: 4182,
+    },
+    {
+        id: 'H2O(s)',
+        formula: { H: 2, O: 1 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -291840,
+        cpA: 2108,
+    },
+    /* Carbon, in the three forms a fire makes. See the header on why all three are zero. */
+    { id: 'C(graphite)', formula: { C: 1 }, phase: PHASE_SOLID, formationEnthalpy: 0, cpA: 709 },
+    { id: 'C(char)', formula: { C: 1 }, phase: PHASE_SOLID, formationEnthalpy: 0, cpA: 1100 },
+    { id: 'C(soot)', formula: { C: 1 }, phase: PHASE_SOLID, formationEnthalpy: 0, cpA: 850 },
+    /* Wood, as its three polymers plus the resins. Each pyrolyses on its own kinetics in CH-3, which
+       is why the smoke changes character as a log heats rather than arriving all at once. */
+    {
+        id: 'cellulose',
+        formula: { C: 6, H: 10, O: 5 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -968957,
+        cpA: 1340,
+        cpB: 4.9,
+        pseudo: true,
+    },
+    {
+        id: 'hemicellulose',
+        formula: { C: 5, H: 8, O: 4 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -997030,
+        cpA: 1380,
+        cpB: 4.9,
+        pseudo: true,
+    },
+    {
+        id: 'lignin',
+        formula: { C: 9, H: 10, O: 3 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -982516,
+        cpA: 1250,
+        cpB: 4.0,
+        pseudo: true,
+    },
+    {
+        id: 'extractives',
+        formula: { C: 10, H: 16 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -91030,
+        cpA: 1700,
+        pseudo: true,
+    },
+    /* The other biopolymers, and the two protein states cooking turns on. A denatured protein sits
+       *above* its native form, because unfolding costs energy; gelatin sits below collagen plus the
+       water it took up, because hydrolysing a peptide bond releases a little. */
+    {
+        id: 'starch',
+        formula: { C: 6, H: 10, O: 5 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -952742,
+        cpA: 1250,
+        pseudo: true,
+    },
+    {
+        id: 'chitin',
+        formula: { C: 8, H: 13, N: 1, O: 5 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -1450080,
+        cpA: 1300,
+        pseudo: true,
+    },
+    {
+        id: 'keratin',
+        formula: { C: 4.6, H: 7.6, N: 1.3, O: 1.4, S: 0.13 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -479628,
+        cpA: 1550,
+        pseudo: true,
+    },
+    {
+        id: 'collagen',
+        formula: { C: 4.3, H: 7.1, N: 1.3, O: 1.5 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -484532,
+        cpA: 1600,
+        pseudo: true,
+    },
+    {
+        id: 'protein',
+        formula: { C: 4.4, H: 7.7, N: 1.2, O: 1.4, S: 0.04 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -427487,
+        cpA: 1600,
+        pseudo: true,
+    },
+    {
+        id: 'protein(denatured)',
+        formula: { C: 4.4, H: 7.7, N: 1.2, O: 1.4, S: 0.04 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -417487,
+        cpA: 1600,
+        pseudo: true,
+    },
+    {
+        id: 'gelatin',
+        formula: { C: 4.3, H: 9.1, N: 1.3, O: 2.5 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -780362,
+        cpA: 1700,
+        pseudo: true,
+    },
+    /* Small organics: the sugars that caramelise and the liquids that dissolve things. */
+    {
+        id: 'glucose',
+        formula: { C: 6, H: 12, O: 6 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -1273300,
+        cpA: 1220,
+    },
+    {
+        id: 'fructose',
+        formula: { C: 6, H: 12, O: 6 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -1265600,
+        cpA: 1220,
+    },
+    {
+        id: 'sucrose',
+        formula: { C: 12, H: 22, O: 11 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -2226100,
+        cpA: 1250,
+    },
+    {
+        id: 'ethanol',
+        formula: { C: 2, H: 6, O: 1 },
+        phase: PHASE_LIQUID,
+        formationEnthalpy: -277600,
+        cpA: 2440,
+    },
+    {
+        id: 'methanol',
+        formula: { C: 1, H: 4, O: 1 },
+        phase: PHASE_LIQUID,
+        formationEnthalpy: -239200,
+        cpA: 2530,
+    },
+    {
+        id: 'acetic-acid',
+        formula: { C: 2, H: 4, O: 2 },
+        phase: PHASE_LIQUID,
+        formationEnthalpy: -484300,
+        cpA: 2050,
+    },
+    {
+        id: 'glycerol',
+        formula: { C: 3, H: 8, O: 3 },
+        phase: PHASE_LIQUID,
+        formationEnthalpy: -669600,
+        cpA: 2430,
+    },
+    /* Lipids. Saturated is tristearin and unsaturated is triolein, which is the difference between a
+       fat that is solid at room temperature and an oil that is not — a melting point rather than a
+       reaction, so it lives on the substance in CH-1. */
+    {
+        id: 'triglyceride(saturated)',
+        formula: { C: 57, H: 110, O: 6 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -2193700,
+        cpA: 1900,
+    },
+    {
+        id: 'triglyceride(unsaturated)',
+        formula: { C: 57, H: 104, O: 6 },
+        phase: PHASE_LIQUID,
+        formationEnthalpy: -2005000,
+        cpA: 2000,
+    },
+    {
+        id: 'fatty-acid',
+        formula: { C: 18, H: 36, O: 2 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -947700,
+        cpA: 1600,
+    },
+    {
+        id: 'wax',
+        formula: { C: 25, H: 52 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -869199,
+        cpA: 2100,
+        pseudo: true,
+    },
+    /* Fuel surrogates. Petrol is octane and diesel is dodecane — real molecules standing in for a
+       distillation cut, which is what a surrogate is. Kerosene has no integer formula at all. */
+    {
+        id: 'octane',
+        formula: { C: 8, H: 18 },
+        phase: PHASE_LIQUID,
+        formationEnthalpy: -250100,
+        cpA: 2230,
+    },
+    {
+        id: 'diesel',
+        formula: { C: 12, H: 26 },
+        phase: PHASE_LIQUID,
+        formationEnthalpy: -350900,
+        cpA: 2210,
+        pseudo: true,
+    },
+    {
+        id: 'kerosene',
+        formula: { C: 12, H: 23 },
+        phase: PHASE_LIQUID,
+        formationEnthalpy: -279166,
+        cpA: 2010,
+        pseudo: true,
+    },
+    {
+        id: 'propane',
+        formula: { C: 3, H: 8 },
+        phase: PHASE_GAS,
+        formationEnthalpy: -103800,
+        cpA: 1670,
+    },
+    {
+        id: 'butane',
+        formula: { C: 4, H: 10 },
+        phase: PHASE_GAS,
+        formationEnthalpy: -125700,
+        cpA: 1700,
+    },
+    /* Polymers, as repeat units. PVC carries the chlorine that becomes HCl in a fire and polyurethane
+       carries the nitrogen that becomes HCN — which is why a burning sofa is the dangerous one, and
+       it falls out of the formulas rather than out of a rule. */
+    {
+        id: 'polyethylene',
+        formula: { C: 2, H: 4 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -54169,
+        cpA: 2300,
+        pseudo: true,
+    },
+    {
+        id: 'polypropylene',
+        formula: { C: 3, H: 6 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -102294,
+        cpA: 1920,
+        pseudo: true,
+    },
+    {
+        id: 'PVC',
+        formula: { C: 2, H: 3, Cl: 1 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -40232,
+        cpA: 900,
+        pseudo: true,
+    },
+    {
+        id: 'polystyrene',
+        formula: { C: 8, H: 8 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: 72569,
+        cpA: 1300,
+        pseudo: true,
+    },
+    {
+        id: 'PMMA',
+        formula: { C: 5, H: 8, O: 2 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -487805,
+        cpA: 1470,
+        pseudo: true,
+    },
+    {
+        id: 'polyurethane',
+        formula: { C: 25, H: 42, N: 2, O: 6 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -3708086,
+        cpA: 1800,
+        pseudo: true,
+    },
+    /* Minerals. Gypsum is here for one reason: the two waters it loses at 100-150 C are an enormous
+       latent-heat sink, which is *why* plasterboard is a fire barrier. Limestone is here for the
+       other: calcination is endothermic and releases gas, which is why stone spalls in a fire. */
+    {
+        id: 'SiO2',
+        formula: { Si: 1, O: 2 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -910700,
+        cpA: 740,
+    },
+    {
+        id: 'CaCO3',
+        formula: { Ca: 1, C: 1, O: 3 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -1207600,
+        cpA: 820,
+    },
+    { id: 'CaO', formula: { Ca: 1, O: 1 }, phase: PHASE_SOLID, formationEnthalpy: -634900, cpA: 750 },
+    {
+        id: 'gypsum',
+        formula: { Ca: 1, S: 1, O: 6, H: 4 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -2022600,
+        cpA: 1090,
+    },
+    {
+        id: 'anhydrite',
+        formula: { Ca: 1, S: 1, O: 4 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -1434500,
+        cpA: 730,
+    },
+    {
+        id: 'Al2O3',
+        formula: { Al: 2, O: 3 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -1675700,
+        cpA: 880,
+    },
+    {
+        id: 'Fe2O3',
+        formula: { Fe: 2, O: 3 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -824200,
+        cpA: 650,
+    },
+    {
+        id: 'Fe3O4',
+        formula: { Fe: 3, O: 4 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: -1118400,
+        cpA: 620,
+    },
+    { id: 'MgO', formula: { Mg: 1, O: 1 }, phase: PHASE_SOLID, formationEnthalpy: -601600, cpA: 930 },
+    { id: 'CuO', formula: { Cu: 1, O: 1 }, phase: PHASE_SOLID, formationEnthalpy: -157300, cpA: 530 },
+    /* Ash is the one species with an arbitrary enthalpy, and it is arbitrary because nothing ever
+       produces or consumes it: a substance holds its ash from the start and every reaction leaves it
+       alone. Zero is therefore not a claim about ash, it is the absence of one. */
+    {
+        id: 'ash',
+        formula: { Si: 0.4, Ca: 0.3, K: 0.15, Mg: 0.1, P: 0.05, O: 1.2 },
+        phase: PHASE_SOLID,
+        formationEnthalpy: 0,
+        cpA: 800,
+        pseudo: true,
+    },
+    /* Metals. Magnesium is here because it burns, which most metals do not at any temperature a fire
+       reaches, and iron because it rusts, which is the slowest reaction in the whole model. */
+    { id: 'Fe', formula: { Fe: 1 }, phase: PHASE_SOLID, formationEnthalpy: 0, cpA: 449 },
+    { id: 'Al', formula: { Al: 1 }, phase: PHASE_SOLID, formationEnthalpy: 0, cpA: 897 },
+    { id: 'Cu', formula: { Cu: 1 }, phase: PHASE_SOLID, formationEnthalpy: 0, cpA: 385 },
+    { id: 'Mg', formula: { Mg: 1 }, phase: PHASE_SOLID, formationEnthalpy: 0, cpA: 1023 },
+];
+/** Register the whole standard set into a registry, in order. */
+export function registerStandardSpecies(registry) {
+    for (const definition of STANDARD_SPECIES)
+        registry.register(definition);
+}

package/dist/species/thermal.d.ts

@@ -0,0 +1,18 @@
+/** K. Below this nothing in this engine is modelled, and a reading clamps rather than extrapolates. */
+export declare const MIN_MODEL_TEMPERATURE = 100;
+/** K. Above this likewise — past any flame this model produces. */
+export declare const MAX_MODEL_TEMPERATURE = 4000;
+/** Specific enthalpy of a species at a temperature, J/kg, zero at the standard state. */
+export declare function sensibleEnthalpy(cpA: number, cpB: number, temperature: number): number;
+/**
+ * The temperature a body of heat capacity `A + B·ΔT` sits at holding `joules`.
+ *
+ * `A` and `B` are **absolute** — kilograms times specific heat, summed over whatever is present —
+ * so `joules` is the total the thing holds rather than a specific value, and there is no division
+ * before the inversion.
+ *
+ * Clamped at both ends rather than extrapolated, and answering the standard state for a body with
+ * no heat capacity at all: a temperature is not a meaningful question about an empty shell, and
+ * inventing one is worse than declining.
+ */
+export declare function temperatureFromCapacity(A: number, B: number, joules: number): number;

package/dist/species/thermal.js

@@ -0,0 +1,72 @@
+/**
+ * Temperature from enthalpy, in closed form, from whatever a thing is made of right now.
+ *
+ * **This replaces `§3`'s per-substance enthalpy curve, and the reversal is CH-6's opening move.**
+ * That curve was built from a substance's *initial* composition, so the temperature it reported
+ * drifted as reactions changed what was actually there — about 20% of the rise for cellulose
+ * becoming char. Ignition is a surface temperature crossing 623 K, so nothing could be allowed to
+ * read it.
+ *
+ * **The repair is smaller than the thing it repairs, because the latent heat was never sensible
+ * enthalpy's job.** It is already in the formation enthalpies CH-0 stores: `H₂O(s) → H₂O(l)` comes
+ * out of Hess's law at 333,611 J/kg against a literature 333,550. So a phase change is a *reaction*
+ * with a temperature gate, its plateau emerges from the substep-and-clamp solver that already
+ * exists, and what is left here is purely sensible heat:
+ *
+ *     h = A·ΔT + B·ΔT²/2          A = Σ mᵢ·cpAᵢ,  B = Σ mᵢ·cpBᵢ,  ΔT = T − 298.15
+ *
+ * A quadratic, so inverting it is a formula rather than a search:
+ *
+ *     ΔT = (−A + √(A² + 2·B·h)) / B
+ *
+ * **One square root, which is one of the two operations ECMAScript specifies exactly** — `§15`
+ * permits it where it forbids `exp` and `pow`, and Track B's solver already leans on the same fact.
+ * Cheaper than the 256-knot binary search it replaces, composition-aware by construction, and it
+ * deletes machinery rather than adding to it.
+ */
+import { STANDARD_TEMPERATURE } from './species.js';
+/** K. Below this nothing in this engine is modelled, and a reading clamps rather than extrapolates. */
+export const MIN_MODEL_TEMPERATURE = 100;
+/** K. Above this likewise — past any flame this model produces. */
+export const MAX_MODEL_TEMPERATURE = 4000;
+/** Specific enthalpy of a species at a temperature, J/kg, zero at the standard state. */
+export function sensibleEnthalpy(cpA, cpB, temperature) {
+    const dT = temperature - STANDARD_TEMPERATURE;
+    return cpA * dT + (cpB * dT * dT) / 2;
+}
+/**
+ * The temperature a body of heat capacity `A + B·ΔT` sits at holding `joules`.
+ *
+ * `A` and `B` are **absolute** — kilograms times specific heat, summed over whatever is present —
+ * so `joules` is the total the thing holds rather than a specific value, and there is no division
+ * before the inversion.
+ *
+ * Clamped at both ends rather than extrapolated, and answering the standard state for a body with
+ * no heat capacity at all: a temperature is not a meaningful question about an empty shell, and
+ * inventing one is worse than declining.
+ */
+export function temperatureFromCapacity(A, B, joules) {
+    if (!(A > 0))
+        return STANDARD_TEMPERATURE;
+    let dT;
+    if (B === 0) {
+        dT = joules / A;
+    }
+    else {
+        const discriminant = A * A + 2 * B * joules;
+        if (!(discriminant >= 0)) {
+            /* Past the turning point of the quadratic, which means past where a linear `cp` is a model of
+               anything. The sign of `B` says which end it ran off. */
+            return B > 0 ? MIN_MODEL_TEMPERATURE : MAX_MODEL_TEMPERATURE;
+        }
+        /* The branch through `ΔT = 0`, which is this root for either sign of `B`: at `h = 0` the
+           discriminant is `A²`, the square root is `A`, and the numerator is zero. */
+        dT = (-A + Math.sqrt(discriminant)) / B;
+    }
+    const temperature = STANDARD_TEMPERATURE + dT;
+    if (temperature < MIN_MODEL_TEMPERATURE)
+        return MIN_MODEL_TEMPERATURE;
+    if (temperature > MAX_MODEL_TEMPERATURE)
+        return MAX_MODEL_TEMPERATURE;
+    return temperature;
+}

package/dist/substance/boiling.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where a liquid boils at a pressure that is not one atmosphere.
+ *
+ * Clausius-Clapeyron, integrated with the latent heat held constant over the range:
+ *
+ *     1/T = 1/T0 - (R / L_molar) * ln(P / P0)
+ *
+ * **Why it matters is `§8.1` and `§22`.** A boiling point is the ceiling a wet surface's
+ * temperature is pinned at, so moving it moves what the surface can do. At 3,000 metres water boils
+ * near 90 C, a stew there cannot reach the 140 C Maillard browning needs, and food genuinely does
+ * not brown in a pot at altitude. Under two atmospheres it boils near 121 C, which is a pressure
+ * cooker and is also why an autoclave sterilises at that number.
+ *
+ * **Authoring-time only, and that is a rule rather than a note.** This calls `log`, and `§7` bans
+ * transcendentals from the tick — they are the easiest place in the engine to lose determinism
+ * between platforms. CH-4 supplies a per-cell pressure, and when it does this is tabulated the way
+ * every rate law already is. Until then a caller passes a pressure at setup.
+ *
+ * Constant latent heat is the approximation, and it is a good one over the range a game covers:
+ * water's `L` falls about 6% between 100 C and 120 C, which moves the answer by a few tenths of a
+ * kelvin. It breaks down approaching the critical point, which nothing here goes near.
+ */
+/**
+ * @param referenceTemperature K, where this liquid boils at `referencePressure`
+ * @param latentHeat J **per kilogram** of the species that changes phase
+ * @param molarMass kg/mol, matching `SpeciesRegistry.molarMass`
+ * @param pressure Pa
+ */
+export declare function boilingPoint(referenceTemperature: number, latentHeat: number, molarMass: number, pressure: number, referencePressure?: number): number;

package/dist/substance/boiling.js

@@ -0,0 +1,54 @@
+/**
+ * Where a liquid boils at a pressure that is not one atmosphere.
+ *
+ * Clausius-Clapeyron, integrated with the latent heat held constant over the range:
+ *
+ *     1/T = 1/T0 - (R / L_molar) * ln(P / P0)
+ *
+ * **Why it matters is `§8.1` and `§22`.** A boiling point is the ceiling a wet surface's
+ * temperature is pinned at, so moving it moves what the surface can do. At 3,000 metres water boils
+ * near 90 C, a stew there cannot reach the 140 C Maillard browning needs, and food genuinely does
+ * not brown in a pot at altitude. Under two atmospheres it boils near 121 C, which is a pressure
+ * cooker and is also why an autoclave sterilises at that number.
+ *
+ * **Authoring-time only, and that is a rule rather than a note.** This calls `log`, and `§7` bans
+ * transcendentals from the tick — they are the easiest place in the engine to lose determinism
+ * between platforms. CH-4 supplies a per-cell pressure, and when it does this is tabulated the way
+ * every rate law already is. Until then a caller passes a pressure at setup.
+ *
+ * Constant latent heat is the approximation, and it is a good one over the range a game covers:
+ * water's `L` falls about 6% between 100 C and 120 C, which moves the answer by a few tenths of a
+ * kelvin. It breaks down approaching the critical point, which nothing here goes near.
+ */
+/** J/(mol·K). */
+const GAS_CONSTANT = 8.314462618;
+/** Pa. The standard atmosphere every reference temperature in this package is quoted at. */
+const REFERENCE_PRESSURE = 101325;
+/**
+ * @param referenceTemperature K, where this liquid boils at `referencePressure`
+ * @param latentHeat J **per kilogram** of the species that changes phase
+ * @param molarMass kg/mol, matching `SpeciesRegistry.molarMass`
+ * @param pressure Pa
+ */
+export function boilingPoint(referenceTemperature, latentHeat, molarMass, pressure, referencePressure = REFERENCE_PRESSURE) {
+    if (!(pressure > 0)) {
+        throw new Error(`boiling point asked at a pressure of ${pressure} Pa`);
+    }
+    if (!(referencePressure > 0)) {
+        throw new Error(`boiling point asked against a reference pressure of ${referencePressure} Pa`);
+    }
+    if (!(latentHeat > 0)) {
+        throw new Error(`latent heat is ${latentHeat}, which is not positive`);
+    }
+    if (!(molarMass > 0)) {
+        throw new Error(`molar mass is ${molarMass}, which is not positive`);
+    }
+    const molarLatentHeat = latentHeat * molarMass;
+    // determinism: build-time — a boiling point derived at registration, from constants
+    const logPressureRatio = Math.log(pressure / referencePressure);
+    const inverse = 1 / referenceTemperature - (GAS_CONSTANT / molarLatentHeat) * logPressureRatio;
+    if (!(inverse > 0)) {
+        throw new Error(`a pressure of ${pressure} Pa puts this liquid past its critical point`);
+    }
+    return 1 / inverse;
+}

package/dist/substance/composition.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What a material is made of: mass fractions over species, summing to one.
+ *
+ * **Mass fractions rather than moles**, and it is the open question `§30` of the design marks
+ * first. Mass is what a consumer thinks in, what a density multiplies, and what a parcel stores;
+ * moles are what stoichiometry wants. The conversion is one multiply by the derived molar mass and
+ * it happens at the reaction boundary, which is the one place that needs it.
+ *
+ * Two parallel arrays rather than a map, because every consumer of a composition walks it in a
+ * loop and a map's iteration allocates.
+ */
+import type { SpeciesRegistry } from '../species/registry.ts';
+/**
+ * How far a hand-written composition may be from summing to one.
+ *
+ * Generous enough for six fractions typed to three decimals, tight enough that a transposed digit
+ * is a refusal rather than a material that quietly loses half a percent of its mass on every
+ * conservation check.
+ */
+export declare const SUM_TOLERANCE = 0.000001;
+export interface Composition {
+    /** Species indices, ascending. */
+    readonly species: Int32Array;
+    /** Mass fraction of each, parallel to `species`. */
+    readonly fraction: Float64Array;
+}
+/**
+ * A composition from species ids and mass fractions.
+ *
+ * Fails fast on anything wrong, per `AGENTS.md`: an unknown id, a fraction that is negative or not
+ * a number, a sum that is not one. Each names the offending value, because "invalid composition" in
+ * a stack trace is a sentence somebody has to reproduce to act on.
+ */
+export declare function massFractions(registry: SpeciesRegistry, entries: Readonly<Record<string, number>>): Composition;