@stage5/lumine 0.3.60 → 0.3.61

package/lib/admin.js

@@ -6252,6 +6252,10 @@ export function printRewardReviewResult({ operation, data }) {
     console.log(
       `Budgets: per user/day ${config.userDailyXP} XP/${config.userDailyCoins} Coins${config.userDailyClaims ? ` · ${config.userDailyClaims} claim(s)` : ""}`,
     );
+    if (config.missedRematch)
+      console.log(
+        `Missed-puzzle rematches: a variant ${config.missedRematch.afterDays} day(s) after a miss · ${config.missedRematch.perDay} a day · full first-try amounts, outside the daily claim count`,
+      );
     for (const rule of config.rules)
       console.log(`  ${formatRewardRuleLine(rule)}`);
   }
@@ -7397,8 +7401,64 @@ function printAiBucketRuleResult({ operation, data }) {
   return false;
 }
 
+// `admin reward-diagnostics`: one app's (or member's) reward audit trail.
+// The generic audit-event printer read runId/action/result, which these
+// events don't have, so every line printed "undefined".
+export function formatRewardDiagnostics(data, filters = {}) {
+  if (data.coverage === "unavailable")
+    return [`Reward diagnostics unavailable${data.reason ? `: ${data.reason}` : "."}`];
+  const events = Array.isArray(data.events) ? data.events : [];
+  const at = (seconds) =>
+    Number.isFinite(Number(seconds)) && Number(seconds) > 0
+      ? new Date(Number(seconds) * 1000).toISOString().slice(5, 16).replace("T", " ")
+      : "?";
+  const lines = [
+    `Reward diagnostics: ${events.length} event(s), ${at(data.since)} → ${at(data.until)} UTC${data.coverage ? ` (${data.coverage})` : ""}`,
+  ];
+  const tally = new Map();
+  for (const event of events) {
+    const key = event.operation || "?";
+    const outcomes = tally.get(key) || new Map();
+    const outcome = event.outcome || "?";
+    outcomes.set(outcome, (outcomes.get(outcome) || 0) + 1);
+    tally.set(key, outcomes);
+  }
+  for (const [operation, outcomes] of tally)
+    lines.push(`  ${operation}: ${[...outcomes].map(([outcome, n]) => `${n} ${outcome}`).join(", ")}`);
+  for (const event of events) {
+    const details = event.details || {};
+    const extras = [
+      details.httpStatus ? String(details.httpStatus) : "",
+      details.errorCode ? String(details.errorCode) : "",
+      Number.isFinite(Number(event.durationMs)) ? `${event.durationMs} ms` : "",
+    ].filter(Boolean);
+    lines.push(
+      `#${event.id} ${at(event.createdAt)} ${event.source || "?"} build ${event.buildId ?? "?"} user ${event.userId ?? "?"} ${event.operation || "?"} → ${event.outcome || "?"}${extras.length ? ` (${extras.join(", ")})` : ""}`,
+    );
+  }
+  if (Array.isArray(data.challenges) || Array.isArray(data.receipts))
+    lines.push(`Server records: ${data.challenges?.length ?? 0} challenge(s), ${data.receipts?.length ?? 0} receipt(s)${data.canonicalRecordsTruncated ? " (truncated)" : ""}.`);
+  for (const limitation of data.limitations || []) lines.push(`Note: ${typeof limitation === "string" ? limitation : JSON.stringify(limitation)}`);
+  if (data.nextCursor) {
+    // the next page needs the same scope and window
+    const again = [
+      filters.buildId ? `--build ${filters.buildId}` : "",
+      filters.userId ? `--user ${filters.userId}` : "",
+      filters.days ? `--days ${filters.days}` : "",
+    ].filter(Boolean).join(" ");
+    lines.push(`More: lumine admin reward-diagnostics ${again ? `${again} ` : ""}--cursor ${data.nextCursor}`);
+  }
+  return lines;
+}
+
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  if (operation.name === "reward-diagnostics.read") {
+    const query = new URLSearchParams(String(operation.path || "").split("?")[1] || "");
+    const filters = { buildId: query.get("buildId"), userId: query.get("userId"), days: query.get("days") };
+    for (const line of formatRewardDiagnostics(data, filters)) console.log(line);
+    return;
+  }
   if (operation.name === "spending.report" && data.spending) {
     console.log(formatSpending(data.spending));
     return;
@@ -7411,6 +7471,11 @@ function printAdminResult({ operation, result }) {
         : `${grade.ruleId}: ${grade.current || "exhausted"}${grade.clearedToday ? " (cleared today)" : ""}; ${grade.remaining} unearned of ${grade.sets}${grade.refillDue ? `; refill to ${data.refillTarget}` : ""}`
       : `${grade.ruleId}: queue unavailable`);
     if (!data.complete) console.log("Queue coverage is incomplete; unavailable grades are not empty queues.");
+    // Rematch variants to write in the next refill: missed puzzles with no unmet variant left for someone.
+    if (data.variantNeeds?.length) {
+      console.log(`Rematch variants needed (write as new sets with variantOf):`);
+      for (const need of data.variantNeeds) console.log(`  ${need.ruleId} ${need.setKey}: ${need.waiting} learner(s) waiting · ${need.variants} variant(s) so far`);
+    }
     return;
   }
   if (printChatSafetyResult({ operation, data })) return;

package/lib/commands.js

@@ -3323,7 +3323,7 @@ export function printHelp() {
   lumine admin chat-reports export <report-id> | --hold <hold-id> --out <new-dir> [--json]   (evidence package + SHA-256 manifest)
   lumine admin chat-reports suspend --user <id> --note <why> [--json]   (full ban: signs them out)
   lumine admin reward-review show <review-id> [--dir <path>] [--json]
-  lumine admin math-lab queue [--json]   (published sets remaining per grade, all-time claims, refill flags)
+  lumine admin math-lab queue [--json]   (published sets remaining per grade, all-time claims, refill flags, rematch variants needed)
   lumine admin reward-review approve <review-id> [--config <rules.json>] [--reason <text>] [--json]   (approval publishes the approved version)
   lumine admin reward-review propose <review-id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--title <new app name>] [--thumbnail <image|workspace>] [--json]
   lumine admin reward-review reject|revoke <review-id> --reason <text> [--json]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.60",
+  "version": "0.3.61",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.69.0
+Version: 1.71.0
 Updated: 2026-10-24
-Generated: 2026-10-24T02:37:05.998Z
+Generated: 2026-10-24T05:37:23.377Z
 
 ## Platform rules
 Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed frame, even when the code itself is correct. They outrank every other guideline: follow them in every change, including small ones, and fix any break of them you see in code you touch.
@@ -1588,7 +1588,7 @@ world.updatePresence({ x, y, z, facing });
 
 ### Twinkle.rewards
 - await Twinkle.rewards.getStatus() | scopes: rewards:claim
-  - Returns: { mode: "live", dayKey, userDailyClaims, claimsToday, budgets: { userDailyXP, userDailyCoins }, rules: [{ id, title, howTo?, category?, series?, xp, coins, verifier: "numeric-quiz" | "completion", minSeconds?, progression?, retryReward: { xp, coins }, maxAttempts, available, setKey, questionCount }], challenges: [{ challengeId, ruleId, attempts, attemptsRemaining, state: "open" | "finished" | "earned", setKey, questions: [{ prompt, hint?, guide? }] }], history: [{ ruleId, xp, coins, attempt, createdAt }], balances: { xp, coins } } | { mode: "preview", dayKey?, rules, challenges: [], history: [], balances?, problems?: string[], message }
+  - Returns: { mode: "live", dayKey, userDailyClaims, claimsToday, missedRematch?: { afterDays, perDay, usedToday, ready: [{ ruleId, setKey, variantOf, missed }], upcoming, nextReadyDay }, budgets: { userDailyXP, userDailyCoins }, rules: [{ id, title, howTo?, category?, series?, xp, coins, verifier: "numeric-quiz" | "completion", minSeconds?, progression?, retryReward: { xp, coins }, maxAttempts, available, setKey, questionCount }], challenges: [{ challengeId, ruleId, attempts, attemptsRemaining, state: "open" | "finished" | "earned", setKey, questions: [{ prompt, hint?, guide? }] }], history: [{ ruleId, xp, coins, attempt, createdAt }], balances: { xp, coins } } | { mode: "preview", dayKey?, rules, challenges: [], history: [], balances?, problems?: string[], message }
   - Read canonical earning rules (without answer keys), today’s started challenges, today’s receipts and balances. Drafts return preview mode: for the app's owner the rules come from the draft's own rewards.json and question sheet (problems lists what is still wrong with them); anyone else sees no rules. Unapproved or revoked published releases return an error.
   - rules[].available is false on a site day (UTC) the reviewer scheduled no questions for; show the rule as not available instead of starting it. xp/coins are the first-try amounts; retryReward is what a correct answer pays after a wrong one (equal to xp/coins unless the reviewer set a retry share). maxAttempts null means unlimited wrong answers until the site's daily reset (UTC midnight, 9:00 AM in Korea). retry.paidAttempts, when set, is the last attempt number a correct answer is still paid on: a later correct answer is recorded as solved (receipt xp 0, coins 0) and pays nothing — tell the learner before they pass it.
   - challenges lists challenges this viewer already started today with their questions, so an app can resume after a reload without calling start. A question's guide (reviewer-approved JSON teaching content: explanation, interactive-model configuration) is present only once the viewer has answered at least once, right or wrong; render it as the after-attempt lesson. claimsToday against userDailyClaims (null = uncapped) tells whether another bounty can still pay today.
@@ -1598,6 +1598,7 @@ world.updatePresence({ x, y, z, facing });
   - category and series are optional rewards.json labels for a long list. category is a short section header (up to 40 characters, e.g. "Bring friends"); series is a short lowercase key (e.g. "new-friend") tying repeat rules like vigil-friend-1/2/3 together, and rules in one series must share category, verifier, XP and Coins. The Earn page groups rules by category and shows each series as one row ("up to 3 a day", "1 of 3 today"); group the app's own rewards list the same way.
   - nonogram-picture-v1 uses Twinkle’s private, editorially reviewed picture bank. Set pictureSize to 5, 10 or 15 on each completion rule. Do not bundle daily solutions or a fixed answer catalog in app files. The collection is maintained through lumine admin nonogram; the reward amounts and daily limits still come from the approved rules.
   - Collection progression keeps every approved keyed set available independently of other players' solves. collectionSets lists { setKey, number }; challenges carry collection, practice, completed and completion. Live status includes viewerId for a per-viewer durable outbox. Attempts and completion persist across days/releases; the daily reward allowance does not reset a puzzle's paid tries. Existing receipts (including rematches), Vault solves/practice and studied guides count. Completed puzzles can be revisited; do not treat any receipt for the grade as completing all its puzzles. Collection rules support up to 500 permanent sets per rule; legacy queued/dated rules keep their 62-set limit.
+  - missedRematch appears when rewards.json declares missedRematch ({ afterDays, perDay }; it requires userDailyClaims) and the app has collection rules. A collection set may declare variantOf: another set's key, meaning the same puzzle with new numbers (an ordinary puzzle for everyone). A learner who missed any puzzle of a family (an original plus its variants) and has not solved one of its puzzles on the first try gets the family's first unmet puzzle as a rematch afterDays site days after their last answer in the family. ready lists today's rematches (variantOf is the family's original, missed the puzzle this learner got wrong most recently; once perDay are used it only keeps one already opened today): open setKey with start({ ruleId, setKey }) at any time (before or after today's bounties) and the challenge comes back with rematch: { variantOf, answered }: one answer, the rule's full first-try amounts, a receipt (rematch: true) that does not count toward userDailyClaims but does count toward the XP/Coin budgets. usedToday against perDay says how many rematches were opened today; opening one uses it. upcoming and nextReadyDay describe rematches not ready yet.
 - await Twinkle.rewards.getReceipt({ challengeId }) | scopes: rewards:claim
   - Returns: { mode: "live", status: "awarded" | "completed" | "pending" | "expired" | "not_found", receipt: { id, challengeId, ruleId, reviewId, artifactVersionId, dayKey, xp, coins, attempt, createdAt } | null, balances: { xp, coins } } | { mode: "preview", status: "not_found", receipt: null, message }
   - Read an existing receipt for this app and signed-in viewer by server-issued challengeId, including previous UTC days and previous approved versions. Requires the current approved published release and runtime grant; a stale frame must reload first. Never awards, retries a claim, returns answer keys, or restores removed rewards permission.
@@ -1614,6 +1615,7 @@ world.updatePresence({ x, y, z, facing });
   - For nonogram-picture-v1, start returns completion { profile, completed: false, readyInSeconds, puzzle: { size, rows: number[][], cols: number[][] } }. Render those row and column clues; there is no progress call. Live readyInSeconds is the remaining approved minimum wait, so reopening a puzzle does not restart its clock. The private picture is durably bound to this exact viewer, app, release, rule, challenge and expiry. Reopening returns the same clues even after a refill. New challenges use unseen pictures; build_reward_picture_collection_complete means this size needs a refill. Offer practice/community puzzles while waiting.
   - For collection rules, setKey is required and must be one of the approved permanent keys. Start returns that exact question and persistent attempts. practice:true means no XP/Coins or official rating (daily allowance reached, earlier practice, or viewed archive guide); display that before answering. Merely opening a practice question does not consume its future eligibility, but answering it does. completed:true returns its lesson and completion, without a new challenge or payout. A current eligible daily-rematch puzzle must be opened as the rematch. A challenge still expires at the usual day/release boundary; reopen the same set to resume its saved attempts.
   - Live completion starts return readyInSeconds, the remaining server-enforced wait for that challenge (including a resumed challenge). Anchor it at response arrival and queue one claim after that time; do not poll claim while too early. Retain the finished proof in a per-viewer outbox and reconcile getReceipt after a lost reply or reload. It is timing metadata, not proof of completion or permission to pay. Older servers may omit it; use the rule minSeconds conservatively. Preview timing and receipts remain separate.
+  - A collection puzzle listed in getStatus().missedRematch.ready starts as a paid rematch, before or after today's bounties: rematch: { variantOf, answered }, attemptsRemaining 1, reward = the rule's full xp/coins, retryReward 0, and its receipt does not count toward userDailyClaims. A wrong answer ends the rematch (the puzzle stays in the collection as an ordinary missed puzzle); a right one pays and completes it.
 - await Twinkle.rewards.progress({ challengeId, completionToken?, frames?, record?, requestId? }) | scopes: rewards:claim
   - Returns: { mode: "live" | "preview", completion: { profile, token?, completed, failed?, decision?, message?, maxFrames? }, aiUsagePolicy? }
   - Verify a bounded batch of inputs for an approved server-simulated climb.