Skip to content

Open-source gym & body-weight tracker, now in the App Store (iPhone + Apple Watch) and as an Android APK. Plan routines, log workouts, see which muscles are trained, import from Strong/Hevy/FitNotes. Self-host it or use it on the phone alone.

Sync: an older app can no longer delete what it does not know, so a v1.3.9 routine save keeps the pyramid sets

Duarte Santos4e65dca385f5
diff --git a/api/openapi.yaml b/api/openapi.yaml
index 80cd98fac..9ed6fc07a 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -1442,6 +1442,14 @@ paths:
removal on record says it was deleted after its last edit is kept and marked as
added back.
+ Such a writer also cannot delete what it does not know: a field of the stored
+ document, of a stored routine, workout, custom exercise, card or profile, of a
+ routine's exercise, or of a logged exercise or set that its copy leaves out comes
+ back from the stored copy (an older app rebuilds an exercise from the fields it
+ knows, which dropped pyramid sets made on an updated device). Only the fields
+ v1.3.9 itself removes (a superset link, a note, a cleared set value, …) can be
+ removed this way. Send `stamped: true` to remove anything else.
+
Every accepted write also starts the grace period of each stored file (tag `media`)
the new state no longer references, and stops it for each one it references again.
That bookkeeping never changes the answer.
diff --git a/api/sync-stamps.js b/api/sync-stamps.js
index 9bb4f1ac1..88ac2875e 100644
--- a/api/sync-stamps.js
+++ b/api/sync-stamps.js
@@ -15,6 +15,9 @@
// lost to any phone that reconnected with an older, unrelated change.
//
// So PUT /api/data (stampPut):
+// 0. for a writer that does not stamp: puts back every field it left out that it cannot have
+// removed on purpose, since it never knew it (keepUnknown): a v1.3.9 phone saving a routine
+// no longer deletes the pyramid sets made on an updated one;
// 1. never lets the records shrink: `deleted` and `edited` are joined with the stored ones (but
// a reset, which starts the profile over, keeps its own);
// 2. for a writer that does not stamp (no `stamped: true` in the body) and wrote over the
@@ -29,6 +32,7 @@
const isMap = v => !!v && typeof v === 'object' && !Array.isArray(v);
const list = v => (Array.isArray(v) ? v : []);
const same = (x, y) => JSON.stringify(x) === JSON.stringify(y);
+const clone = v => (v === undefined ? v : JSON.parse(JSON.stringify(v)));
const workoutKey = w => (w?.id != null ? w.id : `${w?.d}|${w?.start}`);
const workoutTime = w => Number(w?._ts) || Number(w?.end) || Number(w?.start) || 0;
@@ -166,6 +170,76 @@ function stampUnstamped(cur, next, sent, now) {
}
}
+// Step 0, for a writer that does not stamp: what it left out because it does not know it comes
+// back from the stored copy. An app from before a field existed rebuilds what it edits from the
+// fields it knows: v1.3.9's exercise sheet saved a routine's exercise as sets, reps and weight,
+// and the pyramid built on an updated phone (`pyramid`, `pyramidRest`) was gone on every device.
+// The same for a setting, a routine, a workout, a custom exercise, card or profile, an exercise
+// of a routine, an exercise and a set of a logged workout.
+//
+// What such a writer can drop on purpose is what it knows: `V139_DROPS` lists, per place, every
+// key v1.3.9 (the last app that does not stamp) removes or rebuilds itself. A missing key there
+// is a removal and goes through; any other missing key is one it never knew and is put back.
+// A key put back that it had in fact cleared is one tap to clear again; a dropped one was lost.
+// API planners send back what they read, so for them this changes nothing.
+const V139_DROPS = {
+ state: new Set(['showRir']),
+ routines: new Set(['excludeFromProgression']),
+ 'routines.ex': new Set(['id', 'sg', 'sets', 'min', 'speed', 'mode', 'sec', 'weight', 'bodyweight', 'prog',
+ 'inc', 'deloadFactor', 'note', 'warmupSets', 'restSec', 'reps', 'side', 'repsMin', 'repsMax', 'intensifier']),
+ customEx: new Set(['media', 'url']),
+ equipProfiles: new Set(),
+ gymCards: new Set(),
+ workouts: new Set(['media', 'note', 'name', 'bw', 'prs', 'vol', 'routineIds']),
+ 'workouts.entries': new Set(['sg', 'note', 'notePin', 'noProg', 'topW']),
+ 'workouts.entries.sets': new Set(['w', 'r', 'sec', 'min', 'km', 'dist', 'speed', 'rir', 'rpe', 'planSec', 'note',
+ 'done', 'weightOrigin', 'at', 'sides', 'type', 'drops', 'clusters', 'warmup']),
+};
+// The lists inside an entry that are walked too, and how their items are matched.
+const NESTED = { routines: ['ex'], workouts: ['entries'], 'workouts.entries': ['sets'] };
+// Server bookkeeping and the records merged on their own: never put back from the stored copy.
+const NOT_KEPT = new Set(['_rev', '_wid', '_wids', 'active', 'resetAt', 'resetIds', 'deleted', 'edited']);
+
+// `x` with every key of `old` it lacks and the writer cannot have dropped on purpose. Mutates `x`.
+function keepKeys(old, x, place) {
+ if (!isMap(old) || !isMap(x)) return;
+ const drops = V139_DROPS[place] || new Set();
+ for (const k of Object.keys(old)) {
+ if (k in x || drops.has(k) || ENTRY_META.has(k) || (place === 'state' && NOT_KEPT.has(k))) continue;
+ x[k] = clone(old[k]);
+ }
+ for (const f of NESTED[place] || []) {
+ const a = old[f], b = x[f];
+ if (!Array.isArray(a) || !Array.isArray(b)) continue;
+ for (const [o, n] of pairItems(a, b)) keepKeys(o, n, `${place}.${f}`);
+ }
+}
+// Which item of `a` each item of `b` is: by `id` when every id is there and once per list, by
+// position when the lists are as long as each other and no item moved to another id. Anything
+// else (a set taken out of the middle, a reorder of repeats) is not guessed at.
+function pairItems(a, b) {
+ const ids = xs => xs.map(x => (isMap(x) ? x.id : undefined));
+ const ia = ids(a), ib = ids(b);
+ const unique = xs => xs.every(k => k != null) && new Set(xs).size === xs.length;
+ if (unique(ia) && unique(ib)) {
+ const by = new Map(a.map(x => [x.id, x]));
+ return b.filter(x => by.has(x.id)).map(x => [by.get(x.id), x]);
+ }
+ if (a.length !== b.length || ia.some((k, i) => k !== ib[i])) return [];
+ return b.map((x, i) => [a[i], x]);
+}
+/** Step 0 (above): put back into `next` what a writer that does not stamp left out of `cur`. */
+export function keepUnknown(cur, next) {
+ if (!isMap(cur) || !isMap(next)) return next;
+ keepKeys(cur, next, 'state');
+ for (const f of ENTRY_LISTS) {
+ if (!Array.isArray(cur[f]) || !Array.isArray(next[f])) continue;
+ const before = new Map(cur[f].filter(x => isMap(x) && x.id != null).map(x => [x.id, x]));
+ for (const x of next[f]) if (isMap(x) && x.id != null && before.has(x.id)) keepKeys(before.get(x.id), x, f);
+ }
+ return next;
+}
+
// Step 3: an entry held while a removal on record says it was deleted after its last edit is
// kept, and marked as added back.
function keepHeld(next, now) {
@@ -200,6 +274,7 @@ export function stampPut(cur, next, { overRead = false, stamped = false, now = D
if (d) next.deleted = d; else delete next.deleted;
const e = mergeEdits(cur.edited, next.edited);
if (e) next.edited = e; else delete next.edited;
+ if (!stamped) keepUnknown(cur, next);
if (!stamped && overRead) stampUnstamped(cur, next, sent, t);
}
keepHeld(next, t);
diff --git a/api/test/server-bad-input.test.js b/api/test/server-bad-input.test.js
index 4e147a847..b1b73a467 100644
--- a/api/test/server-bad-input.test.js
+++ b/api/test/server-bad-input.test.js
@@ -154,9 +154,14 @@ test('PUT /api/data: an array is not a document, and null entries never reach th
assert.equal(r.body.rev, 2);
assert.deepEqual(onDisk().workouts.map(w => w.id), ['w2', 'w3']);
assert.deepEqual(onDisk().routines.map(x => x.id), ['r1']);
- // Absent lists stay absent — every client fills its own defaults.
+ // Absent lists stay absent from a client that stamps its own changes: every client fills its
+ // own defaults. From one that does not, a list it left out is one it never knew, and the stored
+ // one stays (sync-stamps.js keepUnknown).
r = await put({ state: { unit: 'kg' }, baseRev: 2 });
assert.equal(r.status, 200);
+ assert.deepEqual(onDisk().workouts.map(w => w.id), ['w2', 'w3']);
+ r = await put({ state: { unit: 'kg' }, baseRev: 3, stamped: true });
+ assert.equal(r.status, 200);
assert.equal('workouts' in onDisk(), false);
assert.equal(h.stackFrames(), 0, `stack traces in the log:\n${h.log}`);
});
diff --git a/api/test/sync-stamps.test.js b/api/test/sync-stamps.test.js
index 9f0783e90..eeabb378e 100644
--- a/api/test/sync-stamps.test.js
+++ b/api/test/sync-stamps.test.js
@@ -119,3 +119,64 @@ test('PUT /api/data: an older app\'s push does not wipe the records, and its del
assert.equal(doc.deleted.workouts.w1, 1000);
assert.ok(doc.deleted.workouts.w2 > 1000);
});
+
+// RC review 2026-10-07: a v1.3.9 phone saving a routine rebuilt each exercise from the fields it
+// knows, and the pyramid made on an updated phone was deleted on every device.
+test('an older app saving a routine keeps the pyramid it does not know', () => {
+ const cur = stored();
+ cur.routines[0].ex = [
+ { id: '0025', sets: 4, mode: 'reps', reps: 12, weight: 40, pyramid: [12, 10, 8, 'max'], pyramidRest: [60, 90, 120, 0] },
+ { id: '0032', sets: 3, mode: 'reps', reps: 8, weight: 100, sg: 'g1' },
+ ];
+ const next = clone(cur);
+ delete next.edited; delete next.deleted;
+ next.routines[0].ex = [
+ { id: '0025', sets: 4, mode: 'reps', reps: 12, weight: 45 }, // its sheet: the weight changed, the pyramid gone
+ { id: '0032', sets: 3, mode: 'reps', reps: 8, weight: 100 }, // it took the superset apart: that stays
+ ];
+ stampPut(cur, next, { overRead: true, stamped: false, now: NOW });
+ assert.deepEqual(next.routines[0].ex[0], { id: '0025', sets: 4, mode: 'reps', reps: 12, weight: 45, pyramid: [12, 10, 8, 'max'], pyramidRest: [60, 90, 120, 0] });
+ assert.equal('sg' in next.routines[0].ex[1], false);
+ assert.ok(next.routines[0]._f.ex >= NOW); // its weight change is still an edit of its own
+});
+
+test('an older app keeps the fields it does not know everywhere: settings, entries, sets', () => {
+ const cur = stored();
+ cur.accentCustom = '#ff00aa'; cur.showRir = true;
+ cur.customEx = [{ id: 'c1', n: 'Curl', media: { hash: 'h' }, future: 1 }];
+ cur.workouts[0].entries = [{ id: 'bench', sets: [{ w: 100, r: 5, done: true, max: true }, { w: 90, r: 8, done: true }] }];
+ cur.workouts[0].newer = 'x';
+ const next = clone(cur);
+ delete next.accentCustom; delete next.showRir;
+ delete next.customEx[0].media; delete next.customEx[0].future;
+ next.workouts[0].entries[0].sets = [{ w: 100, r: 6, done: true }, { w: 90, r: 8 }];
+ delete next.workouts[0].newer;
+ stampPut(cur, next, { overRead: true, stamped: false, now: NOW });
+ assert.equal(next.accentCustom, '#ff00aa');
+ assert.equal('showRir' in next, false); // v1.3.9 removes that one itself
+ assert.deepEqual(next.customEx[0], { id: 'c1', n: 'Curl', future: 1, _ts: next.customEx[0]._ts, _f: next.customEx[0]._f });
+ assert.deepEqual(next.workouts[0].entries[0].sets, [{ w: 100, r: 6, done: true, max: true }, { w: 90, r: 8 }]);
+ assert.equal(next.workouts[0].newer, 'x');
+});
+
+test('a set taken out of the middle is not guessed at, and the app\'s own pushes are left as sent', () => {
+ const cur = stored();
+ cur.workouts[0].entries = [{ id: 'bench', sets: [{ w: 1, max: true }, { w: 2 }, { w: 3, max: true }] }];
+ const old = clone(cur);
+ old.workouts[0].entries[0].sets = [{ w: 1 }, { w: 3 }];
+ stampPut(cur, old, { overRead: true, stamped: false, now: NOW });
+ assert.deepEqual(old.workouts[0].entries[0].sets, [{ w: 1 }, { w: 3 }]);
+ const app = clone(cur);
+ delete app.routines[0].name; delete app.queue;
+ stampPut(cur, app, { overRead: true, stamped: true, now: NOW });
+ assert.equal('name' in app.routines[0], false);
+ assert.equal('queue' in app, false);
+});
+
+test('a reset from an older app is not refilled from the profile it wiped', () => {
+ const cur = stored();
+ cur.accentCustom = '#ff00aa';
+ const next = { _ts: NOW, resetAt: NOW, workouts: [], routines: [] };
+ stampPut(cur, next, { overRead: true, stamped: false, now: NOW });
+ assert.equal('accentCustom' in next, false);
+});
diff --git a/frontend/src/lib/sync-stamps-parity.test.js b/frontend/src/lib/sync-stamps-parity.test.js
index 9b2b1f1d7..099bdb0c5 100644
--- a/frontend/src/lib/sync-stamps-parity.test.js
+++ b/frontend/src/lib/sync-stamps-parity.test.js
@@ -95,4 +95,19 @@ describe('what the server stamps holds in the merge', () => {
expect(mergeStates(rcAgain, old).workouts.map(w => w.id)).toEqual(['w1'])
expect(mergeStates(old, rcAgain).workouts.map(w => w.id)).toEqual(['w1'])
})
+
+ // RC review 2026-10-07: v1.3.9's exercise sheet saved a routine without the pyramid it does not
+ // know, and the updated phone took that on its next merge.
+ it('an older app\'s routine save keeps the pyramid on the updated phone too', () => {
+ const cur = doc0()
+ cur.routines[0].ex = [{ id: 'sq', sets: 4, reps: 12, weight: 40, pyramid: [12, 10, 8, 'max'] }]
+ const rc = change(cur, T + 5000, S2 => { S2.restSec = 75 }) // the updated phone, not pushed yet
+ const old = clone(cur); delete old.edited
+ old.routines[0].ex = [{ id: 'sq', sets: 4, reps: 12, weight: 45 }]; old._ts = T + 9000
+ S.stampPut(cur, old, { overRead: true, now: T + 9000 })
+ for (const m of [mergeStates(rc, old), mergeStates(old, rc)]) {
+ expect(m.routines[0].ex).toEqual([{ id: 'sq', sets: 4, reps: 12, weight: 45, pyramid: [12, 10, 8, 'max'] }])
+ expect(m.restSec).toBe(75)
+ }
+ })
})
diff --git a/website/api.html b/website/api.html
index bcd9dc5eb..3bd6510b5 100644
--- a/website/api.html
+++ b/website/api.html
@@ -1485,6 +1485,8 @@ main.api-main .lead { color: var(--fg-2); max-width: 58ch; margin: 14px 0 0; fon
<div class="ep-body">
<p>Replaces the stored state wholesale (atomic write; there is no merge on the server). The <code>active</code> field — an in-progress workout — is stripped before saving: a running session belongs to the device running it. Body limit 5 MiB.</p>
<p>With <code>baseRev</code> the write is conditional: it goes through only when <code>baseRev</code> equals the document's current revision, and answers 409 with the current document otherwise — the client merges the two and pushes again with the revision it was given. Without <code>baseRev</code> the write is unconditional (clients from before revisions, and deliberate replaces such as a backup import). The server stamps the new revision into the document as <code>_rev</code>; a <code>_rev</code> sent by the client is ignored.</p>
+<p>The records of removals (<code>deleted</code>) and of edits (<code>edited</code>) never shrink: the stored ones are joined into the write (a reset keeps its own). A writer that does not stamp its own changes (no <code>stamped: true</code>; an API script, an older app) and sends the current <code>baseRev</code> gets them stamped by the server, at the server's time: every entry it removed (a workout, routine, custom exercise, weigh-in, card, profile or favourite), every setting and plan day it changed (<code>queue</code>, <code>week.&lt;day&gt;</code>, …), and every entry it edited (<code>_ts</code>, per field <code>_f</code>). That keeps a planner's new week, or a routine it removed, from being undone by a phone that reconnects later with an older change. An entry the document holds while a removal on record says it was deleted after its last edit is kept and marked as added back.</p>
+<p>Such a writer also cannot delete what it does not know: a field of the stored document, of a stored routine, workout, custom exercise, card or profile, of a routine's exercise, or of a logged exercise or set that its copy leaves out comes back from the stored copy (an older app rebuilds an exercise from the fields it knows, which dropped pyramid sets made on an updated device). Only the fields v1.3.9 itself removes (a superset link, a note, a cleared set value, …) can be removed this way. Send <code>stamped: true</code> to remove anything else.</p>
<p>Every accepted write also starts the grace period of each stored file (tag <code>media</code>) the new state no longer references, and stops it for each one it references again. That bookkeeping never changes the answer.</p>
<p class="ep-auth"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2.5"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg><span>Requires a session — the cookie set at sign-in, or <code>Authorization: Bearer &lt;token&gt;</code> from mobile-app pairing.</span></p>
@@ -1499,12 +1501,22 @@ main.api-main .lead { color: var(--fg-2); max-width: 58ch; margin: 14px 0 0; fon
<span class="p-type">integer | null</span>
<span class="p-desc">The revision this client last read or wrote. Omit or null for an unconditional overwrite.</span>
</div>
+ <div class="prow">
+ <span class="p-name">baseWid</span>
+ <span class="p-type">string</span>
+ <span class="p-desc">The write id (<code>_wid</code>) of the document this client last read or wrote. With <code>baseRev</code>, a write over a different document at the same revision (the data directory went back in time and the number was reached again) answers 409.</span>
+ </div>
+ <div class="prow">
+ <span class="p-name">stamped</span>
+ <span class="p-type">boolean</span>
+ <span class="p-desc">True when the client stamps its own changes in <code>deleted</code>, <code>edited</code> and each entry's <code>_ts</code>/<code>_f</code>, as the app does. Omit it to have the server stamp what changed against the stored document.</span>
+ </div>
</div>
<p class="ep-h">Responses</p>
<div class="ptab">
<div class="prow rrow">
<span class="r-code s2">200</span>
- <span class="p-desc">Saved.<span class="r-sig">{ ok: always true, ts: number | null, rev: integer }</span></span>
+ <span class="p-desc">Saved.<span class="r-sig">{ ok: always true, ts: number | null, rev: integer, wid: string }</span></span>
</div>
<div class="prow rrow">
<span class="r-code s4">400</span>
@@ -1538,7 +1550,7 @@ main.api-main .lead { color: var(--fg-2); max-width: 58ch; margin: 14px 0 0; fon
<div class="ptab">
<div class="prow rrow">
<span class="r-code s2">200</span>
- <span class="p-desc">The current revision (0 when the profile has no state yet).<span class="r-sig">{ rev: integer }</span></span>
+ <span class="p-desc">The current revision (0 when the profile has no state yet).<span class="r-sig">{ rev: integer, wid: string }</span></span>
</div>
<div class="prow rrow">
<span class="r-code s4">401</span>
@@ -3527,6 +3539,26 @@ main.api-main .lead { color: var(--fg-2); max-width: 58ch; margin: 14px 0 0; fon
<span class="p-type">integer</span>
<span class="p-desc">Server-set revision, incremented on every accepted PUT. Ignored when sent by a client.</span>
</div>
+ <div class="prow">
+ <span class="p-name">_wid</span>
+ <span class="p-type">string</span>
+ <span class="p-desc">Server-set id of this write (16 hex characters), new on every accepted PUT.</span>
+ </div>
+ <div class="prow">
+ <span class="p-name">_wids</span>
+ <span class="p-type">string[]</span>
+ <span class="p-desc">The write ids of the documents this one descends from, oldest first (up to 50).</span>
+ </div>
+ <div class="prow">
+ <span class="p-name">deleted</span>
+ <span class="p-type">object</span>
+ <span class="p-desc">When entries were removed, per list and entry key ({ workouts: { &lt;id&gt;: ms } }, weigh-ins by day, favourites by exercise id). A negative stamp is an add-back after a removal. Never shrinks on the server; stamped for writers that do not stamp (see PUT /api/data).</span>
+ </div>
+ <div class="prow">
+ <span class="p-name">edited</span>
+ <span class="p-type">object</span>
+ <span class="p-desc">When each setting and plan day was last changed, ms ({ queue: ms, 'week.3': ms, … }). Never shrinks on the server; stamped for writers that do not stamp (see PUT /api/data).</span>
+ </div>
<div class="prow">
<span class="p-name">unit</span>
<span class="p-type">&quot;kg&quot; | &quot;lb&quot;</span>
@@ -3560,7 +3592,7 @@ main.api-main .lead { color: var(--fg-2); max-width: 58ch; margin: 14px 0 0; fon
<div class="prow">
<span class="p-name">queue</span>
<span class="p-type">object</span>
- <span class="p-desc">A planner's floating week {ids, since, startsOn, label} — the week's sessions as an ordered queue, the first undone one is today's. Written only by an API client (never by the app), read by the reminder tick.</span>
+ <span class="p-desc">A planner's floating week {ids, since, startsOn, label} — the week's sessions as an ordered queue, the first undone one is today's. Written by an API client or by the app's own rotation feature, read by the reminder tick.</span>
</div>
<div class="prow">
<span class="p-name">week</span>