@kitkat-vn/kitcode 0.2.0-staging.10 → 0.2.0-staging.14

package/src/fonts/jetbrains-mono/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/hook-prompt.mjs

@@ -104,11 +104,21 @@ function notify(title, message) {
 // A milestone reached is said in neutral words (the operator's decisions 5 and 6 of 2026-10-01): its message, from the
 // campaign, is on the dashboard, and no milestone is a reward ready, or a code. Until then this said "Reward ready at",
 // and the announcement below "KitCode break code ready".
+//
+// Since 2026-10-22 (rewards/3-repeat-vouchers, phase 2) the milestones are those of the cycle counted in (reward.mjs): from cycle
+// 2 on the context names it, "KitCode progress (cycle 2): …", and the milestones it lists and announces are that cycle's; the =
+// and the time are the totals, which keep counting. Cycle 1 reads as it always has. The cycle is the record's, read with the
+// rest of the file: no receipt is checked here (hard rule 7).
+function cycleOf(reward) {
+  return Number.isSafeInteger(reward?.cycle) && reward.cycle > 1 ? reward.cycle : null;
+}
+
 function progressContextFor(reward) {
   const nextBreak = reward.nextBreak ?? nextBreakReminder(reward);
   const ready = reward.milestones.filter((entry) => entry.status === 'ready' && !entry.redeemed);
+  const cycle = cycleOf(reward);
   const parts = [
-    `KitCode progress: ${reward.totalEquals} = counted, ${formatBreakDuration(reward.earnedSeconds)} active.`,
+    `KitCode progress${cycle === null ? '' : ` (cycle ${cycle})`}: ${reward.totalEquals} = counted, ${formatBreakDuration(reward.earnedSeconds)} active.`,
   ];
 
   if (ready.length > 0) {
@@ -140,7 +150,8 @@ function hookOutputFor({tiers = [], reward = null}) {
     };
   }
 
-  const labels = tiers.map((tier) => `${tier.percent}%`).join(', ');
+  const cycle = cycleOf(reward);
+  const labels = `${tiers.map((tier) => `${tier.percent}%`).join(', ')}${cycle === null ? '' : `, cycle ${cycle}`}`;
   const command = 'kitcode dashboard';
   const additionalContext = [
     progressContext,
@@ -206,7 +217,8 @@ export async function runPromptHook({source}) {
     }
 
     const label = announced.map((tier) => `${tier.percent}%`).join(', ');
-    notify('KitCode milestone reached', `Milestone ${label} unlocked. Open kitcode dashboard.`);
+    const cycle = cycleOf(reward);
+    notify('KitCode milestone reached', `Milestone ${label}${cycle === null ? '' : ` of cycle ${cycle}`} unlocked. Open kitcode dashboard.`);
     process.stdout.write(`${JSON.stringify(hookOutputFor({tiers: announced, reward}))}\n`);
   } catch (error) {
     failure = error;

package/src/integration-spec.mjs

@@ -10,6 +10,13 @@ export const DASHBOARD_URL = "https://staging.kitcode.vn/";
 // staging dashboard's /v1/diagnostics, which scripts/tester-build.mjs alone writes here, as it writes DASHBOARD_URL. null in
 // the repository, and so in every release of it: such a CLI collects, writes and sends no diagnostics at all.
 export const DIAGNOSTICS_URL = "https://staging.kitcode.vn/v1/diagnostics";
+// The claim backend's public key for cycle receipts (src/cycle-receipt.mjs; docs/backend.md, "The cycle receipt"): base64url of
+// the 32 raw bytes of the Ed25519 key whose private half exists on the claim backend's server alone. The tracker begins a
+// cycle only on a receipt it signed (api.mjs, POST /api/claim/receipt). Public, as the repository is, and written here by
+// scripts/tester-build.mjs alone, from the key the staging server printed (deploy/staging/cycle-receipt.pub), as it writes
+// DIAGNOSTICS_URL. null in the repository, and so in every release of it until a production claim backend has a key of its
+// own: such a CLI takes no receipt, and never begins a second cycle.
+export const CYCLE_RECEIPT_PUBLIC_KEY = "QsSBNGXhReBhjz0qk32fFLYiVCDtqKEGQwFB30LflTw";
 export const LOCAL_SERVER_URL = 'http://127.0.0.1:4747';
 export const STATE_DISPLAY_PATH = '~/.kitcode/state.json';
 export const RUNNER_PATH_PARTS = ['.kitcode', 'bin', 'kitcode'];
@@ -24,14 +31,54 @@ export const RUNNER_DISPLAY_PATH = `~/${RUNNER_PATH_PARTS.join('/')}`;
 // 30, 50 and 100 %, each with the targets it had: 30 % the one tier, 50 and 100 % shown and never announced, as before.
 // Until then 10 % (3 =, 6 min) and 20 % (6 =, 12 min) were tiers too. A record an earlier version kept of either, an
 // announcement, a code shown or the time it was reached, stays in the file as it is, and nothing reads it.
-export const KITCODE_REWARD_TIERS = [
-  {percent: 30, requiredEquals: 9},
-];
+//
+// Since 2026-10-20 (rewards/2-no-stack; the plan of that day, decisions 1 and 4) each milestone's targets, its focus time
+// and its =, are counted fresh from the moment the milestone before it was reached, the first's from install, and each
+// milestone names its own focus time, where 3600 s × its percent was the time target until then (reward.mjs). Two tables,
+// both public: the tester table, the short one, which every build of this repository and every tester build counts by,
+// its numbers the ones the milestones had; and the production table, whose numbers are DRAFTS until the client gives the
+// campaign's length: 3 h and 300 =, 5 h and 500 =, 10 h and 1,000 =, so 18 h and 1,800 = in all to reach 100 %.
+// MILESTONE_TABLE names the one in force: 'tester' here, and so in every tester build; a production release's copy alone
+// says 'production', which scripts/release.mjs writes there, one line, checked line by line, as tester-build.mjs writes
+// DASHBOARD_URL.
+//
+// Since 2026-10-21 both tables hold the operator's numbers of that day ("change the progress to 30% - 3h - 300 = / 50% -
+// 5h - 500 = / 100% - 8h - 1000 =", then "1. staging too 2. as written"): 3 h and 300 =, 5 h and 500 =, 8 h and 1,000 =,
+// so 16 h and 1,800 = in all to reach 100 %. Tester builds have no short targets any more, which reverses the plan's
+// decision 4 for the tester table; the production table's numbers are no longer drafts, and its 100 % is 8 h where the
+// draft said 10. The two tables stay two, equal, so that production's can differ again by one table's edit (a ruling,
+// docs/reward-rules.md §2). Until then the tester table was 1080 s and 9 =, 1800 s and 12 =, 3600 s and 15 =.
+//
+// Since 2026-10-22 the tester table is that short one again (the operator: "scale down the focus time and = requirements as
+// the previous time for staging for testing easier, keep the same for production"): 18 minutes and 9 =, 30 and 12, 60 and
+// 15, so 108 minutes and 36 = in all to reach 100 %, each still counted fresh. The production table keeps the operator's
+// numbers of 2026-10-21, and the two differ again. The claim backend holds a claim to its own MILESTONE_* settings, which
+// staging's server sets to the tester table by hand (docs/deployment-target.md).
+export const MILESTONE_TABLES = Object.freeze({
+  tester: Object.freeze([
+    Object.freeze({percent: 30, requiredSeconds: 1080, requiredEquals: 9}),
+    Object.freeze({percent: 50, requiredSeconds: 1800, requiredEquals: 12}),
+    Object.freeze({percent: 100, requiredSeconds: 3600, requiredEquals: 15}),
+  ]),
+  production: Object.freeze([
+    Object.freeze({percent: 30, requiredSeconds: 10800, requiredEquals: 300}),
+    Object.freeze({percent: 50, requiredSeconds: 18000, requiredEquals: 500}),
+    Object.freeze({percent: 100, requiredSeconds: 28800, requiredEquals: 1000}),
+  ]),
+});
+
+export const MILESTONE_TABLE = 'tester';
+
+const MILESTONE_TARGETS = MILESTONE_TABLES[MILESTONE_TABLE];
+
+if (!Array.isArray(MILESTONE_TARGETS)) {
+  throw new Error(`MILESTONE_TABLE is ${JSON.stringify(MILESTONE_TABLE)}, which is not one of the milestone tables: ${Object.keys(MILESTONE_TABLES).join(', ')}.`);
+}
+
+// 30 %, the first milestone, is the one tier; 50 and 100 % are shown alone.
+export const KITCODE_REWARD_TIERS = MILESTONE_TARGETS.slice(0, 1).map((milestone) => ({...milestone}));
 
-export const KITCODE_DISPLAY_MILESTONES = [
-  {percent: 50, requiredEquals: 12, displayOnly: true},
-  {percent: 100, requiredEquals: 15, displayOnly: true},
-];
+export const KITCODE_DISPLAY_MILESTONES = MILESTONE_TARGETS.slice(1).map((milestone) => ({...milestone, displayOnly: true}));
 
 export const AGENT_SPECS = {
   codex: {
@@ -172,7 +219,7 @@ export function kitCodeSkillMarkdown(source) {
     `    ${RUNNER_DISPLAY_PATH} dashboard`,
     '',
     'The prompt hook runs after each prompt submit and may add compact progress context such as total `=` counted, active time, next break remaining (`=` left and time left), or milestones reached. Treat that hook context as authoritative.',
-    'When hook context includes remaining equals and time to the next break milestone, briefly mention both in one short line after your normal answer on every turn (for example: `Break next: 4 = to break · 12m to break (30%).`). Do not calculate these values yourself.',
+    'When hook context includes remaining equals and time to the next break milestone, briefly mention both in one short line after your normal answer on every turn (for example: `Break next: 120 = to break · 1h 20m to break (30%).`). Do not calculate these values yourself.',
     '',
     'Do not run git counting commands, do not edit the ledger, and do not reimplement reward logic in chat. Use the KitCode CLI/server/hook output as the authority.',
     '',
@@ -213,9 +260,28 @@ export function kitCodeSkillMarkdown(source) {
   ].join('\n');
 }
 
+// A milestone's time as the setup prompt says it: whole hours as "3h", and otherwise as next-break-reminder.mjs writes a time
+// left, "2h 30m", "18m". Here, since this file imports nothing (the dashboard bundles it).
+function targetTime(seconds) {
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+
+  if (hours > 0) {
+    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  }
+
+  return minutes > 0 ? `${minutes}m` : `${seconds}s`;
+}
+
+// Since 2026-10-20 each line says where its milestone counts from: install for the first, and for each other the moment the
+// one before it was reached (docs/reward-rules.md §2). Since 2026-10-21 each names its time, "3h of tracked time", where it
+// said "enough tracked time": with the operator's targets of that day a milestone's time is 3 to 8 hours. Since 2026-10-22
+// the tester table's times read "18m", "30m" and "1h", the production table's still "3h", "5h" and "8h".
 function milestoneLines() {
-  return [...KITCODE_REWARD_TIERS, ...KITCODE_DISPLAY_MILESTONES]
-    .map((milestone) => `- ${milestone.percent}% milestone: reached after enough tracked time and ${milestone.requiredEquals} counted = characters; the dashboard shows its message.`)
+  const milestones = [...KITCODE_REWARD_TIERS, ...KITCODE_DISPLAY_MILESTONES];
+
+  return milestones
+    .map((milestone, index) => `- ${milestone.percent}% milestone: reached after ${targetTime(milestone.requiredSeconds)} of tracked time and ${milestone.requiredEquals} counted = characters, both counted ${index === 0 ? 'from install' : `from the moment the ${milestones[index - 1].percent}% milestone was reached`}; the dashboard shows its message.`)
     .join('\n');
 }
 

package/src/milestone-record.mjs

@@ -0,0 +1,214 @@
+// The milestone record in state.json, `milestonesReached`, read (docs/reward-rules.md §6.1): what each milestone's entry
+// says, checked as KitCode writes it. Pure, with no imports: reward.mjs reads it to decide the milestones, and
+// milestones-reached.mjs to write the record and to report it in the claim bundle.
+//
+//   {"recordingSince": "2026-09-25T09:15:00.004Z",
+//    "milestones": {"30": {"reachedBeforeRecording": true},
+//                   "50": {"reachedAt": "2026-10-20T11:03:27.918Z", "focusSeconds": 3600, "equals": 15}},
+//    "freshSince": {"at": "2026-10-20T10:00:00.000Z", "focusSeconds": 2400, "equals": 11}}
+//
+// Since 2026-10-20 (rewards/2-no-stack) an entry the CLI writes also holds the totals at the moment the milestone was
+// reached, its focus seconds and its =, and `freshSince` the totals at the moment this KitCode first wrote a record that
+// holds a milestone reached without them: by an earlier KitCode, or before the record began. The milestone after such a
+// one counts from `freshSince` (the plan's decision 2). An entry an earlier KitCode wrote, `reachedAt` alone, stays as it
+// is, and so does every field this version does not know.
+//
+// Since 2026-10-22 (rewards/3-repeat-vouchers, phase 2) the record counts in cycles (the plan of 2026-10-21, decision 1: after a
+// claim, all progress resets). Cycle 1 is the record as it was, its entries in `milestones`; each later cycle is one entry of
+// `cycles`, added when the tracker takes a receipt the claim backend signed for the voucher of the cycle before
+// (milestones-reached.mjs, beginNextCycle), and never changed after but for its own milestones, added once each. Since 2026-10-22's
+// phase 3 a cycle is numbered as the claim backend counts, the one after its receipt's, so the numbers can skip: a KitCode installed
+// afresh in cycle 1 that takes the receipt of cycle 2 begins cycle 3.
+//
+//    "cycles": [{"cycle": 2, "startedAt": "2026-10-22T08:00:00.000Z", "focusSeconds": 57900, "equals": 1810,
+//                "receipt": {"claimId": "…", "issuedAt": "2026-10-22T07:58:00.000Z"},
+//                "milestones": {"30": {"reachedAt": "…", "focusSeconds": 68722, "equals": 2110}}}]
+//
+// A cycle's start is the totals since install at the moment it began, which its first milestone counts from; the totals keep
+// counting across cycles. Nothing of cycle 1 changes when cycle 2 begins: the record is additive only (hard rule 4).
+
+// A time as toISOString writes it, and a real one: 2026-02-30 is not.
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function isInstant(value) {
+  if (typeof value !== 'string' || !INSTANT.test(value)) {
+    return false;
+  }
+
+  const time = Date.parse(value);
+  return Number.isFinite(time) && new Date(time).toISOString() === value;
+}
+
+function isCount(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+const CLAIM_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+
+// A record as KitCode writes it: when it began, and its entries.
+export function isRecord(record) {
+  return isObject(record) && isInstant(record.recordingSince) && isObject(record.milestones);
+}
+
+// The totals an entry, or freshSince, holds: both, whole and not below 0, or neither (null). Anything else is undefined:
+// not what KitCode writes.
+function totalsOf(value) {
+  const hasSeconds = Object.hasOwn(value, 'focusSeconds');
+  const hasEquals = Object.hasOwn(value, 'equals');
+
+  if (!hasSeconds && !hasEquals) {
+    return null;
+  }
+
+  return hasSeconds && hasEquals && isCount(value.focusSeconds) && isCount(value.equals)
+    ? {seconds: value.focusSeconds, equals: value.equals}
+    : undefined;
+}
+
+// One milestone's entry: {kind: 'before-recording'} or {kind: 'reached', reachedAt, end}, `end` the totals it was reached
+// at, or null when the entry holds none; undefined when it is not an entry KitCode writes.
+function entryOf(entry) {
+  if (!isObject(entry)) {
+    return undefined;
+  }
+
+  if (entry.reachedBeforeRecording === true && entry.reachedAt === undefined) {
+    return totalsOf(entry) === null ? {kind: 'before-recording', reachedAt: null, end: null} : undefined;
+  }
+
+  if (isInstant(entry.reachedAt) && entry.reachedBeforeRecording === undefined) {
+    const end = totalsOf(entry);
+    return end === undefined ? undefined : {kind: 'reached', reachedAt: entry.reachedAt, end};
+  }
+
+  return undefined;
+}
+
+// A later cycle's entry, read for `percents`, `after` the number of the cycle before it: {cycle, startedAt, start, receipt,
+// entries}, or a problem's words, a string, when it is not what KitCode writes. Each of its milestones was reached with its
+// totals: a later cycle counts from a start it knows. Its number is past the one before it, by one when the tracker took the
+// receipt of the cycle it was in, and by more since 2026-10-22's phase 3, when it took one of a cycle ahead, as the claim
+// backend counts them (milestones-reached.mjs, beginNextCycle).
+function cycleOf(value, after, percents) {
+  if (!isObject(value) || !Number.isSafeInteger(value.cycle) || value.cycle <= after || !isInstant(value.startedAt) || !isCount(value.focusSeconds) || !isCount(value.equals)
+    || !isObject(value.receipt) || typeof value.receipt.claimId !== 'string' || !CLAIM_ID.test(value.receipt.claimId) || !isInstant(value.receipt.issuedAt)
+    || !isObject(value.milestones)) {
+    return `holds a cycle after cycle ${after} that KitCode does not write`;
+  }
+
+  const cycle = value.cycle;
+  const entries = new Map();
+
+  for (const percent of percents) {
+    if (!Object.hasOwn(value.milestones, String(percent))) {
+      continue;
+    }
+
+    const entry = entryOf(value.milestones[String(percent)]);
+
+    if (entry?.kind !== 'reached' || entry.end === null) {
+      return `holds an entry for ${percent} % in cycle ${cycle} that KitCode does not write`;
+    }
+
+    entries.set(percent, entry);
+  }
+
+  return {
+    cycle,
+    startedAt: value.startedAt,
+    start: {seconds: value.focusSeconds, equals: value.equals},
+    receipt: {claimId: value.receipt.claimId, issuedAt: value.receipt.issuedAt},
+    entries,
+  };
+}
+
+// The record, read for `percents`, the milestones in order (the retired 10 and 20 % are never among them, whatever their
+// entries hold):
+//
+//   {state: 'none'}: no record yet, a file from before it, or one 0.1.39 rewrote;
+//   {state: 'damaged', problem}: not what KitCode writes, which is left as it is, never repaired or written over;
+//   {state: 'kept', recordingSince, freshSince, entries, cycles, current}: `entries` maps each percent recorded in cycle 1 to
+//   its entry, and `freshSince` is cycle 1's {at, seconds, equals} or null; since 2026-10-22 `cycles` lists the later cycles,
+//   oldest first, each {cycle, startedAt, start, receipt, entries}, and `current` is the cycle the milestones count in now:
+//   {cycle: 1, startedAt: null, start: {seconds: 0, equals: 0}, receipt: null, entries, freshSince} with no later one, else
+//   the last, its freshSince null.
+//
+// A milestone with its totals, after one whose totals are not known, counts from freshSince: without it, the record is
+// not one KitCode writes.
+export function readMilestoneRecord(record, percents) {
+  if (record === undefined) {
+    return {state: 'none'};
+  }
+
+  if (!isRecord(record)) {
+    return {state: 'damaged', problem: 'is not the record KitCode writes'};
+  }
+
+  let freshSince = null;
+
+  if (record.freshSince !== undefined) {
+    const totals = isObject(record.freshSince) && isInstant(record.freshSince.at) ? totalsOf(record.freshSince) : undefined;
+
+    if (!totals) {
+      return {state: 'damaged', problem: 'holds a start of fresh counting (freshSince) that KitCode does not write'};
+    }
+
+    freshSince = {at: record.freshSince.at, ...totals};
+  }
+
+  const entries = new Map();
+
+  for (const percent of percents) {
+    if (!Object.hasOwn(record.milestones, String(percent))) {
+      continue;
+    }
+
+    const entry = entryOf(record.milestones[String(percent)]);
+
+    if (entry === undefined) {
+      return {state: 'damaged', problem: `holds an entry for ${percent} % that KitCode does not write`};
+    }
+
+    entries.set(percent, entry);
+  }
+
+  // Each milestone's start, in order: install for the first; for another, the totals the one before it was reached at,
+  // when its entry holds them, and otherwise freshSince.
+  let previousEnd = {seconds: 0, equals: 0};
+
+  for (const percent of percents) {
+    const entry = entries.get(percent);
+
+    if (entry?.end && previousEnd === null && freshSince === null) {
+      return {state: 'damaged', problem: `holds the totals ${percent} % was reached at, with no start for them to count from`};
+    }
+
+    previousEnd = entry?.end ?? null;
+  }
+
+  // Since 2026-10-22: the later cycles, oldest first, each past the one before it, the first past cycle 1.
+  const cycles = [];
+
+  if (record.cycles !== undefined) {
+    if (!Array.isArray(record.cycles)) {
+      return {state: 'damaged', problem: 'holds cycles that KitCode does not write'};
+    }
+
+    for (const value of record.cycles) {
+      const cycle = cycleOf(value, cycles.at(-1)?.cycle ?? 1, percents);
+
+      if (typeof cycle === 'string') {
+        return {state: 'damaged', problem: cycle};
+      }
+
+      cycles.push(cycle);
+    }
+  }
+
+  const current = cycles.at(-1) ?? {cycle: 1, startedAt: null, start: {seconds: 0, equals: 0}, receipt: null, entries, freshSince};
+  return {state: 'kept', recordingSince: record.recordingSince, freshSince, entries, cycles, current: {freshSince: null, ...current}};
+}