@stage5/lumine 0.2.80 → 0.2.82

package/lib/admin.js

@@ -174,7 +174,10 @@ export function readRewardProposalDirectory(directory) {
   let bytes = 0;
   const walk = (dir) => {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      if (entry.name.startsWith(".") || REWARD_PROPOSAL_SKIPPED_DIRS.has(entry.name))
+      if (
+        entry.name.startsWith(".") ||
+        REWARD_PROPOSAL_SKIPPED_DIRS.has(entry.name)
+      )
         continue;
       const fullPath = path.join(dir, entry.name);
       if (entry.isSymbolicLink()) {
@@ -194,7 +197,10 @@ export function readRewardProposalDirectory(directory) {
         );
       }
       bytes += buffer.length;
-      const relative = path.relative(realRoot, fullPath).split(path.sep).join("/");
+      const relative = path
+        .relative(realRoot, fullPath)
+        .split(path.sep)
+        .join("/");
       files.push({ path: `/${relative}`, content: buffer.toString("utf8") });
     }
   };
@@ -221,7 +227,7 @@ export function readRewardConfigFile(filePath) {
   const normalizedPath = String(filePath || "").trim();
   if (!normalizedPath) {
     throw cliValidationError(
-      "Pass the earning rules with --config <rules.json> (dailyXP, dailyCoins, userDailyXP, userDailyCoins, lifetimeXP, lifetimeCoins, rules[]).",
+      "Pass the earning rules with --config <rules.json> (userDailyXP, userDailyCoins, optional userDailyClaims, rules[]).",
     );
   }
   let contents;
@@ -3918,7 +3924,9 @@ function printRewardReviewResult({ operation, data }) {
       console.log(`  ${file.status}: ${file.path}`);
   }
   if (review.status === "rejected" && review.declinedByCreator) {
-    console.log("The creator declined the proposed changes; the request is closed.");
+    console.log(
+      "The creator declined the proposed changes; the request is closed.",
+    );
   }
   if (review.status === "approved" && review.publishedArtifactVersionId) {
     console.log(
@@ -3944,7 +3952,7 @@ function printRewardReviewResult({ operation, data }) {
   const config = review.config || {};
   if (Array.isArray(config.rules)) {
     console.log(
-      `Budgets: day ${config.dailyXP} XP/${config.dailyCoins} Coins · per user/day ${config.userDailyXP} XP/${config.userDailyCoins} Coins${config.userDailyClaims ? ` · ${config.userDailyClaims} claim(s)` : ""} · lifetime ${config.lifetimeXP} XP/${config.lifetimeCoins} Coins`,
+      `Budgets: per user/day ${config.userDailyXP} XP/${config.userDailyCoins} Coins${config.userDailyClaims ? ` · ${config.userDailyClaims} claim(s)` : ""}`,
     );
     for (const rule of config.rules)
       console.log(`  ${formatRewardRuleLine(rule)}`);

package/lib/rewards.js

@@ -214,7 +214,7 @@ function printRewardsHelp() {
   lumine rewards sheet --show       Summarize the sheet on file (never prints answer keys)
 
 rewards.json (project root) declares the economy the reviewer approves:
-  { "dailyXP", "dailyCoins", "userDailyXP", "userDailyCoins", "lifetimeXP", "lifetimeCoins", "userDailyClaims"?,
+  { "userDailyXP", "userDailyCoins", "userDailyClaims"?,
     "rules": [{ "id", "title", "xp", "coins", "verifier": "numeric-quiz" | "completion",
                 "maxAttempts"?, "retry"?: { "xpPercent", "coinsPercent", "paidAttempts"? }, "minSeconds"? (completion), "progression"?: "dated" | "until-earned" (quiz) }] }
 Questions and answer keys never go in project files; they belong in the sheet.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.80",
+  "version": "0.2.82",
   "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.45.0
+Version: 1.45.2
 Updated: 2026-09-14
-Generated: 2026-09-15T02:06:06.654Z
+Generated: 2026-09-19T10:34:03.685Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -33,9 +33,10 @@ Generated: 2026-09-15T02:06:06.654Z
 - Use Twinkle.live for one-way app livestreams and Twinkle.chat for the accompanying thread. Free livestreams require a verified host, end after at most 15 minutes, and issue at most 10 private viewer grants. Twinkle keeps platform-owned live-status/end controls above active hosts, so app code cannot hide or replace the broadcaster's Stop path.
 - Media Energy is separate from AI Energy. Replace Media Energy UI only from canonical mediaEnergy/getUsage responses; never decrement, reserve, or synthesize it in app code.
 - Twinkle.rewards awards real XP and Coins only in the current approved published release. Drafts, local previews, private apps and superseded releases cannot earn. The server supplies a published-runtime grant; app code cannot choose a recipient or award amount.
-- The creator's agent designs the rewards. Declare the economy in a project file `rewards.json` at the root: budgets (dailyXP, dailyCoins, userDailyXP, userDailyCoins, lifetimeXP, lifetimeCoins, optional userDailyClaims) and rules [{ id, title, xp, coins, verifier: 'numeric-quiz' | 'completion', maxAttempts?, retry?: { xpPercent, coinsPercent, paidAttempts? }, minSeconds? (completion), progression?: 'dated' | 'until-earned' (quiz) }]. Wire the matching Twinkle.rewards calls with those literal rule ids. Questions and answer keys NEVER go in project files (published source is readable by every player): quiz rules get them from the private question sheet uploaded with `lumine rewards sheet <file.json>` ({ rules: { <ruleId>: { questions?, sets? } } }); `lumine rewards check` validates both together. A review request freezes the code and proposes rewards.json merged with the sheet; the administrator reads the code, checks the amounts and whether the app is exploitable, may change any amount, and approves. Creators are kids and teens: show approval status and one Send for review action; do not ask them to fill in technical forms. Every code update that retains rewards needs a new approval before publishing. Removing the SDK automatically clears its gate. Apps read amounts, tries and sets from getStatus, never from their own file.
+- The creator's agent designs the rewards. Declare the economy in a project file `rewards.json` at the root: budgets (userDailyXP, userDailyCoins, optional userDailyClaims; there is no app-wide daily or lifetime budget, only what one learner can earn per day) and rules [{ id, title, xp, coins, verifier: 'numeric-quiz' | 'completion', maxAttempts?, retry?: { xpPercent, coinsPercent, paidAttempts? }, minSeconds? (completion), progression?: 'dated' | 'until-earned' (quiz) }]. Wire the matching Twinkle.rewards calls with those literal rule ids. Questions and answer keys NEVER go in project files (published source is readable by every player): quiz rules get them from the private question sheet uploaded with `lumine rewards sheet <file.json>` ({ rules: { <ruleId>: { questions?, sets? } } }); `lumine rewards check` validates both together. A review request freezes the code and proposes rewards.json merged with the sheet; the administrator reads the code, checks the amounts and whether the app is exploitable, may change any amount, and approves. Creators are kids and teens: show approval status and one Send for review action; do not ask them to fill in technical forms. Every code update that retains rewards needs a new approval before publishing. Removing the SDK automatically clears its gate. Apps read amounts, tries and sets from getStatus, never from their own file.
 - Verifiers: 'numeric-quiz' pays for server-checked numeric answers (retry share, attempt limits, dated sets or until-earned sets that stay up until somebody earns them, after-answer guides). 'completion' pays when the app reports an activity finished — a cleared stage, a finished round — at least minSeconds after start({ ruleId }); the server checks only the elapsed time, once per learner per site day (UTC midnight), and the budgets. Call start when the activity begins and claim({ challengeId }) with no answers when it ends; keep completion amounts and userDailyXP small enough that a player scripting the calls would not matter, because nothing else is verified.
 - Numeric quiz answers are verified on the server; client scores, privateDb state, timers and completion booleans are not verified reward evidence. Limits reset at UTC midnight. Rules are earned once per viewer per UTC day; attempt limits and retry payouts come from the approved rule. Challenges expire at the UTC day boundary. Budgets apply across release changes.
+- Optional reward rule controls: maxLifetimeClaims caps one learner’s receipts for that rule across every day and release; completionProof: classic-tower-v1 requires a server-simulated Classic Tower finish in addition to minSeconds. These are server-enforced controls. Existing completion rules without completionProof still verify elapsed time only.
 
 ## Token Scopes
 files:read, media:read, media:write, live:read, live:write, user:read, users:read, dailyReflections:read, content:read, content:write, sharedDb:read, sharedDb:write, privateDb:read, privateDb:write, files:write, chat:read, chat:write, notifications:read, notifications:write, notifications:emit, reminders:read, reminders:write, rewards:claim
@@ -1017,6 +1018,7 @@ world.updatePresence({ x, y, z, facing });
   - 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.
   - Under progression 'until-earned' the same set stays up day after day until somebody earns it; setKey names the set currently up. Completion rules are always available and have questionCount 0.
+  - Rules may set maxLifetimeClaims, a per-learner limit for that rule across days and releases. rules[].lifetime contains the server-confirmed limit and remaining claims. App storage never enforces this limit.
 - await Twinkle.rewards.getReceipt({ challengeId }) | scopes: rewards:claim
   - Returns: { mode: "live", status: "awarded" | "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.
@@ -1026,12 +1028,20 @@ world.updatePresence({ x, y, z, facing });
   - Creates or resumes a server-issued challenge for the signed-in viewer. Render its questions (prompt and optional hint) and collect numeric answers in the same order. One daily challenge per rule/review; repeat starts cannot reset attempts. A challenge stays open until the site's daily reset (UTC midnight, 9:00 AM in Korea) (expiresAt). Resuming after a wrong answer includes each question's guide.
   - Errors: build_reward_not_scheduled when the rule has no questions for today; build_reward_daily_claims_reached when the viewer already earned today’s cap. attemptsRemaining is null for unlimited rules.
   - For a completion rule call start when the activity begins (the moment the stage starts); the challenge's age is what the claim is measured against. In preview mode start also works for the owner (a stateless simulation).
-- await Twinkle.rewards.claim({ challengeId, answers?: [number] }) | scopes: rewards:claim
+  - For completionProof: classic-tower-v1, start also returns completion { profile, token, maxFrames, completed, failed }. A new start resets only the simulated climb to its canonical spawn; it cannot reset daily or lifetime rewards. Record inputs from the first physics frame. The completion token is bound to the viewer, challenge, rule and published release.
+- await Twinkle.rewards.progress({ challengeId, completionToken, frames }) | scopes: rewards:claim
+  - Returns: { mode: "live" | "preview", completion: { profile: "classic-tower-v1", token, maxFrames, completed, failed } }
+  - Verify a bounded batch of inputs for an approved server-simulated climb.
+  - Only for completionProof: classic-tower-v1. Send 1 to 600 chronological physics frames, each [dt, moveX, moveY, cameraForwardX, cameraForwardZ, jumpPressed, jumpHeld, speedMultiplier]. dt is in seconds, at most 0.05; movement axes are -1 through 1; the camera values are the horizontal components before normalization; jump flags are 0 or 1; speedMultiplier is an existing Classic Tower trail speed (1, 1.1, 1.2, 1.3, 1.35 or 1.4). Geometry and player state are owned by the registered server simulation.
+  - Send occasional batches with at most one request in flight. Keep the previous token and the exact batch until a response confirms it; an identical retry is safe. Use the returned token for the next batch. Simulation time cannot outrun wall time. A completed token is evidence of a legal simulated run, not proof that a human played or that inputs were not automated.
+  - On respawn or a return from another world, begin a fresh run at the canonical spawn via start. Preserve other worlds and gameplay. Do not submit positions, scores, secret keys, or a client completion flag. Preview tokens can never be redeemed in the published app.
+- await Twinkle.rewards.claim({ challengeId, answers?: [number], completionToken?: string }) | scopes: rewards:claim
   - Returns: { awarded: false, attempts, attemptsRemaining, questions: [{ prompt, hint?, guide? }] } | { awarded: true, duplicate, receipt: { ruleId, xp, coins, attempt, firstTry }, questions: [{ prompt, hint?, guide? }], balances: { xp, coins } }
   - Twinkle verifies every answer, approval, current published artifact and budget before atomically recording XP and Coins. The receipt’s xp/coins are what was actually paid: the full amounts on a first try, the retry share after a wrong answer (attempt > 1). Retry the same challengeId after a lost response; a confirmed claim returns its original receipt without another award. Never update balance UI optimistically. Under retry.paidAttempts a correct answer past that attempt returns awarded: true with a zero receipt: solved, not paid.
   - Every claim response, wrong or right, returns the questions with their guides unlocked: show the teaching content right after the first answer. Answer keys are never returned.
   - A wrong answer within two seconds of the previous one is refused with build_reward_throttled (HTTP 429) and does not count; wait for the person to try again rather than retry-looping.
   - Completion rules take no answers: claim({ challengeId }) when the activity is finished. build_reward_too_fast (HTTP 409) means fewer than minSeconds passed since start; show nothing and let play continue. In preview mode the receipt carries preview: true and nothing is paid.
+  - A completionProof rule also requires the signed completionToken from a successful rewards.progress response. The server simulates the registered game physics and must reach the goal. A timer, forged position, client win flag, altered inventory or token from another viewer, challenge or release cannot authorize payment. maxLifetimeClaims is enforced from receipts in the same award transaction. build_reward_lifetime_claims_reached means all rewards for this rule have been collected; do not retry it.
 - await Twinkle.rewards.getLeaderboard({ metric?: "xp" | "coins", period?: "day" | "week" | "all", limit? }) | scopes: rewards:claim
   - Returns: { mode: "live", metric, period, limit, dayKey, from, available: { xp, coins }, entries: [{ rank, userId, username, profilePicUrl, xp, coins, claims, lastAt }], me: { rank, xp, coins, claims } | null } | { mode: "preview", metric, period, available, entries: [], me: null, message }
   - Standings of who earned the most XP or Coins in THIS app, computed by Twinkle from its own receipts (never from anything the app submits). period 'day' is today (site day, UTC), 'week' the last 7 site days, 'all' (default) every day since approval. limit defaults to 20, max 100.

package/sdk/LUMINE_ADMIN.md

@@ -1143,17 +1143,18 @@ Review questions to settle with Mikey before approving:
   it, then the next one comes up the following site day (UTC midnight, 9:00 AM Korea)) keep them honest.
 - Do the rule IDs in `rewards.json` match what the code starts? Unknown IDs
   simply never pay.
-- Are the amounts and the per-user, per-app and lifetime budgets conservative
-  for what the app actually asks of people?
+- Are the amounts and the per-learner daily budgets right for what the app
+  actually asks of people? There is no app-wide budget, per day or lifetime:
+  a good app keeps paying everyone who plays it. Older configs may still
+  carry `dailyXP`/`dailyCoins`/`lifetimeXP`/`lifetimeCoins`; the API accepts
+  and ignores them, so never add or tune them.
 
 `rules.json` (what `--config` takes, and what the app's `rewards.json` plus
 sheet compose into):
 
 ```json
 {
-  "dailyXP": 2000000, "dailyCoins": 0,
   "userDailyXP": 10000, "userDailyCoins": 0,
-  "lifetimeXP": 200000000, "lifetimeCoins": 0,
   "rules": [
     { "id": "stage-1", "title": "Clear Stage 1", "xp": 300, "coins": 0,
       "verifier": "completion", "minSeconds": 20 },
@@ -1191,8 +1192,8 @@ day, elementary 50,000 XP + 1,000 Coins, middle 70,000 + 5,000, high
 `userDailyClaims` 1; until-earned sets authored from the Korean curriculum.
 Arcade Typing (Mikey, 2026-09-12): XP for clearing campaign stages, up to
 10,000 XP per learner per day, no Coins. Platform ceilings: 100,000 XP /
-10,000 Coins per rule and per learner per day, 10,000,000 XP / 1,000,000 Coins
-per app per day, 1,000,000,000 XP / 100,000,000 Coins per app lifetime.
+10,000 Coins per rule and per learner per day. No app-wide ceiling exists,
+per day or lifetime.
 
 Approval freezes these rules with the reviewed snapshot and publishes that
 snapshot immediately (the result carries `published.version`); an approval
@@ -2670,6 +2671,24 @@ Read every line, and put these in the daily report verbatim:
   line;
 - the `day-over-day … worker_heap=…` delta.
 
+**The memory report looks back only 24 hours; the run's window is often longer.**
+On 2026-09-19 a four-day window hid two heap-OOM aborts (09-16 and 09-17) that
+`memory-daily` no longer showed. In every full review, also search the reviewed
+error log for `[cluster] worker exited` lines that are not planned or operator
+recycles, across the whole window since the last completed full run, and treat
+each one exactly like a non-zero `oom_aborts` / `unexpected_worker_exits`.
+
+Each unexpected exit is followed by a `[cluster] worker last work slot=… pid=…
+in_flight=[…] recent=[…]` line (added 2026-09-19). The worker writes that trail
+synchronously as each piece of work begins and ends, so it survives an abort
+inside a single synchronous burst. `in_flight` names the requests or socket
+events that were running when the process died; `recent` lists the last
+sixteen begin/label/end records with their age before exit. Quote both lists
+verbatim in the report and in the todo: they are the evidence that pinpoints
+the code path. `unavailable (no trail file)` means the worker died before its
+trail existed or an older generation is still running; say so rather than
+guessing.
+
 Escalate in the report (a todo, and a note for Mikey) when any of these hold:
 `oom_aborts` > 0, `service_restarts` > 0, `unexpected_worker_exits` > 0, any
 worker `heap_high_water_pct` ≥ 95, or `heap_recycles` ≥ 4 in a day (the
@@ -2976,6 +2995,33 @@ Mikey"** section carrying only
 the deltas and anomalies worth his time, next to the escalation list. Never
 dump raw sections at him.
 
+### Jev shadow pilot (standing duty, every full daily review; added 2026-09-19)
+
+Read `data.jevPilot` from `lumine admin brief --json` and carry it into
+the full report for Mikey. The active `daily-run report --json` also includes
+`data.report.brief.jevPilot`. This duty does not authorize a separate full run.
+If the deployed API lacks the field, say the telemetry is not deployed; do not
+treat a missing section as zero traffic or a healthy pilot.
+
+State the configuration and operating status even when off/blocked/awaiting
+samples. Headline the named last completed UTC day, compare with the trailing
+seven completed days, and keep the in-progress day separate. Include paired
+decision counts, disagreements (especially Jev react / baseline respond),
+p50/p95 latency for each model, provider errors/timeouts, pending observations,
+known incremental cost, unknown-cost requests, ledger gaps and cap status.
+The pilot's known recorded spend is already in application AI costs: never add
+it again. Shadow mode changes no user-visible decisions and has not established
+savings. Agreement is not accuracy; confidence is not a measured success rate.
+
+Privately inspect the bounded `reviewCandidates` when needed, name what was
+actually reviewed, and account for edited comments. Ordinary model disagreements
+are evaluation findings; outages, stuck telemetry or missing ledger entries are
+operational findings. Report a recommendation to continue, adjust or stop, without
+automatically enabling traffic, raising caps or promoting Jev to serving. Data
+handling for under-18 users and TypeSafe account access must be resolved before
+real conversations are sent. See `twinkle-api/JEV_PILOT.md` for configuration,
+the synthetic evaluation step and release checks.
+
 ### Application AI calendar-month cost (standing duty, every full daily review)
 
 Run `lumine admin ai-costs monthly --json` during every full daily management