@kitkat-vn/kitcode 0.2.0-staging.9 → 0.3.0-staging.16

package/src/milestones-reached.mjs

@@ -1,6 +1,7 @@
 import {equalsLedgerFrom} from './equals-ledger.mjs';
 import {focusTimeFrom} from './focus-clock.mjs';
-import {buildRewardSummary, REWARD_MILESTONES} from './reward.mjs';
+import {readMilestoneRecord} from './milestone-record.mjs';
+import {decideMilestones, MILESTONE_PERCENTS, milestonesOf, REWARD_TIERS} from './reward.mjs';
 
 // When each milestone first became ready (docs/reward-rules.md §6.1), for the claim bundle. Kept in
 // state.json, where the tracker writes the progress it belongs to, as `milestonesReached`:
@@ -17,40 +18,38 @@ import {buildRewardSummary, REWARD_MILESTONES} from './reward.mjs';
 // 0.1.39 drops it when it rewrites the file (install-id.mjs says how). The next write of this version then
 // begins a new record, and a milestone reached by then is recorded as reached before recording began:
 // the time it was reached is lost, and none is made up.
-
-export const MILESTONE_PERCENTS = REWARD_MILESTONES.map((milestone) => milestone.percent);
-
-// 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);
-}
-
-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;
-}
-
-// A record as KitCode writes it: when it began, and its entries.
-function isRecord(record) {
-  return isObject(record) && isInstant(record.recordingSince) && isObject(record.milestones);
+//
+// Since 2026-10-08 the milestones are 30, 50 and 100 % (integration-spec.mjs): the entries an earlier version wrote for 10
+// and 20 % stay in the record, never changed or removed, as every entry does, and nothing reads them now.
+//
+// Since 2026-10-20 (rewards/2-no-stack) the record decides the milestones: each counts from the moment the one before it
+// was reached (reward.mjs decideMilestones), so an entry also holds the totals at that moment, written with it, once:
+//
+//   "50": {"reachedAt": "2026-10-20T11:03:27.918Z", "focusSeconds": 4200, "equals": 21}
+//
+// and, the first time this KitCode writes a record that holds a milestone reached without them, by an earlier KitCode or
+// before the record began, `freshSince` records the totals then: the milestone after it counts from there (the plan's
+// decision 2). An earlier entry is never given totals it did not hold, and none is made up (milestone-record.mjs).
+//
+// Since 2026-10-22 (rewards/3-repeat-vouchers, phase 2) the record counts in cycles (milestone-record.mjs): a milestone newly
+// reached is recorded in the cycle it is in, and a new cycle begins only by beginNextCycle, on a receipt the claim backend
+// signed for the voucher of the cycle before, which the tracker has checked (api.mjs). Nothing else begins one: no read, no
+// failure and no prompt resets anyone's progress.
+
+export {MILESTONE_PERCENTS};
+
+function totalsIn(stored, focusSeconds) {
+  return {
+    seconds: Math.floor(Math.max(0, Number(focusSeconds ?? focusTimeFrom(stored).activeSeconds) || 0)),
+    equals: Math.max(0, Number(equalsLedgerFrom(stored).total_equals) || 0),
+  };
 }
 
-// The milestones reached by `state` now: every milestone up to the highest one that is ready or
-// redeemed. A milestone's targets are never below a lower one's, so a higher milestone ready means every
-// lower one was ready then too, even one that reads locked now: a redeemed tier keeps its status when
-// its = go down (docs/reward-rules.md §6, E8).
-function reachedNow(state) {
-  const ledger = equalsLedgerFrom(state);
-  const reward = buildRewardSummary({earnedSeconds: focusTimeFrom(state).activeSeconds, totalEquals: ledger.total_equals, ledger});
-  const highest = Math.max(0, ...reward.milestones.filter((milestone) => milestone.status !== 'locked').map((milestone) => milestone.percent));
-
-  return MILESTONE_PERCENTS.filter((percent) => percent <= highest);
+function redeemedIn(stored) {
+  const tiers = new Set(REWARD_TIERS.map((tier) => tier.percent));
+  return new Set(equalsLedgerFrom(stored).earned_tiers
+    .filter((entry) => entry !== null && typeof entry === 'object' && tiers.has(Number(entry.percent)) && typeof entry.redeemed_at === 'string')
+    .map((entry) => Number(entry.percent)));
 }
 
 // Records, in `stored`, each milestone first found reached: `stored` is the file's own object, inside
@@ -59,72 +58,177 @@ function reachedNow(state) {
 // before recording began, with no time, since none is known. From then on, a milestone newly reached is
 // recorded at `now`. A record, or an entry, that is not what KitCode writes is left exactly as it is:
 // never repaired, never written over. `now` is the tracker's clock, which a test can move.
-export function noteMilestonesReached(stored, now = new Date(Date.now())) {
+//
+// Since 2026-10-20 a milestone newly reached is recorded with the totals at `now`, its focus seconds, floored, and its =;
+// `focusSeconds` is the tracker's own clock, when it folds a scan between two saves, ahead of the file's by up to one
+// save. One write reaches one milestone at most: the next counts from that write's totals, so nothing it credited counts
+// toward the next. A milestone reached with no totals known, and freshSince not yet written, has it written now.
+//
+// Since 2026-10-23 (tracking/2-cli) a milestone is found reached against the targets in force (reward.mjs milestonesOf;
+// tracking-config.mjs), or `config`'s, a tracking config, when one is given: the record keeps every milestone it holds whatever
+// the targets do, so a raise takes nothing reached away, and a target lowered under what the milestone in progress earned is
+// recorded reached by this write.
+export function noteMilestonesReached(stored, now = new Date(Date.now()), {focusSeconds, config} = {}) {
   const record = stored.milestonesReached;
+  const read = readMilestoneRecord(record, MILESTONE_PERCENTS);
 
-  if (record !== undefined && !isRecord(record)) {
+  if (read.state === 'damaged') {
     return;
   }
 
-  const reached = reachedNow(stored);
+  const totals = totalsIn(stored, focusSeconds);
+  const decided = decideMilestones({totals, record, redeemed: redeemedIn(stored), ...(config === undefined ? {} : {milestones: milestonesOf(config)})});
   const at = now.toISOString();
+  const atTotals = {at, focusSeconds: totals.seconds, equals: totals.equals};
 
-  if (record === undefined) {
+  if (read.state === 'none') {
+    const before = decided.entries.filter((entry) => entry.reached);
     stored.milestonesReached = {
       recordingSince: at,
-      milestones: Object.fromEntries(reached.map((percent) => [String(percent), {reachedBeforeRecording: true}])),
+      milestones: Object.fromEntries(before.map((entry) => [String(entry.percent), {reachedBeforeRecording: true}])),
+      ...(before.length > 0 ? {freshSince: atTotals} : {}),
     };
     return;
   }
 
-  for (const percent of reached) {
-    if (!Object.hasOwn(record.milestones, String(percent))) {
-      record.milestones[String(percent)] = {reachedAt: at};
+  // The milestones of the cycle counted in: cycle 1's are the record's own; a later cycle's, its entry's, the last of `cycles`
+  // (milestone-record.mjs), whose numbers can skip since 2026-10-22's phase 3.
+  const cycle = read.current.cycle > 1 ? record.cycles[record.cycles.length - 1] : null;
+  const milestones = cycle === null ? record.milestones : cycle.milestones;
+
+  for (const entry of decided.entries) {
+    if (!entry.reached || entry.recorded || Object.hasOwn(milestones, String(entry.percent))) {
+      continue;
     }
+
+    // Found reached now, at the frontier, with the totals of this write; or below one that is, its totals not known, which a
+    // later cycle never has: it counts from a start it knows.
+    milestones[String(entry.percent)] = entry.end === null
+      ? {reachedAt: at}
+      : {reachedAt: at, focusSeconds: entry.end.seconds, equals: entry.end.equals};
   }
-}
 
-// A milestone record that is not what KitCode writes. The claim bundle does not guess at it.
-export class MilestoneRecordError extends Error {
-  constructor(problem) {
-    super(`The record of when each milestone was reached, in state.json, ${problem}. KitCode has left it as it is.`);
-    this.name = 'MilestoneRecordError';
+  const unknown = MILESTONE_PERCENTS.some((percent) => {
+    const entry = record.milestones[String(percent)];
+    return entry !== undefined && (entry.reachedBeforeRecording === true || entry.focusSeconds === undefined);
+  });
+
+  if (unknown && record.freshSince === undefined) {
+    record.freshSince = atTotals;
   }
 }
 
-function entryFor(percent, record) {
-  const key = String(percent);
+// Begins the next cycle, in `stored`, the file's own object inside updateState, on `receipt`, a receipt the tracker read and
+// found signed with the claim backend's key and for this install (cycle-receipt.mjs, api.mjs): {installId, cycle, claimId,
+// issuedAt}. The plan of 2026-10-21's decision 1: after a claim, all progress resets. The receipt of the cycle the record is in
+// begins the next, once: the record holds which receipt began each cycle, so the same receipt again, or one of a cycle past,
+// changes nothing. Since 2026-10-22's phase 3 (the coordinator's ruling: the server is the authority on cycles) one of a cycle
+// ahead, as a KitCode installed afresh after its person's earlier vouchers is given, begins the cycle after the receipt's, as the
+// claim backend counts them; until then it changed nothing, and such an install stayed in its cycle for good. Either way a
+// receipt only ever resets progress, and never adds any. The new cycle starts at the totals at `now`, `focusSeconds` the
+// tracker's own clock as a save writes it (noteMilestonesReached); the totals themselves go on counting, and nothing earlier is
+// changed or removed: the record is additive only (hard rule 4). First, as any write that makes progress does, it records what
+// is reached by now in the cycle it closes, beginning the record if none was.
+//
+// Returns {outcome: 'started', cycle, startedAt, start}; {outcome: 'used', cycle, startedAt}, the cycle this receipt began
+// already; {outcome: 'cycle', current}, the receipt of a cycle before the record's, `current`; or {outcome: 'damaged', problem},
+// a record not what KitCode writes, left as it is.
+export function beginNextCycle(stored, receipt, now = new Date(Date.now()), {focusSeconds} = {}) {
+  noteMilestonesReached(stored, now, {focusSeconds});
+  const read = readMilestoneRecord(stored.milestonesReached, MILESTONE_PERCENTS);
+
+  if (read.state === 'damaged') {
+    return {outcome: 'damaged', problem: read.problem};
+  }
+
+  const used = read.cycles.find((cycle) => cycle.receipt.claimId === receipt.claimId);
 
-  if (!Object.hasOwn(record.milestones, key)) {
-    return {percent, status: 'not-reached', reachedAt: null};
+  if (used !== undefined) {
+    return {outcome: 'used', cycle: used.cycle, startedAt: used.startedAt};
   }
 
-  const entry = record.milestones[key];
+  if (receipt.cycle < read.current.cycle) {
+    return {outcome: 'cycle', current: read.current.cycle};
+  }
 
-  if (isObject(entry) && entry.reachedBeforeRecording === true && entry.reachedAt === undefined) {
-    return {percent, status: 'reached-before-recording', reachedAt: null};
+  const totals = totalsIn(stored, focusSeconds);
+  const startedAt = now.toISOString();
+  const record = stored.milestonesReached;
+  const next = {
+    cycle: receipt.cycle + 1,
+    startedAt,
+    focusSeconds: totals.seconds,
+    equals: totals.equals,
+    receipt: {claimId: receipt.claimId, issuedAt: receipt.issuedAt},
+    milestones: {},
+  };
+
+  if (Array.isArray(record.cycles)) {
+    record.cycles.push(next);
+  } else {
+    record.cycles = [next];
   }
 
-  if (isObject(entry) && isInstant(entry.reachedAt) && entry.reachedBeforeRecording === undefined) {
-    return {percent, status: 'reached', reachedAt: entry.reachedAt};
+  return {outcome: 'started', cycle: next.cycle, startedAt, start: {focusSeconds: totals.seconds, equals: totals.equals}};
+}
+
+// A milestone record that is not what KitCode writes. The claim bundle does not guess at it.
+export class MilestoneRecordError extends Error {
+  constructor(problem) {
+    super(`The record of when each milestone was reached, in state.json, ${problem}. KitCode has left it as it is.`);
+    this.name = 'MilestoneRecordError';
   }
+}
 
-  throw new MilestoneRecordError(`holds an entry for ${percent} % that KitCode does not write`);
+function totalsField(totals) {
+  return {focusSeconds: totals.seconds, equals: totals.equals};
 }
 
 // The record as the claim bundle reports it: when it began, or null when it has not, and each
-// milestone's status and time, from 10 to 100 %. Reads only; a damaged record throws a
+// milestone's status and time, from 30 to 100 %. Reads only; a damaged record throws a
 // MilestoneRecordError.
+//
+// Since 2026-10-20 each milestone also carries `start` and `end`, the totals it counted from and those it was reached at,
+// {focusSeconds, equals}, when its entry holds them; null otherwise: not reached, or reached with no totals known.
+//
+// Since 2026-10-22 the record reported is that of the cycle counted in, `cycle`, and `cycleStart` says where it began:
+// {at: null, focusSeconds: 0, equals: 0} for cycle 1, install; the moment a later one began, and the totals then, which its
+// 30 % counts from.
+const FIRST_CYCLE_START = Object.freeze({at: null, focusSeconds: 0, equals: 0});
+
 export function milestonesReachedFrom(state) {
-  const record = state.milestonesReached;
+  const read = readMilestoneRecord(state.milestonesReached, MILESTONE_PERCENTS);
 
-  if (record === undefined) {
-    return {recordingSince: null, milestones: MILESTONE_PERCENTS.map((percent) => ({percent, status: 'not-reached', reachedAt: null}))};
+  if (read.state === 'none') {
+    return {recordingSince: null, cycle: 1, cycleStart: {...FIRST_CYCLE_START}, milestones: MILESTONE_PERCENTS.map((percent) => ({percent, status: 'not-reached', reachedAt: null, start: null, end: null}))};
   }
 
-  if (!isRecord(record)) {
-    throw new MilestoneRecordError('is not the record KitCode writes');
+  if (read.state === 'damaged') {
+    throw new MilestoneRecordError(read.problem);
   }
 
-  return {recordingSince: record.recordingSince, milestones: MILESTONE_PERCENTS.map((percent) => entryFor(percent, record))};
+  const {current} = read;
+  let previousEnd = {...current.start};
+
+  const milestones = MILESTONE_PERCENTS.map((percent) => {
+    const entry = current.entries.get(percent);
+    const start = previousEnd ?? current.freshSince;
+    previousEnd = entry?.end ?? null;
+
+    if (entry === undefined) {
+      return {percent, status: 'not-reached', reachedAt: null, start: null, end: null};
+    }
+
+    const segment = entry.end === null ? {start: null, end: null} : {start: totalsField(start), end: totalsField(entry.end)};
+    return entry.kind === 'before-recording'
+      ? {percent, status: 'reached-before-recording', reachedAt: null, ...segment}
+      : {percent, status: 'reached', reachedAt: entry.reachedAt, ...segment};
+  });
+
+  return {
+    recordingSince: read.recordingSince,
+    cycle: current.cycle,
+    cycleStart: current.cycle > 1 ? {at: current.startedAt, focusSeconds: current.start.seconds, equals: current.start.equals} : {...FIRST_CYCLE_START},
+    milestones,
+  };
 }

package/src/next-break-reminder.mjs

@@ -1,4 +1,4 @@
-import {milestoneProgressPercent} from './break-progress.mjs';
+import {earnedToward, milestoneProgressPercent} from './break-progress.mjs';
 
 export function formatBreakDuration(seconds) {
   const totalSeconds = Math.max(0, Math.floor(Number(seconds) || 0));
@@ -48,8 +48,9 @@ export function nextBreakReminder(reward) {
     return null;
   }
 
-  const earnedSeconds = Math.max(0, Number(reward.earnedSeconds) || 0);
-  const totalEquals = Math.max(0, Number(reward.totalEquals) || 0);
+  // What counts toward it: since 2026-10-20 what was earned since it began, the moment the milestone before it was
+  // reached (break-progress.mjs earnedToward); from a tracker before then, the totals.
+  const {seconds: earnedSeconds, equals: totalEquals} = earnedToward(reward, milestone);
   const requiredSeconds = Math.max(0, Number(milestone.requiredSeconds) || 0);
   const requiredEquals = Math.max(0, Number(milestone.requiredEquals) || 0);
   // Floored, so it reads 100 only once the milestone is unlocked (docs/reward-rules.md §10).

package/src/onboarding-electron.mjs

@@ -10,6 +10,7 @@ import {DASHBOARD_URL} from './integration-spec.mjs';
 import {onboardingPreferences, saveOnboardingPreferences, STORE_DIR} from './store.mjs';
 import {resolveSetupPlatform} from './onboarding-platform.mjs';
 import {renderOnboardingWindow} from './onboarding-window.mjs';
+import {WELCOME_ERRORS, WELCOME_TESTER_ERRORS, WELCOME_WORDS} from './welcome-words.mjs';
 import {keepWindowOnItsPage} from './window-guards.mjs';
 
 const sourceDirectory = path.dirname(fileURLToPath(import.meta.url));
@@ -132,7 +133,7 @@ function setupWindowOptions(platform) {
     transparent: true,
     hasShadow: false,
     backgroundColor: '#00000000',
-    title: 'Welcome to KitCode',
+    title: WELCOME_WORDS.windowTitle,
     webPreferences: {preload: preloadPath, contextIsolation: true, nodeIntegration: false, sandbox: true},
   };
 }
@@ -154,7 +155,7 @@ app.whenReady().then(() => {
   keepWindowOnItsPage(window);
   // Project records carry absolute paths: only Welcome's own page gets them.
   ipcMain.handle('kitcode:onboarding-initial-state', (event) => {
-    if (event.sender !== window.webContents) return {ok: false, error: 'Invalid setup request.', projects: [], suggestedProjects: []};
+    if (event.sender !== window.webContents) return {ok: false, error: WELCOME_ERRORS.invalidRequest, projects: [], suggestedProjects: []};
     return {
       ...onboardingPreferences(),
       projects: listProjectRecords(),
@@ -170,21 +171,21 @@ app.whenReady().then(() => {
     return {canceled: result.canceled, paths, projects: describeProjects(paths)};
   });
   ipcMain.handle('kitcode:onboarding-submit', async (event, input) => {
-    if (event.sender !== window.webContents) return {ok: false, error: 'Invalid setup request.'};
+    if (event.sender !== window.webContents) return {ok: false, error: WELCOME_ERRORS.invalidRequest};
     // A tester build's invited email, kept outside state.json, before anything else is saved; one that is not an address is
     // asked for again, and nothing is saved.
     if (diagnosticsEnabled() && typeof input?.invitedEmail === 'string' && !setInvitedEmail(input.invitedEmail).ok) {
-      return {ok: false, error: 'That email address does not look right: check it, or leave it empty.'};
+      return {ok: false, error: WELCOME_TESTER_ERRORS.invalidEmail};
     }
     const folders = validFolders(input?.folders);
-    if (!folders.length && !listProjectRecords().length) return {ok: false, error: 'Add at least one readable project folder.'};
-    try { registerNewProjects(folders); } catch { return {ok: false, error: 'KitCode could not register one of those folders.'}; }
+    if (!folders.length && !listProjectRecords().length) return {ok: false, error: WELCOME_ERRORS.noProjects};
+    try { registerNewProjects(folders); } catch { return {ok: false, error: WELCOME_ERRORS.registerFailed}; }
     const selection = {autoTrack: input?.autoTrack === true, companionView: 'mini'};
     if (selection.autoTrack && !(await runCli(['track', '--host', host, '--port', port]))) {
       saveOnboardingPreferences({...selection, completed: false});
       return {
         ok: false,
-        error: 'Projects were saved, but the tracker could not start. Free the local port and retry.',
+        error: WELCOME_ERRORS.trackerFailed,
         projects: listProjectRecords(),
       };
     }
@@ -197,14 +198,14 @@ app.whenReady().then(() => {
     return {ok: true, projects};
   });
   ipcMain.handle('kitcode:onboarding-remove-project', async (event, projectId) => {
-    if (event.sender !== window.webContents) return {ok: false, error: 'Invalid setup request.'};
-    if (!projectId) return {ok: false, error: 'Project not found.'};
+    if (event.sender !== window.webContents) return {ok: false, error: WELCOME_ERRORS.invalidRequest};
+    if (!projectId) return {ok: false, error: WELCOME_ERRORS.projectNotFound};
     try {
       const removed = removeProject(projectId);
-      if (!removed) return {ok: false, error: 'Project not found.'};
+      if (!removed) return {ok: false, error: WELCOME_ERRORS.projectNotFound};
       return {ok: true, projects: listProjectRecords()};
     } catch {
-      return {ok: false, error: 'KitCode could not remove that project.'};
+      return {ok: false, error: WELCOME_ERRORS.removeFailed};
     }
   });
   ipcMain.handle('kitcode:onboarding-close', (event) => {

package/src/onboarding-platform.mjs

@@ -1,3 +1,5 @@
+import {WELCOME_WORDS} from './welcome-words.mjs';
+
 const PLATFORM_CHROME = {
   darwin: {
     id: 'darwin',
@@ -41,9 +43,10 @@ export function setupPlatformTheme(platform) {
   return PLATFORM_CHROME[resolveSetupPlatform(platform)];
 }
 
+// Welcome's title bar, in Welcome's words (src/welcome-words.mjs); the Mini has its own (src/companion-controls.mjs).
 export function renderPlatformChrome(theme = setupPlatformTheme()) {
-  return `<div class="${theme.chromeClass}" title="Drag window">
-    <button class="dot filled dot-close" id="closeButton" type="button" aria-label="Close setup" title="Close"></button>
+  return `<div class="${theme.chromeClass}" title="${WELCOME_WORDS.chrome.drag}">
+    <button class="dot filled dot-close" id="closeButton" type="button" aria-label="${WELCOME_WORDS.chrome.closeName}" title="${WELCOME_WORDS.chrome.close}"></button>
     <span class="dot" aria-hidden="true"></span>
     <span class="dot" aria-hidden="true"></span>
   </div>`;