A stock vector, keyed by node id. Plain JSON: this is what @latticekit/persist writes.

The mutable form. Every hot-path function writes into one of these instead of allocating.

A per-edge multiplier, evaluated once per buildFlow and held constant across the integration that follows.

This is where a rate that is not linear stops being a problem. Because the factor is sampled once and frozen, the expression inside it may be anything at all — a square root, a threshold, a milestone table, a capacity share, a curve read off a design spreadsheet. The constraint sim actually imposes is not linear, it is piecewise constant in time, and every one of those is constant between commits. The milestone mechanic ("every tenth press doubles what all of them make") is this, in one line: scale: () => milestoneMultiplier(game.pressesBought, MILESTONES); a prestige bonus is scale: () => Math.sqrt(game.prestige). Neither is a workaround, and neither costs the closed form anything.

Key it on a quantity that only changes when the player acts. It receives the stock vector at the anchor because that is often where the count lives, and that is also the trap: keying a milestone on an effective count that the flow itself produces puts a rate discontinuity inside an integral, and the same save then answers differently at 10 Hz than it does after one fourteen-hour catch-up. Purchased counts change only at actions. Effective counts change continuously. Use the first.

A source edge's scale is evaluated with the stock vector exactly like any other, which is usually what you want: a headline rate is most often a function of something the player bought.

One production edge: d(to)/dt += rate × stock(from), or — with no from — d(to)/dt += rate.

Non-consuming. The edge adds to to and subtracts nothing from from; a consuming edge would put a negative term on the diagonal, A would stop being nilpotent, and the closed form would stop terminating. A linear drain — lamps burning oil at a fixed rate per lamp — is not that, and is fully supported: it is a forward edge with a negative per. A flat standing charge is a source with a negative per.

Everything a game declares about its economy. Structure only: no balance, no time, no state.

Getting nodes wrong is a save-compatibility bug rather than a maths bug, which is why it is documented at the field rather than here.

A validated edge, in the package's own order.

The difference from EdgeSpec is slot and the ordering of the array it lives in: a game's spec file is text a designer reorders freely, and float addition is not associative, so the accumulation order has to be fixed here or a cosmetic diff moves the last bit of every stock in the game.

A validated, frozen production graph. Build it once at load; it holds no mutable state and two saves may share one.

Every guarantee the rest of the package makes rests on the two invariants this object carries: the edges point strictly forward through Economy.order, and depth bounds the matrix powers. Construct one only through defineEconomy — a hand-built object literal that satisfies the type can still violate both, and the integrator will not terminate.

Validate a spec and compute its evaluation order.

The order is derived by Kahn's algorithm and therefore proven, not asserted against a hand-written array the way the source game did it. A kit cannot ask a game author to keep a topological ordering correct by hand across fourteen resources and two content updates; it can compute one, and refuse the graphs that do not have one.

Ties in Kahn — two nodes ready at the same moment — are broken by declaration order, per the Lattice ordering rule. There is no comparator parameter, and there is no case in which the order depends on how the game happened to sort its edge list.

Validation uses core's guard validators, which return the value rather than take a boolean — so every message can name the offending node instead of reporting that something, somewhere, was false.

This is the function every game calls first, and the one most likely to be called wrongly, so its diagnostics carry more weight than the rest of the package's put together. Two rules are held to throughout: the kind of a value is checked before anything is inferred from it, and a message that could send the reader to either of two places names both.

A fresh, fully-populated, all-zero vector, keyed in storage order.

Every key is present and every value is a number, so the object's hidden class never changes under the integrator — a vector that grows a key on the first frame a resource is unlocked deoptimises every call site that has ever seen it. The key order matters for a second reason: it is the order JSON.stringify writes, so two saves of the same economy produce byte- comparable text.

The degree of node's trajectory in t: the longest path into it, so 0 is constant, 1 is linear and 2 is quadratic.

Exported because it is the precondition of an exact depletion solve: degree 1 and 2 are algebraic, and a game is entitled to know at design time whether the instant it wants to report is available in closed form or found by bisection. A resource drained by a fixed set of consumers is degree 1, which is most idle games' everything.

A source counts as one edge, so a node fed only by a source is degree 1 — a constant inflow makes a stock linear in time, and solveCrossing answers it with one divide.

The evaluated rate of every edge, plus the integrator's workspace.

One Flow per simulated world; see the module header for what sharing one costs. Treat everything but rates as opaque — the remaining fields are the integrator's and the root finder's scratch, they are sized against one particular Economy, and writing to them corrupts the next integration rather than the current one, which is the hardest kind of bug to trace back.

Allocate the workspace for one simulated world.

Call it once per world at load, next to defineEconomy's result, and keep it. It is the only allocation in the per-frame path of this package, and it happens before the first frame.

The ratios in force, one per declared gate. 1 is healthy; 0 stops the tagged edges.

For an economy with no gates.

Frozen, and a single shared instance: an economy without gates reads nothing out of it, so there is nothing to allocate per frame and nothing a caller could usefully put in.

Fold per × scale(stocks) × gateRatio into out.rates.

Cheap and allocation-free: one pass over tens of edges. Call it whenever anything that feeds a rate has moved — a purchase, a milestone, nightfall, a brownout. Forgetting to call it after a gate reading changes is the bug where the sun goes down and the oil does not start burning until the player's next click.

The multiplication order is fixed here — per, then scale, then the gate, and the identity factors are skipped rather than multiplied — so a gate ratio of r is bit-identical to the same graph with that edge's per pre-multiplied by r and no gate at all. A gate is exactly a rate multiplier and nothing subtler.

Tier A.

Integrate the whole vector forward by seconds, exactly, in one step.

Evaluates x(t) = Σ_k A^k x₀ tᵏ/k!, which terminates after eco.depth terms because A is nilpotent. Uses only + − × ÷: Tier A, bit-identical across engines given the same rates, and therefore safe to persist.

Composes exactly the way the underlying flow map does: integrating t₁ + t₂ once and integrating t₁ then t₂ agree in exact arithmetic and differ only by accumulated double rounding — about 1e-13 relative, asserted at 1e-9. That identity is what makes one fourteen- hour catch-up and fifty thousand one-second steps the same code path, and it is the reason there is no clamp anywhere in this function: a clamp is a nonlinearity, the result would stop being the integral of anything, and the discrepancy would depend on how often you called it. Solve for the crossing instead and put a boundary there.

dx/dt at this instant — what a HUD prints as "per second".

This is the derivative now and nothing else. Multiplying it by elapsed time is the classic wrong answer: production arriving during the next minute makes the real accrual super-linear, so the number a player is shown and the number they get disagree — in the player's disfavour, by more the better they are doing. To answer "how much in the next minute", integrate 60 and subtract.

Tier A, allocation-free, and safe against out aliasing stocks.

A stock vector and the instant it is true at. This is the whole of sim's state, and it is a value — JSON-round-trippable as-is, which is what @latticekit/persist writes.

atMs is an epoch timestamp and nothing else will do. Not loop.time, not a duration accumulated on the fixed step, not a monotonic reading: those have no calendar, run at roughly quarter speed in a hidden tab, and compare against a different zero after a reload. core brands EpochMillis precisely so that substitution is a compile error.

Validate a stock vector, returning it. guard-shaped, for the same reason core's validators are: a boolean has already thrown away the node that was wrong.

Call it on anything that came out of JSON.parse. A null where a number should be (an Infinity that made a round trip) and a NaN (which JSON.stringify also writes as null) are both caught here, at the one boundary where the value can still be blamed on the save rather than on the arithmetic.

A stock at Infinity means the economy has no answer, not that it has a very large one. It cannot be rendered, compared or spent, and it becomes a NaN downstream on the first 0 × ∞, which poisons every comparison in the game. Growth here is polynomial in elapsed time, so no single absence can carry a sane balance to 1.8e308; what can is compounding across sessions in a graph with no sink, which is exponential in session count. A throw from here is therefore a balance report, and it is designed to arrive at persist's "corrupt save → fresh, with a reported reason" path rather than at a player.

(atMs − ledger.atMs) / 1000, clamped at zero. The one place the ms→s conversion lives.

Clamped rather than absolute: laptop suspends, NTP corrections and a user changing their system date all produce an atMs behind the anchor, and Math.abs of that would run the economy forwards for time that did not pass. Zero, never negative.

Integrate to an instant without committing, into a caller-owned vector.

This is what a HUD calls every frame. It changes nothing, allocates nothing, and always integrates from the same anchor — so the answer is one expression evaluated at a later t, not an accumulation. Folding a per-frame projection back into the anchor is arithmetically fine and reproducibility poison: the state then depends on how many frames the player's laptop managed, which is the end of replay from a seed and an input log.

Deliberately does not check the result for finiteness. This is per-frame, and a non-finite out is garbage on screen for one frame, which is visible and harmless. The check belongs at the boundary between a number and a durable number — see advance.

Move the anchor, crediting creditedSeconds of production.

Two parameters, deliberately: the anchor always lands on atMs, and the production credited for getting there is whatever the caller says. Live play passes elapsedSeconds(...). An absence with a schedule uses advanceOver instead, which is the only function in this package permitted to apply a warp, because distributing one across phases is the thing you must not do by hand.

An atMs earlier than the anchor returns the ledger unchanged — it neither credits nor moves the anchor backwards, because an anchor that can be walked back is an interval that can be credited twice. Correcting a bad clock is reanchor, deliberately a different call.

Allocates one Ledger and one vector. It is a boundary call — an action, a save, a hydrate — not a per-frame one.

Move the anchor without crediting anything, in either direction.

The clock-correction tool, and the only function here that may move an anchor backwards. advance deliberately refuses to.

It exists because of the forward clock jump. A phone whose date is a year ahead hands the game a gap of 31.5 million seconds; the credit for that is capped by the offline curve's flat branch, but the anchor is not — it lands a year in the future, and when the clock is corrected every subsequent read sees time running backwards and credits zero. The economy then freezes for a year, with no error and a save that looks fine. That is the more damaging half of a forward jump and no cap on the credit prevents it.

So: a game that detects atMs < ledger.atMs by more than a plausible drift — a few seconds of NTP correction — calls this, keeps its stocks, forfeits nothing it had earned, and is running again on the next frame. Only the game knows its own session cadence, so only the game can set that threshold.

Uncapped for uncappedSeconds, softcapped at exponent, flat after flatAfterSeconds.

The shipping numbers in the game this kit came from: 3 h, 0.6, 24 h. Every field is a balance decision, and a balance pass is a data diff — so a wrong number arrives as data, and each is validated where it is read rather than three hours into a run.

Credited seconds for a single contiguous absence.

Apply it once per return, over the one gap between the ledger's anchor and now — see the module header for why it does not compose, and advanceOver for the only correct way to spread it across a schedule.

The result is clamped at the elapsed time it was given, so W(T) ≤ T holds to the bit rather than to within a rounding error near the knot. Math.min is exactly specified, so the clamp costs nothing in determinism: a dyadic exponent stays Tier A through it.

@tier B in general — a fractional power. Tier A when exponent is a dyadic rational with denominator ≤ 64, which is computed as a Math.sqrt chain rather than a pow.

The most any absence can ever be worth. Derived from the curve, never restated.

What a "you have banked the maximum" HUD line reads, and the number a reviewer should compare against a game's own plausibility threshold for a bad device clock: about 37.6 ks — 10.4 hours — at 3 h / 0.6 / 24 h.

W⁻¹ — the real elapsed time at which creditedSeconds of credit had accrued.

The map back from the physics to the calendar, and the reason a game can say "the lamps went out at 3:41 into the second night" rather than "at 1:52 of credited time, which is not a thing the player experienced". Under a warp the two clocks differ by a factor that grows with the absence, so a toast built from the credited number is confidently wrong about the player's own evening.

Closed form: the identity below U, and U·(c/U)^(1/e) above it. Tier A when 1/e is a whole number or a dyadic rational — e = 0.5 gives 1/e = 2, one multiply — and Tier B otherwise, including for e = 0.625, whose reciprocal 1.6 is not dyadic. The forward direction and the inverse therefore do not always share a tier, which is worth knowing before a game hashes either.

dW/dt — "the next second away is worth this much of a second". A read for the UI; the integrator never needs it.

Reported as the right derivative at both knots, because what a player wants to know is what the next second pays: it steps 1 → exponent at U, decays, and is 0 from F onwards. W is continuous there and w is not, which is the honest thing to show on a meter — a value interpolated across the kink would tell the player the softcap is gentler than it is.

One piece of a piecewise-constant schedule.

An absence, and the schedule that ran during it.

The coordinate system is real seconds from the start of the absence. fromSeconds says where the ledger's anchor currently sits in it and spanSeconds says where this call stops; the phases are absolute in the same frame and never need re-basing.

Where a crossing landed, in both clocks.

Advance across a piecewise-constant schedule, applying the warp once across the whole span and distributing it across the phases by evaluation at their boundaries.

This takes a curve rather than a number — the opposite of advance, and the asymmetry is the point. With one phase there is nothing to distribute and the caller may as well warp the scalar itself. With a schedule, distributing the warp by hand is exactly the thing that goes wrong: restarting W at each phase pays a player for K absences instead of one, it is invisible for short gaps because W is the identity below U, and the error grows without bound with the length of the absence.

Cost is O(visited phases × edges × depth) — semantic boundaries, not fixed steps. Doubling the length of the absence past the horizon does not change it at all: with a curve, the walk stops at the first phase beginning at or after curve.flatAfterSeconds, because every later one credits exactly zero. That makes the horizon a hard bound on work as well as on reward, so a phase array generated from a bad device clock cannot cost anything either.

An atMs earlier than the anchor returns the ledger unchanged, for the same reason advance does. The anchor otherwise lands on atMs even when nothing was credited — a fully consumed absence still happened.

Leaves flow holding the last visited phase's rates. Rebuild it before the next live frame.

The same solve as solveCrossing, across a whole schedule: walk the phases, integrate each exactly, and solve inside the first one whose interior contains the crossing.

The two clocks in Crossing are why this exists rather than being a loop in game code. The physics happens in credited time; the sentence the player reads is in real time, and the map between them is offlineElapsed evaluated at the phase's own offset. Getting that backwards produces a toast that is confidently wrong about when the lights went out — by a factor that grows the longer the player was away.

Pass the same plan you will pass to advanceOver, including the same fromSeconds. The two functions walk identically, so the crossing this reports is exactly the instant that one will integrate to.

Leaves flow holding the rates of the phase the crossing was found in — which is the flow the caller wants anyway, since the next thing it does is commit at that instant.

Allocates one Crossing and two stock vectors. A hydrate-boundary call.

The first instant within [0, horizonSeconds] at which node reaches level, or Infinity if it does not.

level is usually 0. Crossings in either direction are found; the caller knows which side it started on. If node is already at level the answer is 0 — a stock sitting at zero has already run out, and reporting anything else would make the guttering loop skip a lamp.

The rates it reads are whatever buildFlow last put in flow, so a crossing is answered for the economy as it is now. Change a gate and the answer changes, which is the point: the caller re-solves after every commit.

Allocates one small array, plus one per level of the degree-≥3 recursion. This is a boundary call — per lamp, per commit — never a per-frame one.

The wall's one parameter.

The wall: 1 at or under parity, falling linearly to 0 at blackoutAt times over-draw.

Written against supply · blackoutAt rather than against demand / supply so that both endpoints are exact: parity returns exactly 1 and the blackout point returns exactly 0, with no rounding sliver of production left on at the moment the game is telling the player the lights went out.

supply <= 0 with any demand is 0. demand <= 0 is 1. A NaN demand — which is a bug in the game's own supply/demand sum — reads as no demand rather than as a blackout: a NaN that blacks out the grid is unrecoverable, and one that reads as healthy leaves the game playable while the real bug is found. Never returns NaN.

The share: min(1, supply / demand). A queue, not a wall — everyone present gets a slice and nothing collapses.

demand <= 0 is 1 and supply <= 0 is 0; for any finite positive supply the result is strictly positive, which is the property that distinguishes a queue from a wall. Never returns NaN.

demand / supply, for the meter — the number a HUD paints amber at 0.8, so that 18 of 20 does not look like 6 of 20.

0 when demand is zero, Infinity when supply is zero and demand is not; never NaN, because a NaN reaches the player as an empty progress bar rather than as an error anyone can act on.

This is a derived read and it must never be stored. Infinity serializes to null with a perfectly valid checksum, and a game that writes this number into its save has put a hole in it that no layer downstream can detect. It is the one value in this package's surface that is deliberately allowed to be infinite.

cost(k) = base · growth^k. growth must be > 1 in a shipping balance.

b · r^k — the price of the next single unit. Tier A.

b · r^k · (r^n − 1)/(r − 1) — the price of count more, starting from owned. Tier A.

A fixed batch is all or nothing: a ×10 button with funds for six buys nothing, not six. Only maxBuyable resolves a purchase against the balance, and that asymmetry is the point — a partial batch is a different transaction from the one the player pressed.

floor( log_r( c(r−1)/(b·r^k) + 1 ) ), corrected for float rounding, clamped to cap.

The guarantee callers rely on is two-sided, and both halves hold on the engine that computed them: bulkCost(curve, owned, maxBuyable(...)) <= budget — a max purchase can never drive a balance negative — and bulkCost(curve, owned, maxBuyable(...) + 1) > budget unless the answer is cap, so the button says what it does.

The correction after the logarithm is at most four steps in each direction. It is a rounding fix, not a search: cap bounds arithmetic, never CPU, and 4,000 owned costs the same as 4.

This result is advisory. Do not persist it and do not send it anywhere.

The seed is Math.log, which ECMA-262 does not require to be correctly rounded. Two conforming engines can therefore disagree in the last bit, and on a cost curve that disagreement can land exactly on a floor boundary: same save, same balance, two clients, two different answers to "how many can I afford" — differing by exactly one. That is bounded and it is the residual the design accepts, because the alternative is a pow-free integer search or an epsilon, and an epsilon here would let a player buy something they cannot afford.

What follows for a caller:

• Use it for a label and for the size of the purchase you are about to make, on the engine that computed it. Within one client it is exactly consistent with bulkCost.
• Never store it, never checksum it, and never put it in a replay log or on a wire. Store the inputs — owned count and balance — and recompute. A persisted count computed on Firefox and verified on Safari can differ by one and will look like tampering.
• The authoritative check is the balance test at purchase time, and it is bulkCost(curve, owned, n) <= budget compared exactly. A verifier that re-derives n and demands equality will reject honest clients on a browser update; a verifier that charges the bulkCost of the n it was handed and refuses when the balance will not cover it cannot.

Ascending thresholds, each multiplying once. The source game ships ×2 at 10 / 20 / 35 / 50.

The multiplier from milestone bonuses at an owned count. Repeated multiplication, so Tier A.

Feed it purchased counts, never effective ones. This is the subtlest bug in the package: a multiplier keyed on a count the flow itself produces changes the rate inside an integral, so a client integrating at 10 Hz places the discontinuity somewhere different from a catch-up integrating once — same save, two answers, neither reproducible. Purchased counts change only at actions, which is exactly the property the closed form needs.

It is a pure function of a number so a game can also use it on a shop card, which is where players actually learn the mechanic exists.

An identity for a thing in the world — a lamp, a building, a pilgrim with a name.

A number at runtime and in JSON; branded so that a lamp id cannot be passed where a tile index is wanted. The one cast that constructs one lives inside mintId, and the one that re-narrows a saved integer lives inside asEntityId. There is deliberately no third.

The allocator. Its entire state is one integer, and that integer must be saved.

next is deliberately mutable: this is the one value in the package that is not a value. A counter that is not persisted alongside the entities it named will re-issue live ids on the next session and merge two entities into one — silently, and unrecoverably.

Start or restore an allocator.

Take the next id. Monotone, and never reused.

Recycling a freed id is the ABA bug in a game: a reference held to a lamp that was extinguished silently becomes a reference to the lamp built afterwards, and the symptom appears three systems away. At one mint per millisecond a counter reaches Number.MAX_SAFE_INTEGER in 285,000 years, so there is nothing to reclaim.

Deterministic by construction: ids are handed out in the order actions are applied, so a replay from a seed and an input log mints the same ids for the same things. That is why the counter is here and not derived from a clock or an Rng — a time-derived id cannot replay, and a random one would consume a stream the rest of the game is also drawing from.

Narrow a number that came back from a save.

Ids arrive from JSON.parse as plain numbers, so a load boundary needs exactly one checked cast — and that check is worth having for its own sake: an id at or above source.next is proof the counter was not saved with the entities. That save will re-issue live ids and merge two entities into one, which is unrecoverable and silent. Fail at load instead.

The kit version this package was built as part of.