halkyon/docs/adr/0034-train-equipment-and-plate-maths.md

ADR 0034: Train's equipment by place, and plate maths

• Status: decided 2 Nov 2026, by the developer (D1–D4, the agent's recommendations taken), the rest proposed by the agent and flagged where it chose.
• Numbering: 0025–0029 are held (ADR 0030's note); this is the next free number.
• Builds on: ADR 0030 (Halkyon Train): D7 (sealed rows), D12 and D60 (the shell, its Profile and Settings), D19 (no background location), D42 (interval plans); ADR 0002 (the envelope a row is sealed in).

Context

On 1 Nov 2026 the developer asked whether Train has an inventory: whether they can tell it that they own dip bars, dumbbells, barbells and so on, with how many weight plates of which weight; that training plans then use it and work out "the least number and amount of work necessary to change the weight plates from one [weight] to another"; and that the inventory be bound to a place, home's apart from a gym's, the training offered adjusting to it.

Train has nothing of it: it records cardio and runs interval plans (D42), whose steps end after a time, a distance or a lap, with targets of pace, heart rate, power or stroke rate. No model holds an exercise, a set, a repetition or a weight.

Decision

1. This step builds the inventory and the plate maths; strength plans and recording them come next, on top of them (D1, the developer's choice of 2 Nov 2026). A plan's sets, their order and the plate changes between them need both, and both are worth having alone: the inventory says what a place has, the plate calculator what to load.

2. The inventory is a catalogue with the person's own items beside it (D2). Train knows the kinds it can reason about, so that plans can rely on them:

   • loadable, taking plates, each with its own weight: barbell, EZ bar, trap bar, dumbbell handle;
   • plates, by weight and count, one set a place;
   • weights by weight and count, not loadable: fixed dumbbells, kettlebells;
   • present or not, with a count: bench, rack, pull-up bar, dip bars, cable machine, resistance bands;
   • the person's own, by name and count, which plans can name but not reason about.

   Weights are kept in grams, whole numbers, so that sums are exact (1.25 kg is 1250 g); they are shown and typed in kilograms. Plates in pounds are left for later (the person types their kilograms, 20.41 kg for a 45 lb plate).

3. Plate maths: both sides alike, the heaviest load not above the target, the heavier plates inside (D3).

   • A barbell's load is its own weight and the plates on its two sides, the same on each: a plate is used on a side only as often as the place has it twice over. A pair of dumbbells takes four of each plate (two handles, two sides).
   • The load chosen is the heaviest the plates make that isn't above the target, and the calculator says how far below it is; among loads of that weight, the one of fewest plates.
   • Plates go on heaviest first, so that a side reads from the inside out as heavier to lighter, as in a gym.
   • Between loads, only what must come off does: a side is a stack, its innermost plates stay as long as the next load starts with them, the rest come off from the outside and the next load's go on. For a series of targets (a plan's sets, later), among the loads of each target's weight, those are chosen that make the fewest plate moves over the whole series (a shortest path through them). The calculator lists the moves per side: "take off 1 × 5 kg, put on 2 × 10 kg".

4. A place is chosen, and the last one remembered (D4). The person picks the place (Home, Gym…) where its equipment matters, the plate calculator now and plans later; Train remembers the last on the device. It never asks for the device's location for it, keeping D19.

5. A place is a sealed, synced row of its own (the agent's, following plans and routes): the table training_place, its payload a place's name and items, versioned JSON, sealed with the person's key (D7); one row a place, so two devices editing two places never collide, and the same place the last writer wins, as with plans. The migration only creates the table, its space index and its cascade to the sync engine's spaces, as routes did; deleting a person deletes their places with their space.

6. Where it shows (the agent's): Settings gets Equipment, beside the body's figures: the places, each with its items, a new place starting from what a home or a gym usually has, every item editable; and the plate calculator, from Equipment and from a place: a target, the bar or handle, the plates per side, and for several targets the moves between them.

7. A weight vest is a kind of its own (the developer's, 5 Nov 2026; the details the agent's): weightVest, its weight and, for an adjustable one, how far it goes (gramsUpTo, added to the payload without a new schema: an older app leaves the kind out). What the body lifts takes weight as typed, so a vest at the place chosen shows as a chip by a set's weight (VestChip), tapped writing its weight, an adjustable one's lightest; a plan doesn't plan with it. A hand grip trainer stays the person's own, by name, as it would serve one exercise, itself their own.

Consequences

• Strength plans (exercises, sets, repetitions, weights, rest) are the next step: a plan names its place's equipment, and the plate maths of D3 orders the moves between its sets. What an exercise needs (a bench, a rack, dip bars) is checked against the place chosen, which is how "the training offered adjusts" to it.
• Gyms' bars sometimes weigh other than 20 kg, and collars add weight; both are items a person edits (a barbell's own weight), collars left out of the maths for now.
• Pounds, micro-plates' own increments and a sleeve's length (how many plates fit) are left for later; the calculator never loads more plates than a place has.