@driftengine/chemistry 3.61.0

package/src/library/food.ts

@@ -0,0 +1,302 @@
+/**
+ * `@driftengine/chemistry/library/food` — water, fat, protein, starch, sugar, and cooking.
+ *
+ * **Nothing here is a cooking rule.** Every claim a cook makes about searing is a consequence of one
+ * fact the model already had: a wet surface is pinned at the boiling point by CH-6's vaporisation
+ * plateau, and Maillard needs forty degrees more than that. So browning is not forbidden while the
+ * surface is wet — it is *unreachable*, which is a much stronger statement and costs nothing.
+ *
+ * The one species this library adds is molten fat, because fat melting is a phase change between two
+ * states of one material and this model expresses a phase change as a reaction between two species.
+ */
+import { PHASE_LIQUID, type SpeciesDefinition } from '../species/species.ts';
+import {
+  KIND_BROWNING,
+  KIND_DENATURATION,
+  type Reaction,
+  phaseChange,
+} from '../reaction/reaction.ts';
+import { SHAPE_SLAB, SHAPE_SPHERE } from '../parcel/shells.ts';
+import { massFractions } from '../substance/composition.ts';
+import { wetComposition } from '../substance/substance.ts';
+import type { SubstanceThermal } from '../substance/substance.ts';
+import type { SubstanceLibrary } from './library.ts';
+import { BOIL_WATER, COMMON_REACTIONS, MELT_ICE } from './common.ts';
+
+export const MELT_FAT = 'melt-fat';
+export const DENATURE_MYOSIN = 'denature-myosin';
+export const DENATURE_ALBUMEN = 'denature-albumen';
+export const GELATINISE_COLLAGEN = 'gelatinise-collagen';
+export const HYDROLYSE_STARCH = 'hydrolyse-starch';
+export const BROWN_MAILLARD = 'brown-maillard';
+export const CARAMELISE = 'caramelise';
+
+/**
+ * Molten fat: the same molecule as `triglyceride(saturated)`, one heat of fusion above it.
+ *
+ * 190 J/g, which is tristearin's measured enthalpy of fusion, and it is **stored** rather than
+ * derived — unavoidably, because a phase pair is two species and the gap between their formation
+ * enthalpies *is* the latent heat. Water's two transitions are derived only because CH-0 happened to
+ * have published formation enthalpies for ice, water and steam separately; nobody has published one
+ * for molten tristearin.
+ */
+const MOLTEN_FAT: SpeciesDefinition = {
+  id: 'fat(liquid)',
+  formula: { C: 57, H: 110, O: 6 },
+  phase: PHASE_LIQUID,
+  formationEnthalpy: -2024313,
+  cpA: 2100,
+  pseudo: true,
+};
+
+/** K over which butter softens. `§8.1`: a mixture of triglycerides, so a band and not a point. */
+const FAT_BAND = 3;
+
+const REACTIONS: readonly Reaction[] = [
+  ...COMMON_REACTIONS,
+
+  /* 33-35 °C, over three kelvin, which is what makes fat render instead of switching state. */
+  phaseChange(MELT_FAT, 'triglyceride(saturated)', 'fat(liquid)', 306.15, FAT_BAND),
+
+  {
+    /* Myosin, at 50-55 °C: the meat firms and turns opaque. */
+    id: DENATURE_MYOSIN,
+    reactants: [{ species: 'protein', moles: 1 }],
+    products: [{ species: 'protein(denatured)', moles: 1 }],
+    kinetics: { type: 'arrhenius', A: 0.4, activationEnergy: 0 },
+    kind: KIND_DENATURATION,
+    gates: { minTemperature: 323.15, width: 5 },
+  },
+  {
+    /* Egg white sets at 62 °C, and the yolk at 68 — which is why a 63 °C egg is a thing. The two
+       bands are two reactions rather than one, because they are two proteins. */
+    id: DENATURE_ALBUMEN,
+    reactants: [{ species: 'protein', moles: 1 }],
+    products: [{ species: 'protein(denatured)', moles: 1 }],
+    kinetics: { type: 'arrhenius', A: 0.4, activationEnergy: 0 },
+    kind: KIND_DENATURATION,
+    gates: { minTemperature: 335.15, width: 3 },
+  },
+  {
+    /*
+     * **The rate is back-derived from two measured times**, which is what an activation energy is:
+     * many hours at 60 °C and about an hour at 80 °C is a factor of eight over twenty kelvin, and
+     * that factor fixes `Ea` at 101.6 kJ/mol. `A` then sets the absolute clock from the second time.
+     *
+     * The consequence is the whole of slow cooking: this reaction and the ones that dry the meat out
+     * are a genuine competition between two rates, and at 80 °C this one is winning.
+     */
+    id: GELATINISE_COLLAGEN,
+    reactants: [
+      { species: 'collagen', moles: 1 },
+      { species: 'H2O(l)', moles: 1 },
+    ],
+    products: [{ species: 'gelatin', moles: 1 }],
+    kinetics: { type: 'arrhenius', A: 3e11, activationEnergy: 101600 },
+    kind: KIND_DENATURATION,
+    gates: { minTemperature: 333.15, width: 5 },
+  },
+  {
+    /* Starch to sugar, needing water and warmth. It is what puts a reducing sugar on the surface of
+       a potato, and therefore what lets a potato brown at all. */
+    id: HYDROLYSE_STARCH,
+    reactants: [
+      { species: 'starch', moles: 1 },
+      { species: 'H2O(l)', moles: 1 },
+    ],
+    products: [{ species: 'glucose', moles: 1 }],
+    kinetics: { type: 'arrhenius', A: 1e11, activationEnergy: 100000 },
+    kind: KIND_DENATURATION,
+    gates: { minTemperature: 328.15, width: 10 },
+  },
+  {
+    /*
+     * Browning, at 140 °C, and the product is carbon because carbon is what a crust is.
+     *
+     * **The amino donor is not a reactant, and that is a stated simplification.** Maillard needs a
+     * reducing sugar and an amino group; the sugar is the scarce one and the protein is always there
+     * in the foods where this matters, so making the protein a reactant would have bought nothing
+     * and cost a nitrogen path with nowhere to go. What is modelled is the sugar being consumed and
+     * a dark surface appearing, which is what `§17` reads.
+     */
+    id: BROWN_MAILLARD,
+    reactants: [{ species: 'glucose', moles: 1 }],
+    products: [
+      { species: 'C(char)', moles: 6 },
+      { species: 'H2O(g)', moles: 6 },
+    ],
+    kinetics: { type: 'arrhenius', A: 4e12, activationEnergy: 130000 },
+    kind: KIND_BROWNING,
+    gates: { minTemperature: 413.15, width: 8 },
+  },
+  {
+    /* Sugar alone, twenty degrees higher, and no protein needed. */
+    id: CARAMELISE,
+    reactants: [{ species: 'sucrose', moles: 1 }],
+    products: [
+      { species: 'C(char)', moles: 12 },
+      { species: 'H2O(g)', moles: 11 },
+    ],
+    kinetics: { type: 'arrhenius', A: 4e12, activationEnergy: 130000 },
+    kind: KIND_BROWNING,
+    gates: { minTemperature: 433.15, width: 10 },
+  },
+];
+
+export const FOOD: SubstanceLibrary = {
+  id: 'food',
+  species: [MOLTEN_FAT],
+  reactions: REACTIONS,
+  substances: (species): readonly SubstanceThermal[] => [
+    {
+      id: 'water',
+      composition: massFractions(species, { 'H2O(l)': 1 }),
+      density: 997,
+      conductivity: { k0: 0.6, k1: 0 },
+      shells: 2,
+      shape: SHAPE_SPHERE,
+      emissivity: 0.96,
+      reactions: [BOIL_WATER],
+      appearance: {
+        albedo: [0.02, 0.03, 0.04],
+        charAlbedo: [0.02, 0.03, 0.04],
+        sootYield: 0,
+      },
+    },
+    {
+      /* Authored as the coldest form, per `SubstanceThermal`: ice with two transitions rather than
+         water with one in each direction, because a reaction runs one way. */
+      id: 'ice',
+      composition: massFractions(species, { 'H2O(s)': 1 }),
+      density: 917,
+      conductivity: { k0: 2.2, k1: -0.01 },
+      shells: 3,
+      shape: SHAPE_SPHERE,
+      emissivity: 0.97,
+      reactions: [MELT_ICE, BOIL_WATER],
+      appearance: {
+        albedo: [0.72, 0.78, 0.82],
+        charAlbedo: [0.72, 0.78, 0.82],
+        sootYield: 0,
+      },
+    },
+    {
+      /* Eighty percent fat, sixteen water, and the water is why it spits. */
+      id: 'butter',
+      composition: wetComposition(
+        species,
+        massFractions(species, {
+          'triglyceride(saturated)': 0.94,
+          protein: 0.04,
+          ash: 0.02,
+        }),
+        0.19,
+      ),
+      density: 911,
+      conductivity: { k0: 0.2, k1: 0 },
+      shells: 2,
+      shape: SHAPE_SLAB,
+      emissivity: 0.93,
+      reactions: [MELT_FAT, BOIL_WATER, DENATURE_MYOSIN],
+      appearance: {
+        albedo: [0.86, 0.76, 0.42],
+        charAlbedo: [0.1, 0.06, 0.03],
+        sootYield: 0.05,
+      },
+    },
+    {
+      /* Seventy-two percent water by mass, which is `moisture: 2.571` on a dry basis — and getting
+         that conversion wrong is the mistake `wetComposition` exists to prevent. */
+      id: 'beef-muscle',
+      composition: wetComposition(
+        species,
+        massFractions(species, {
+          protein: 0.74,
+          'triglyceride(saturated)': 0.15,
+          collagen: 0.08,
+          glucose: 0.01,
+          ash: 0.02,
+        }),
+        2.571,
+      ),
+      density: 1050,
+      conductivity: { k0: 0.45, k1: 0.0005 },
+      shells: 4,
+      shape: SHAPE_SLAB,
+      porosity: 0.1,
+      emissivity: 0.95,
+      reactions: [BOIL_WATER, MELT_FAT, DENATURE_MYOSIN, GELATINISE_COLLAGEN, BROWN_MAILLARD],
+      appearance: {
+        albedo: [0.42, 0.12, 0.11],
+        charAlbedo: [0.05, 0.03, 0.02],
+        sootYield: 0.04,
+      },
+    },
+    {
+      /* Starch, and the free sugar that lets it brown. A potato browns because starch hydrolyses
+         first — which is why a blanched chip browns and a raw one goes grey. */
+      id: 'potato',
+      composition: wetComposition(
+        species,
+        massFractions(species, {
+          starch: 0.8,
+          protein: 0.09,
+          glucose: 0.05,
+          ash: 0.06,
+        }),
+        3.762,
+      ),
+      density: 1080,
+      conductivity: { k0: 0.55, k1: 0.0005 },
+      shells: 4,
+      shape: SHAPE_SPHERE,
+      porosity: 0.15,
+      emissivity: 0.93,
+      reactions: [BOIL_WATER, HYDROLYSE_STARCH, DENATURE_MYOSIN, BROWN_MAILLARD],
+      appearance: {
+        albedo: [0.72, 0.62, 0.38],
+        charAlbedo: [0.06, 0.04, 0.02],
+        sootYield: 0.02,
+      },
+    },
+    {
+      /* Eighty-eight percent water, and it sets twelve degrees above where muscle firms. */
+      id: 'egg-white',
+      composition: wetComposition(
+        species,
+        massFractions(species, {
+          protein: 0.92,
+          glucose: 0.02,
+          ash: 0.06,
+        }),
+        7.333,
+      ),
+      density: 1040,
+      conductivity: { k0: 0.6, k1: 0.0005 },
+      shells: 3,
+      shape: SHAPE_SPHERE,
+      emissivity: 0.95,
+      reactions: [BOIL_WATER, DENATURE_ALBUMEN, BROWN_MAILLARD],
+      appearance: {
+        albedo: [0.88, 0.87, 0.82],
+        charAlbedo: [0.08, 0.06, 0.04],
+        sootYield: 0.02,
+      },
+    },
+    {
+      id: 'sugar',
+      composition: massFractions(species, { sucrose: 1 }),
+      density: 1590,
+      conductivity: { k0: 0.15, k1: 0 },
+      shells: 2,
+      shape: SHAPE_SLAB,
+      emissivity: 0.9,
+      reactions: [CARAMELISE],
+      appearance: {
+        albedo: [0.92, 0.9, 0.86],
+        charAlbedo: [0.08, 0.04, 0.02],
+        sootYield: 0.03,
+      },
+    },
+  ],
+};

package/src/library/fuel.ts

@@ -0,0 +1,299 @@
+/**
+ * `@driftengine/chemistry/library/fuel` — the liquids and the gas, and what they do before they burn.
+ *
+ * **A liquid fuel does not burn; its vapour does.** That is why a pool fire's burning rate is a
+ * heat-transfer number rather than a chemical one, why a cold pool of diesel will not light from a
+ * match and a cold pool of petrol will, and why throwing sand on one works. So every liquid here
+ * carries a vaporisation before it carries a combustion, and the two are ordinary gated reactions.
+ *
+ * **Six species, and each is an existing liquid plus a measured enthalpy of vaporisation.** Nothing
+ * about combustion went into any of them, so the heating values that come out of the burn reactions
+ * are predictions — and `fuel.test.ts` checks each against its published figure.
+ */
+import { PHASE_GAS, PHASE_LIQUID, type SpeciesDefinition } from '../species/species.ts';
+import { KIND_COMBUSTION, type Reaction, phaseChange } from '../reaction/reaction.ts';
+import { SHAPE_CYLINDER, SHAPE_SLAB } from '../parcel/shells.ts';
+import { massFractions } from '../substance/composition.ts';
+import type { SubstanceThermal } from '../substance/substance.ts';
+import type { SubstanceLibrary } from './library.ts';
+import { COMMON_REACTIONS, GAS_REACTIONS } from './common.ts';
+
+export const BURN_ETHANOL = 'burn-ethanol';
+export const BURN_PETROL = 'burn-petrol';
+export const BURN_DIESEL = 'burn-diesel';
+export const BURN_KEROSENE = 'burn-kerosene';
+export const BURN_PROPANE = 'burn-propane';
+export const BURN_WAX = 'burn-wax';
+
+/** What an `AtmosphereField` is given where any of these fuels is in play. */
+export const FUEL_GAS_REACTIONS: readonly string[] = [
+  ...GAS_REACTIONS,
+  BURN_ETHANOL,
+  BURN_PETROL,
+  BURN_DIESEL,
+  BURN_KEROSENE,
+  BURN_PROPANE,
+  BURN_WAX,
+];
+
+/*
+ * The vapours. Each formation enthalpy is the liquid's plus that liquid's measured enthalpy of
+ * vaporisation at 298.15 K, and three of the four with a published gas-phase value land within
+ * 0.6% of it — ethanol −235,300 against −234,800, octane −208,600 against −208,750, dodecane
+ * −289,400 against −290,900. That agreement is the arithmetic checking itself.
+ */
+const VAPOURS: readonly SpeciesDefinition[] = [
+  {
+    id: 'ethanol(g)',
+    formula: { C: 2, H: 6, O: 1 },
+    phase: PHASE_GAS,
+    formationEnthalpy: -235300,
+    cpA: 1420,
+    cpB: 3.5,
+  },
+  {
+    id: 'octane(g)',
+    formula: { C: 8, H: 18 },
+    phase: PHASE_GAS,
+    formationEnthalpy: -208600,
+    cpA: 1650,
+    cpB: 4.0,
+  },
+  {
+    id: 'diesel(g)',
+    formula: { C: 12, H: 26 },
+    phase: PHASE_GAS,
+    formationEnthalpy: -289400,
+    cpA: 1640,
+    cpB: 4.0,
+    pseudo: true,
+  },
+  {
+    id: 'kerosene(g)',
+    formula: { C: 12, H: 23 },
+    phase: PHASE_GAS,
+    formationEnthalpy: -219166,
+    cpA: 1600,
+    cpB: 3.8,
+    pseudo: true,
+  },
+  /*
+   * Wax gets two, because a candle is two plateaus in series. Fusion is 200 J/g and vaporisation is
+   * 284 J/g, both measured on paraffin; over 352.69 g/mol those are 70,538 and 100,000 J/mol.
+   */
+  {
+    id: 'wax(l)',
+    formula: { C: 25, H: 52 },
+    phase: PHASE_LIQUID,
+    formationEnthalpy: -798661,
+    cpA: 2300,
+    pseudo: true,
+  },
+  {
+    id: 'wax(g)',
+    formula: { C: 25, H: 52 },
+    phase: PHASE_GAS,
+    formationEnthalpy: -698661,
+    cpA: 2400,
+    cpB: 3.0,
+    pseudo: true,
+  },
+];
+
+const REACTIONS: readonly Reaction[] = [
+  ...COMMON_REACTIONS,
+
+  /*
+   * The boiling points, and the **widths are the interesting half**: ethanol is one molecule and
+   * boils at a point, where diesel and kerosene are distillation cuts and boil over tens of kelvin.
+   * Same gate, different width, and the consequence is that a cut keeps giving off vapour across a
+   * range of surface temperatures instead of all at once.
+   */
+  phaseChange('vaporise-ethanol', 'ethanol', 'ethanol(g)', 351.45, 0.5),
+  phaseChange('vaporise-petrol', 'octane', 'octane(g)', 398.75, 1),
+  phaseChange('vaporise-diesel', 'diesel', 'diesel(g)', 489.15, 20),
+  phaseChange('vaporise-kerosene', 'kerosene', 'kerosene(g)', 470.15, 20),
+  phaseChange('melt-wax', 'wax', 'wax(l)', 330.15, 8),
+  phaseChange('vaporise-wax', 'wax(l)', 'wax(g)', 660.15, 10),
+
+  {
+    id: BURN_ETHANOL,
+    reactants: [
+      { species: 'ethanol(g)', moles: 1 },
+      { species: 'O2', moles: 3 },
+    ],
+    products: [
+      { species: 'CO2', moles: 2 },
+      { species: 'H2O(g)', moles: 3 },
+    ],
+    kinetics: { type: 'arrhenius', A: 1e12, activationEnergy: 125500 },
+    kind: KIND_COMBUSTION,
+  },
+  {
+    id: BURN_PETROL,
+    reactants: [
+      { species: 'octane(g)', moles: 1 },
+      { species: 'O2', moles: 12.5 },
+    ],
+    products: [
+      { species: 'CO2', moles: 8 },
+      { species: 'H2O(g)', moles: 9 },
+    ],
+    kinetics: { type: 'arrhenius', A: 4e11, activationEnergy: 125500 },
+    kind: KIND_COMBUSTION,
+  },
+  {
+    id: BURN_DIESEL,
+    reactants: [
+      { species: 'diesel(g)', moles: 1 },
+      { species: 'O2', moles: 18.5 },
+    ],
+    products: [
+      { species: 'CO2', moles: 12 },
+      { species: 'H2O(g)', moles: 13 },
+    ],
+    kinetics: { type: 'arrhenius', A: 3e11, activationEnergy: 125500 },
+    kind: KIND_COMBUSTION,
+  },
+  {
+    id: BURN_KEROSENE,
+    reactants: [
+      { species: 'kerosene(g)', moles: 1 },
+      { species: 'O2', moles: 17.75 },
+    ],
+    products: [
+      { species: 'CO2', moles: 12 },
+      { species: 'H2O(g)', moles: 11.5 },
+    ],
+    kinetics: { type: 'arrhenius', A: 3e11, activationEnergy: 125500 },
+    kind: KIND_COMBUSTION,
+  },
+  {
+    /* Already a gas, so it has no vaporisation and no flash point — which is exactly why a leak is
+       dangerous at any temperature and a diesel spill is not. */
+    id: BURN_PROPANE,
+    reactants: [
+      { species: 'propane', moles: 1 },
+      { species: 'O2', moles: 5 },
+    ],
+    products: [
+      { species: 'CO2', moles: 3 },
+      { species: 'H2O(g)', moles: 4 },
+    ],
+    kinetics: { type: 'arrhenius', A: 8e11, activationEnergy: 125500 },
+    kind: KIND_COMBUSTION,
+  },
+  {
+    id: BURN_WAX,
+    reactants: [
+      { species: 'wax(g)', moles: 1 },
+      { species: 'O2', moles: 38 },
+    ],
+    products: [
+      { species: 'CO2', moles: 25 },
+      { species: 'H2O(g)', moles: 26 },
+    ],
+    kinetics: { type: 'arrhenius', A: 2e11, activationEnergy: 125500 },
+    kind: KIND_COMBUSTION,
+  },
+];
+
+/**
+ * A liquid fuel's `pilotedSurfaceK` is its **flash point** and `autoSurfaceK` its autoignition
+ * temperature, and the gap between them is enormous where it matters.
+ *
+ * Petrol flashes at −43 °C and autoignites at 280; diesel flashes at 52 °C and autoignites at 210.
+ * That is the whole difference between the two in a garage: petrol is above its flash point on the
+ * coldest day of the year and diesel is below it on the hottest, so one needs a spark it will
+ * certainly find and the other needs a spark it may not.
+ */
+export const FUEL: SubstanceLibrary = {
+  id: 'fuel',
+  species: VAPOURS,
+  reactions: REACTIONS,
+  substances: (species): readonly SubstanceThermal[] => [
+    {
+      id: 'ethanol',
+      composition: massFractions(species, { ethanol: 1 }),
+      density: 789,
+      conductivity: { k0: 0.17, k1: 0 },
+      shells: 2,
+      shape: SHAPE_SLAB,
+      emissivity: 0.95,
+      reactions: ['vaporise-ethanol'],
+      /* And its flame is nearly invisible, because there is no soot in it at all — one of the two
+         ends of `§8.4`'s sooting scale, and a genuine hazard in a real spirit fire. */
+      ignition: { pilotedSurfaceK: 286, autoSurfaceK: 636, criticalMassFlux: 0.001 },
+      appearance: {
+        albedo: [0.03, 0.04, 0.05],
+        charAlbedo: [0.03, 0.04, 0.05],
+        sootYield: 0.008,
+      },
+    },
+    {
+      id: 'petrol',
+      composition: massFractions(species, { octane: 1 }),
+      density: 745,
+      conductivity: { k0: 0.14, k1: 0 },
+      shells: 2,
+      shape: SHAPE_SLAB,
+      emissivity: 0.95,
+      reactions: ['vaporise-petrol'],
+      ignition: { pilotedSurfaceK: 230, autoSurfaceK: 553, criticalMassFlux: 0.001 },
+      appearance: {
+        albedo: [0.3, 0.26, 0.1],
+        charAlbedo: [0.3, 0.26, 0.1],
+        sootYield: 0.1,
+      },
+    },
+    {
+      id: 'diesel',
+      composition: massFractions(species, { diesel: 1 }),
+      density: 832,
+      conductivity: { k0: 0.13, k1: 0 },
+      shells: 2,
+      shape: SHAPE_SLAB,
+      emissivity: 0.95,
+      reactions: ['vaporise-diesel'],
+      ignition: { pilotedSurfaceK: 325, autoSurfaceK: 483, criticalMassFlux: 0.0012 },
+      appearance: {
+        albedo: [0.2, 0.17, 0.1],
+        charAlbedo: [0.2, 0.17, 0.1],
+        sootYield: 0.13,
+      },
+    },
+    {
+      id: 'kerosene',
+      composition: massFractions(species, { kerosene: 1 }),
+      density: 810,
+      conductivity: { k0: 0.13, k1: 0 },
+      shells: 2,
+      shape: SHAPE_SLAB,
+      emissivity: 0.95,
+      reactions: ['vaporise-kerosene'],
+      ignition: { pilotedSurfaceK: 311, autoSurfaceK: 493, criticalMassFlux: 0.0012 },
+      appearance: {
+        albedo: [0.24, 0.22, 0.16],
+        charAlbedo: [0.24, 0.22, 0.16],
+        sootYield: 0.12,
+      },
+    },
+    {
+      /* Solid, and it has to melt and then boil before anything burns. That is a candle. */
+      id: 'paraffin-wax',
+      composition: massFractions(species, { wax: 1 }),
+      density: 900,
+      conductivity: { k0: 0.25, k1: 0 },
+      shells: 3,
+      shape: SHAPE_CYLINDER,
+      emissivity: 0.93,
+      reactions: ['melt-wax', 'vaporise-wax'],
+      ignition: { pilotedSurfaceK: 472, autoSurfaceK: 573, criticalMassFlux: 0.002 },
+      appearance: {
+        albedo: [0.86, 0.85, 0.8],
+        charAlbedo: [0.1, 0.09, 0.08],
+        sootYield: 0.06,
+      },
+    },
+  ],
+};

package/src/library/library.ts

@@ -0,0 +1,62 @@
+/**
+ * What a substance family is, and how one is installed.
+ *
+ * **`§2` of the design applies the payload rule to *data*, which this engine has not had to do
+ * before.** A substance is about forty numbers, a composition and a reaction list; forty of them is
+ * a real payload and most games use ten. So each family is its own entry point, and a consumer who
+ * defines three substances of their own imports none of these and pays for none of them.
+ *
+ * **Substances are a function of the registry rather than constants.** A composition is mass
+ * fractions over species *indices*, and there are no indices until something is registered — so the
+ * only honest shape is a function called once, at init, with the registry that will hold them.
+ *
+ * **A library may register species of its own**, and two of them do. That is better than growing
+ * `species/standard.ts`: `tar` is meaningless outside a wood fire and molten wax outside a candle,
+ * so putting either in the standard table would charge every consumer in the engine for both.
+ */
+import type { SpeciesDefinition } from '../species/species.ts';
+import type { SpeciesRegistry } from '../species/registry.ts';
+import type { Reaction } from '../reaction/reaction.ts';
+import type { ReactionRegistry } from '../reaction/registry.ts';
+import type { SubstanceRegistry } from '../substance/registry.ts';
+import type { SubstanceThermal } from '../substance/substance.ts';
+
+export interface SubstanceLibrary {
+  readonly id: string;
+  /** Species this family needs that the standard table does not carry. Usually none. */
+  readonly species: readonly SpeciesDefinition[];
+  readonly reactions: readonly Reaction[];
+  substances(species: SpeciesRegistry): readonly SubstanceThermal[];
+}
+
+/**
+ * Species, then reactions, then substances — **skipping whatever is already registered**.
+ *
+ * The skipping is the whole reason this is not three loops of `register`. Gas-phase combustion
+ * belongs to every family that burns, and registering an id twice throws by design, so a consumer
+ * installing `organic` and `fuel` together would otherwise fail at init on the first reaction they
+ * share. Skipping also makes installing a family twice a no-op rather than a crash, which is what a
+ * consumer assembling a world out of several libraries will do by accident sooner or later.
+ *
+ * **It does not check that the existing registration matches.** Two libraries declaring different
+ * reactions under one id would silently take the first, and nothing here would say so — but every
+ * id in these libraries is defined in exactly one place, and a consumer who shadows one has said
+ * something deliberate. Refusing it would mean comparing stoichiometry and kinetics for equality,
+ * which is a real cost at init for a case the libraries themselves cannot produce.
+ */
+export function installLibrary(
+  library: SubstanceLibrary,
+  species: SpeciesRegistry,
+  reactions: ReactionRegistry,
+  substances: SubstanceRegistry,
+): void {
+  for (const definition of library.species) {
+    if (species.indexOf(definition.id) < 0) species.register(definition);
+  }
+  for (const reaction of library.reactions) {
+    if (reactions.indexOf(reaction.id) < 0) reactions.register(reaction);
+  }
+  for (const substance of library.substances(species)) {
+    if (substances.indexOf(substance.id) < 0) substances.define(substance);
+  }
+}