@driftengine/chemistry 3.61.0

package/dist/present/install.js

@@ -0,0 +1,157 @@
+/**
+ * `installChemistry` — three lines, and a consumer's oak is oak.
+ *
+ * **`§16` is honest about what "free" means and this file is where it lands.** Free of *authoring*:
+ * a consumer never writes a reaction, never tunes an ignition temperature, never writes a state
+ * machine for fire. Not free of *importing*: core does not depend on chemistry and a game with no
+ * fire in it pays zero bytes, which is `ARCHITECTURE.md` §5's payload rule and this track does not
+ * get an exception to it.
+ *
+ * So the work goes into making the wiring free, and this is it.
+ */
+import { ReactionRegistry } from '../reaction/registry.js';
+import { KIND_COMBUSTION, KIND_PHASE_CHANGE } from '../reaction/reaction.js';
+import { SpeciesRegistry } from '../species/registry.js';
+import { registerStandardSpecies } from '../species/standard.js';
+import { SubstanceRegistry } from '../substance/registry.js';
+import { ParcelStore } from '../parcel/store.js';
+import { AtmosphereField } from '../field/atmosphere.js';
+import { STANDARD_AIR, STANDARD_FIELD_SPECIES } from '../field/ambient.js';
+import { ChemistryWorld } from '../transport/world.js';
+import { installLibrary } from '../library/library.js';
+/**
+ * A world with the given families in it, and everything wired to everything else.
+ *
+ * **Every option after `libraries` removes a capability when omitted rather than breaking.** No
+ * ambient: standard air. No cell size: one metre. That is `§16`'s arrangement, and the reason none
+ * of them is required is that a consumer who has not decided yet should still get a fire.
+ *
+ * **The gas-phase reactions come from the libraries rather than from the caller.** A family knows
+ * what its own volatiles are, and a consumer who forgot to pass `burn-tar` would have a fire that
+ * made smoke and no flame — which is a silent wrong answer rather than an error.
+ */
+export function installChemistry(options) {
+    const species = new SpeciesRegistry();
+    registerStandardSpecies(species);
+    const reactions = new ReactionRegistry(species);
+    const substances = new SubstanceRegistry(species, reactions);
+    for (const library of options.libraries) {
+        installLibrary(library, species, reactions, substances);
+    }
+    /*
+     * Every combustion step any installed family declared, which is what a flame is made of — and the
+     * species those steps touch, which is what the air has to be able to carry.
+     *
+     * **Both are derived rather than asked for.** A consumer who installed `organic` and then forgot
+     * to name `burn-tar` would have a fire that made smoke and no flame, and one who named the
+     * reaction but not the `tar` species would be refused at init with a message about a field they
+     * never configured. Neither is a decision worth exposing.
+     */
+    const gasReactions = [];
+    const carried = new Set(STANDARD_FIELD_SPECIES);
+    for (let r = 0; r < reactions.count; r++) {
+        if (reactions.kindOf(r) !== KIND_COMBUSTION)
+            continue;
+        gasReactions.push(reactions.idOf(r));
+        for (const s of reactions.reactantSpecies(r))
+            carried.add(species.idOf(s));
+        for (const s of reactions.productSpecies(r))
+            carried.add(species.idOf(s));
+    }
+    /*
+     * **And every phase change whose reactants the air already holds, which is what condenses smoke.**
+     *
+     * Combustion alone left a hole: `library/organic` condenses tar to droplets below its dew point,
+     * which is a `KIND_PHASE_CHANGE` and is the only thing that happens to the volatiles off a
+     * *smouldering* surface — no flame over it, so nothing burns and nothing cracks. Without this the
+     * pale smoke a smoulder makes has no source and the tar drifts away invisible.
+     *
+     * **Derived by the same rule as the line above rather than declared**, and the rule is one
+     * sentence: a reaction the air can run is one whose inputs are already in the air. That admits
+     * `condense-tar`, because a combustion step above put `tar` in the set, and then `evaporate-tar`,
+     * because the first one put `tar(l)` there — which is why this is a fixpoint and not a pass. It
+     * declines `melt-ice` and `boil-water` and every `vaporise-*` in `library/fuel`, because a lump of
+     * ice and a puddle of diesel are not things the air holds, and the combustion steps burn the
+     * *vapours* rather than the liquids they come from. And it would admit `boil-water` the day
+     * something put liquid water into a cell, which is right: a droplet suspended in warm air really
+     * does evaporate.
+     *
+     * The alternative was a `gasReactions` list on `SubstanceLibrary`, which this file already argues
+     * against for combustion: a library author who forgot to add one would ship a fire whose smoke
+     * never whitened, and nothing would say so. The cost of deriving is that the set is a closure a
+     * consumer cannot read off their own library — so `gasReactions` is returned, and the demo panel
+     * prints it.
+     */
+    for (let grew = true; grew;) {
+        grew = false;
+        for (let r = 0; r < reactions.count; r++) {
+            if (reactions.kindOf(r) !== KIND_PHASE_CHANGE)
+                continue;
+            const id = reactions.idOf(r);
+            if (gasReactions.includes(id))
+                continue;
+            let inTheAir = true;
+            for (const s of reactions.reactantSpecies(r)) {
+                if (!carried.has(species.idOf(s)))
+                    inTheAir = false;
+            }
+            if (!inTheAir)
+                continue;
+            gasReactions.push(id);
+            for (const s of reactions.productSpecies(r))
+                carried.add(species.idOf(s));
+            grew = true;
+        }
+    }
+    const parcels = new ParcelStore(substances);
+    const air = new AtmosphereField(species, {
+        cellSize: options.cellSize ?? 1,
+        ambient: options.ambient ?? STANDARD_AIR,
+        maxChunks: options.maxChunks,
+        species: [...carried],
+        reactions,
+        reactionIds: gasReactions,
+    });
+    const world = new ChemistryWorld(parcels, air);
+    return {
+        species,
+        reactions,
+        substances,
+        parcels,
+        air,
+        world,
+        gasReactions,
+        match(names) {
+            const resolved = [];
+            const unmatched = [];
+            let matched = 0;
+            for (const name of names) {
+                const index = substances.indexOf(name);
+                resolved.push(index);
+                if (index >= 0)
+                    matched++;
+                else
+                    unmatched.push(name);
+            }
+            return { substances: resolved, matched, unmatched };
+        },
+    };
+}
+/**
+ * Sensible parcel numbers from a bounding box and a density.
+ *
+ * **`§16`'s third mechanism**: a consumer with meshes gets parcels without measuring anything, and a
+ * consumer who cares supplies real numbers instead. The area is all six faces, which is right for
+ * something in the open and generous for something lying on a hearth — and being generous is the
+ * safe direction, because it makes things heat slightly faster rather than mysteriously refusing to.
+ */
+export function parcelFromBounds(width, height, depth, density) {
+    const volume = width * height * depth;
+    const area = 2 * (width * height + height * depth + depth * width);
+    return {
+        mass: volume * density,
+        volume,
+        area,
+        thickness: area > 0 ? volume / area : 0,
+    };
+}

package/dist/present/smoke.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The field made visible, written into somebody else's particle arrays.
+ *
+ * **This module names no core type and imports nothing.** The target is described by what it must
+ * have, which is the `ragdollFromBones` arrangement: `@driftengine/core`'s `ParticleInstances`
+ * satisfies `SmokeTarget` exactly, and neither package knows the other exists. That matters more
+ * here than it did there, because this package imports **no** engine package at all and `present/`
+ * must not be the thing that breaks it.
+ */
+import type { AtmosphereField } from '../field/atmosphere.ts';
+/**
+ * Anything shaped like a pool of particles.
+ *
+ * Declared structurally, per the header. `spins` and `capacity` are core's and are not required
+ * here — a target that has them is fine, and one that does not still works, which is what
+ * structural means.
+ */
+export interface SmokeTarget {
+    positions: Float32Array;
+    velocities: Float32Array;
+    colors: Float32Array;
+    alphas: Float32Array;
+    sizes: Float32Array;
+    ages: Float32Array;
+    seeds: Float32Array;
+    count: number;
+    readonly capacity: number;
+}
+export interface SmokeOptions {
+    /** kg of soot plus aerosol in a cell below which nothing is drawn. */
+    readonly threshold: number;
+    /** Metres across, which is also the path length opacity is computed over. */
+    readonly size: number;
+    /** The horizontal component a particle inherits, m/s. The vertical is the field's own. */
+    readonly wind: number;
+}
+/**
+ * The colour of a mixture of soot and aerosol, by mass.
+ *
+ * **Nothing chose it.** Soot is near-black at an albedo around 0.03 and water aerosol is near-white,
+ * so the ratio *is* the colour: a green log steams white, a rich fire smokes black, and a fire doing
+ * both does both in the right places. Grey where they are equal, which is what wood smoke is.
+ *
+ * Writes into `out`, allocates nothing.
+ */
+export declare function smokeColour(soot: number, aerosol: number, out: Float32Array): void;
+/**
+ * Write one particle per smoky cell in a box, and return how many were written.
+ *
+ * The box is `cells` cells on a side from `(x, y, z)` in cell coordinates, which is what a consumer
+ * has: they know where their fire is, and scanning the whole live set to find it would cost the same
+ * whether there was one fire or a hundred.
+ *
+ * **Every value is a reading rather than a parameter.** Position is the cell centre, velocity is the
+ * caller's wind plus the field's own buoyant rise — the same function transport uses, so a particle
+ * goes up at the speed the gas carrying it goes up — colour is the soot-to-aerosol ratio, and
+ * opacity is extinction over the particle's own path length. `size` and `threshold` are the two
+ * things a consumer genuinely decides.
+ *
+ * `count` is set rather than added to: a pool is refilled each frame, which is what makes this
+ * allocation-free.
+ */
+export declare function emitSmoke(field: AtmosphereField, x: number, y: number, z: number, cells: number, out: SmokeTarget, options: SmokeOptions): number;

package/dist/present/smoke.js

@@ -0,0 +1,85 @@
+/** Linear albedo of soot, and of condensed water aerosol. `§17`. */
+const SOOT_ALBEDO = 0.03;
+const AEROSOL_ALBEDO = 0.92;
+/** The extinction the field's own visibility is derived from, m²/kg. */
+const SOOT_EXTINCTION = 8700;
+/**
+ * The colour of a mixture of soot and aerosol, by mass.
+ *
+ * **Nothing chose it.** Soot is near-black at an albedo around 0.03 and water aerosol is near-white,
+ * so the ratio *is* the colour: a green log steams white, a rich fire smokes black, and a fire doing
+ * both does both in the right places. Grey where they are equal, which is what wood smoke is.
+ *
+ * Writes into `out`, allocates nothing.
+ */
+export function smokeColour(soot, aerosol, out) {
+    const total = soot + aerosol;
+    const albedo = total > 0 ? (soot * SOOT_ALBEDO + aerosol * AEROSOL_ALBEDO) / total : AEROSOL_ALBEDO;
+    out[0] = albedo;
+    out[1] = albedo;
+    out[2] = albedo;
+}
+/* Scratch, module-level and reused, because this runs per cell per frame. */
+const colour = new Float32Array(3);
+/**
+ * Write one particle per smoky cell in a box, and return how many were written.
+ *
+ * The box is `cells` cells on a side from `(x, y, z)` in cell coordinates, which is what a consumer
+ * has: they know where their fire is, and scanning the whole live set to find it would cost the same
+ * whether there was one fire or a hundred.
+ *
+ * **Every value is a reading rather than a parameter.** Position is the cell centre, velocity is the
+ * caller's wind plus the field's own buoyant rise — the same function transport uses, so a particle
+ * goes up at the speed the gas carrying it goes up — colour is the soot-to-aerosol ratio, and
+ * opacity is extinction over the particle's own path length. `size` and `threshold` are the two
+ * things a consumer genuinely decides.
+ *
+ * `count` is set rather than added to: a pool is refilled each frame, which is what makes this
+ * allocation-free.
+ */
+export function emitSmoke(field, x, y, z, cells, out, options) {
+    let written = 0;
+    const limit = out.alphas.length < out.capacity ? out.alphas.length : out.capacity;
+    for (let ix = 0; ix < cells && written < limit; ix++) {
+        for (let iy = 0; iy < cells && written < limit; iy++) {
+            for (let iz = 0; iz < cells && written < limit; iz++) {
+                const cx = x + ix + 0.5;
+                const cy = y + iy + 0.5;
+                const cz = z + iz + 0.5;
+                const soot = field.sootAt(cx, cy, cz);
+                const aerosol = field.aerosolAt(cx, cy, cz);
+                if (soot + aerosol < options.threshold)
+                    continue;
+                const at = written * 3;
+                out.positions[at] = cx;
+                out.positions[at + 1] = cy;
+                out.positions[at + 2] = cz;
+                out.velocities[at] = options.wind;
+                out.velocities[at + 1] = field.riseAt(cx, cy, cz);
+                out.velocities[at + 2] = 0;
+                smokeColour(soot, aerosol, colour);
+                out.colors[at] = colour[0];
+                out.colors[at + 1] = colour[1];
+                out.colors[at + 2] = colour[2];
+                /*
+                 * Opacity from extinction over the particle's own size, rather than from a curve.
+                 *
+                 * `1 − exp(−σd)` is the honest form and `exp` may not run here, so this is the first two
+                 * terms of it arranged as `σd / (1 + σd)` — which agrees to within a few percent over the
+                 * range that matters and saturates at one the way the exponential does, instead of
+                 * overshooting the way a truncated series would.
+                 */
+                const extinction = field.smokeDensityAt(cx, cy, cz) * options.size;
+                out.alphas[written] = extinction / (1 + extinction);
+                out.sizes[written] = options.size;
+                out.ages[written] = 0;
+                /* Per-particle randomness with no entropy: the cell's own index, so neighbours differ and
+                   two runs agree. `§15`'s determinism rule reaches presentation too. */
+                out.seeds[written] = (((ix * 73856093) ^ (iy * 19349663) ^ (iz * 83492791)) % 1024) / 1024;
+                written++;
+            }
+        }
+    }
+    out.count = written;
+    return written;
+}

package/dist/present/surface.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What a burning thing looks like, written into somebody else's per-instance arrays.
+ *
+ * **Structural, like `smoke.ts`, and for the same reason**: this package imports no engine package
+ * and `present/` must not be the thing that breaks it. A target is described by what it must have.
+ *
+ * Four of `§17`'s six mappings live here — char, glow, wetness and shrinkage — because all four are
+ * per-parcel and per-frame and reading a parcel four times would be four passes over the same
+ * columns. Smoke and flame are per-cell and per-fire, which is why they are elsewhere.
+ */
+import type { ParcelStore } from '../parcel/store.ts';
+/** Anything shaped like a block of per-instance material overrides. */
+export interface SurfaceTarget {
+    /** Linear RGB, three floats each. */
+    albedos: Float32Array;
+    /** Linear RGB, three floats each, already multiplied by intensity. */
+    emissives: Float32Array;
+    /** 0 to 1, where wet is smoother. */
+    roughness: Float32Array;
+    /** A uniform scale, 1 at the size it was spawned. */
+    scales: Float32Array;
+    count: number;
+}
+/**
+ * Write one entry per parcel, in the order given.
+ *
+ * **Every value is a reading.** Albedo lerps from the substance's own toward its own char colour by
+ * char fraction; the emissive is Planck at the surface temperature times Stefan-Boltzmann;
+ * roughness is the surface water film; scale is the cube root of what is left of the volume.
+ *
+ * **A substance with no `appearance` gets no albedo and no roughness written**, and the entry is
+ * left exactly as the caller had it. Quietly recolouring a material the consumer described would be
+ * the engine overwriting an artist. Scale and emissive are still written, because both are physics
+ * rather than art.
+ *
+ * **`AGENTS.md`'s standing trap applies to `emissives`.** Emissive in this engine is gated on
+ * `nightFactor`, so embers written here look right at dusk and dead at noon. A consumer who wants
+ * them visible in daylight raises that gate; nothing in this function can do it for them.
+ */
+export declare function writeSurface(parcels: ParcelStore, handles: readonly number[], out: SurfaceTarget): number;

package/dist/present/surface.js

@@ -0,0 +1,76 @@
+import { GLOW_MIN_TEMPERATURE, blackbodyRGB, glowIntensity } from './blackbody.js';
+/**
+ * Roughness a dry surface sits at, and how far a soaked one is pulled toward a mirror.
+ *
+ * `WET_FILM_FULL` is kilograms of water per square metre at which the film is continuous — about a
+ * tenth of a millimetre of water, which is what a surface holds before it starts running off.
+ */
+const DRY_ROUGHNESS = 0.85;
+const WET_ROUGHNESS = 0.15;
+const WET_FILM_FULL = 0.1;
+/* Scratch, module-level and reused: this runs per parcel per frame. */
+const glow = new Float32Array(3);
+/**
+ * Write one entry per parcel, in the order given.
+ *
+ * **Every value is a reading.** Albedo lerps from the substance's own toward its own char colour by
+ * char fraction; the emissive is Planck at the surface temperature times Stefan-Boltzmann;
+ * roughness is the surface water film; scale is the cube root of what is left of the volume.
+ *
+ * **A substance with no `appearance` gets no albedo and no roughness written**, and the entry is
+ * left exactly as the caller had it. Quietly recolouring a material the consumer described would be
+ * the engine overwriting an artist. Scale and emissive are still written, because both are physics
+ * rather than art.
+ *
+ * **`AGENTS.md`'s standing trap applies to `emissives`.** Emissive in this engine is gated on
+ * `nightFactor`, so embers written here look right at dusk and dead at noon. A consumer who wants
+ * them visible in daylight raises that gate; nothing in this function can do it for them.
+ */
+export function writeSurface(parcels, handles, out) {
+    let written = 0;
+    for (let i = 0; i < handles.length; i++) {
+        const parcel = handles[i];
+        if (!parcels.alive(parcel))
+            continue;
+        const at = written * 3;
+        const appearance = parcels.appearanceOf(parcel);
+        if (appearance !== null) {
+            const char = parcels.charFractionOf(parcel);
+            const solid = char > 1 ? 1 : char;
+            for (let c = 0; c < 3; c++) {
+                out.albedos[at + c] =
+                    appearance.albedo[c] * (1 - solid) +
+                        appearance.charAlbedo[c] * solid;
+            }
+            const film = parcels.wetnessOf(parcel) / WET_FILM_FULL;
+            const wet = film > 1 ? 1 : film;
+            out.roughness[written] = DRY_ROUGHNESS * (1 - wet) + WET_ROUGHNESS * wet;
+        }
+        const surface = parcels.surfaceTemperatureOf(parcel);
+        if (surface >= GLOW_MIN_TEMPERATURE) {
+            blackbodyRGB(surface, glow);
+            const intensity = glowIntensity(surface);
+            for (let c = 0; c < 3; c++)
+                out.emissives[at + c] = glow[c] * intensity;
+        }
+        else {
+            out.emissives[at] = 0;
+            out.emissives[at + 1] = 0;
+            out.emissives[at + 2] = 0;
+        }
+        /*
+         * The **cube root** of the volume ratio, because a scale is linear and a volume is not. Half the
+         * mass is 0.794 of the size, which is a log visibly smaller and not half a log.
+         *
+         * `Math.cbrt`'s result is not pinned down by ECMAScript, which is why it is kept off the
+         * simulation path entirely — `shellGeometry` says so. Here it is presentation, which does not
+         * feed back into the state, so a last-bit difference between platforms is a pixel rather than a
+         * divergence.
+         */
+        // determinism: build-time — presentation: a parcel's drawn scale, not its state
+        out.scales[written] = Math.cbrt(parcels.volumeShareOf(parcel));
+        written++;
+    }
+    out.count = written;
+    return written;
+}

package/dist/reaction/localise.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Packing a reaction network against one owner's species set.
+ *
+ * Both a substance and the atmosphere run reactions, and both need the same thing: the network
+ * rewritten so its species are **local slots** into the few species that owner actually holds,
+ * rather than indices into all sixty-eight. A shell's composition is then a dense run and the
+ * solver's inner loop is a walk rather than a lookup.
+ *
+ * One implementation, used by both, because two would be two things to keep in step — and the
+ * second would be discovered wrong on the day a reaction behaved differently in a cell than in the
+ * shell beside it.
+ */
+import type { SpeciesRegistry } from '../species/registry.ts';
+import type { ReactionRegistry } from './registry.ts';
+import { type SubstanceReactions } from './solver.ts';
+export declare function localiseReactions(species: SpeciesRegistry, reactions: ReactionRegistry | undefined, ids: readonly string[], set: Int32Array, owner: string): SubstanceReactions;

package/dist/reaction/localise.js

@@ -0,0 +1,95 @@
+import { MAX_SUBSTANCE_REACTIONS } from './solver.js';
+export function localiseReactions(species, reactions, ids, set, owner) {
+    if (ids.length > MAX_SUBSTANCE_REACTIONS) {
+        throw new Error(`${owner} declares ${ids.length} reactions; the limit is ${MAX_SUBSTANCE_REACTIONS}`);
+    }
+    const local = new Int32Array(species.count).fill(-1);
+    for (let i = 0; i < set.length; i++)
+        local[set[i]] = i;
+    const molarMass = new Float64Array(set.length);
+    const cpA = new Float64Array(set.length);
+    const cpB = new Float64Array(set.length);
+    for (let i = 0; i < set.length; i++) {
+        const global = set[i];
+        molarMass[i] = species.molarMass(global);
+        /* `cp(T) = cpA + cpB·(T − 298.15)`, recovered from the registry's own linear model. */
+        cpA[i] = species.heatCapacityOf(global, 298.15);
+        cpB[i] = species.heatCapacityOf(global, 299.15) - cpA[i];
+    }
+    const indices = [];
+    for (const id of ids) {
+        if (reactions === undefined) {
+            throw new Error(`${owner} declares reaction "${id}", and no reaction registry was supplied`);
+        }
+        const at = reactions.indexOf(id);
+        if (at < 0)
+            throw new Error(`${owner} declares reaction "${id}", which is not registered`);
+        indices.push(at);
+    }
+    const reactantStart = new Int32Array(indices.length + 1);
+    const productStart = new Int32Array(indices.length + 1);
+    const reactantLocal = [];
+    const reactantMoles = [];
+    const productLocal = [];
+    const productMoles = [];
+    const enthalpy = new Float64Array(indices.length);
+    const minTemperature = new Float64Array(indices.length);
+    const maxTemperature = new Float64Array(indices.length);
+    const gateWidth = new Float64Array(indices.length);
+    const transportLimit = new Float64Array(indices.length);
+    const table = [];
+    const slot = (global, id) => {
+        const at = local[global];
+        if (at < 0) {
+            throw new Error(`${owner} declares reaction "${id}", which touches "${species.idOf(global)}" — ` +
+                'a species it does not carry');
+        }
+        return at;
+    };
+    for (let r = 0; r < indices.length; r++) {
+        const registry = reactions;
+        const global = indices[r];
+        const id = ids[r];
+        reactantStart[r] = reactantLocal.length;
+        const rs = registry.reactantSpecies(global);
+        const rm = registry.reactantMoles(global);
+        for (let i = 0; i < rs.length; i++) {
+            reactantLocal.push(slot(rs[i], id));
+            reactantMoles.push(rm[i]);
+        }
+        productStart[r] = productLocal.length;
+        const ps = registry.productSpecies(global);
+        const pm = registry.productMoles(global);
+        for (let i = 0; i < ps.length; i++) {
+            productLocal.push(slot(ps[i], id));
+            productMoles.push(pm[i]);
+        }
+        enthalpy[r] = registry.enthalpyOf(global);
+        minTemperature[r] = registry.minTemperatureOf(global);
+        maxTemperature[r] = registry.maxTemperatureOf(global);
+        gateWidth[r] = registry.gateWidthOf(global);
+        transportLimit[r] = registry.transportLimitOf(global);
+        table.push(registry.rateTableOrNull(global));
+    }
+    reactantStart[indices.length] = reactantLocal.length;
+    productStart[indices.length] = productLocal.length;
+    return {
+        count: indices.length,
+        speciesCount: set.length,
+        molarMass,
+        cpA,
+        cpB,
+        minTemperature,
+        maxTemperature,
+        gateWidth,
+        transportLimit,
+        reactantStart,
+        reactantLocal: Int32Array.from(reactantLocal),
+        reactantMoles: Float64Array.from(reactantMoles),
+        productStart,
+        productLocal: Int32Array.from(productLocal),
+        productMoles: Float64Array.from(productMoles),
+        enthalpy,
+        table,
+    };
+}

package/dist/reaction/rates.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Reaction rates as tables, because `exp` may not run on a tick.
+ *
+ * **The reasoning is `§7`'s and it is a hard rule rather than a preference.** `AGENTS.md` already
+ * made this call once, for the tyre curve: Pacejka is `sin(atan(…))` and both were banned from the
+ * tick, so the curve became a table and the API came out better than the closed form. The same
+ * applies here with more force. `exp(−Ea/RT)` would be evaluated once per reaction per shell per
+ * parcel per substep — a hundred times the tyre call count — and it varies by twenty orders of
+ * magnitude over the range of interest, which makes it the single easiest place in the engine to
+ * lose determinism to one platform's `exp` differing in the last bit.
+ *
+ * **Knots are uniform in `1/T`, and that is a departure from the design worth recording.** `§7`
+ * says "512 logarithmically-spaced knots, log-`k` stored so the interpolation is in the variable
+ * that is nearly linear" — and `ln k = ln A + n·ln T − Ea/(R·T)` is not nearly linear in `ln T`, it
+ * is *exactly* linear in `1/T` for the `n = 0` form that almost every rate in the library uses. So
+ * the knots are uniform in `1/T`, which puts the interpolation error where the design wanted it.
+ *
+ * **But `k` is stored rather than `ln k`, and that is the other half of the correction.** The
+ * design's own sentence would need an `exp` at every lookup, which is the thing the paragraph above
+ * it forbids — the two halves of `§7` contradict each other, and this is the resolution. Storing
+ * `k` and interpolating linearly costs a real interpolation error, bounded by about `δ²/8` where
+ * `δ` is the change in `ln k` across one knot. At 1,024 knots over 200–3500 K that is under half a
+ * percent for every activation energy in the library, **which is comfortably inside the uncertainty
+ * in the activation energies themselves** — literature values for cellulose pyrolysis differ by
+ * several percent between studies. `rates.test.ts` measures it rather than trusting this paragraph.
+ */
+/** J/(mol·K). */
+export declare const GAS_CONSTANT = 8.314462618;
+export interface RateTable {
+    readonly minTemperature: number;
+    readonly maxTemperature: number;
+    /** `1 / maxTemperature`: the low end of the knot axis. */
+    readonly inverseMin: number;
+    /** `1 / minTemperature`: the high end of it. */
+    readonly inverseMax: number;
+    readonly knots: number;
+    /** Rate at each knot, ascending in `1/T` — so descending in temperature. */
+    readonly rate: Float64Array;
+}
+/** `k(T) = A · T^n · exp(−Ea / R·T)`, sampled once so the tick never evaluates it. */
+export declare function tabulateArrhenius(A: number, activationEnergy: number, n?: number, min?: number, max?: number, knots?: number): RateTable;
+/**
+ * The peaked curve an enzyme-catalysed rate actually follows, normalised to one at the optimum.
+ *
+ * Zero at both cardinal ends, one at `optimum`, and **asymmetric in the right direction**: a slow
+ * climb and a sharp fall, because an enzyme denatures far faster than it warms up. Modelling decay
+ * or fermentation with Arrhenius instead gives compost that gets hotter forever, which is the most
+ * common mistake in this area and is refused here structurally rather than by remembering.
+ */
+export declare function cardinalRate(temperature: number, min: number, optimum: number, max: number): number;
+/** A cardinal curve scaled to a peak rate, tabulated the same way an Arrhenius one is. */
+export declare function tabulateCardinal(peak: number, min: number, optimum: number, max: number, low?: number, high?: number, knots?: number): RateTable;
+/**
+ * The rate at a temperature.
+ *
+ * Two multiplications, a floor and a lerp. Clamped at both ends rather than extrapolated: linearly
+ * extrapolating an exponential is how a rate table produces a number with nothing behind it.
+ */
+export declare function rateAt(table: RateTable, temperature: number): number;