@stage5/lumine 0.3.58 → 0.3.59

package/README.md

@@ -134,6 +134,15 @@ version, records the same save metadata, and marks public builds as having
 unpublished changes. For projects you own, run `lumine launch` to publish the
 saved changes, or `lumine save --publish` to save and publish in one step.
 
+For automation, `lumine save --json` emits one canonical JSON receipt with
+`schemaVersion`, `ok`, the saved artifact metadata, `build`, and `publication`.
+`lumine versions --json` returns the server's version history without prose.
+If `save --publish --json` saves successfully but publication fails, the receipt
+still identifies that saved version, sets `ok: false`, and reports the publication
+error; the command exits nonzero. A contribution branch reports
+`publication.published: false` with `reason: "contribution_requires_owner"`.
+Saving a branch does not publish the owner's app.
+
 Pulled workspaces include `AGENTS.md` and `CLAUDE.md` guides for local coding
 agents, `TWINKLE_BUILD_SDK.md` with the current Build SDK reference, plus
 `.twinkle/lumine-project.json` metadata that tells agents whether the checkout

package/lib/admin.js

@@ -5877,8 +5877,14 @@ function printAdminMonthlyAiCosts(monthlyAiCosts) {
 
 function printAdminDailyAiCosts(dailyAiCosts) {
   console.log(
-    `Application AI-cost ledger for ${dailyAiCosts.day.dayKey} (closed UTC day): ${formatAdminUsd(dailyAiCosts.summary?.estimatedCostUsd)} across ${Number(dailyAiCosts.summary?.requestCount || 0)} request(s).`,
+    `Application AI usage before credits for ${dailyAiCosts.day.dayKey} (closed UTC day): ${formatAdminUsd(dailyAiCosts.summary?.estimatedCostUsd)} across ${Number(dailyAiCosts.summary?.requestCount || 0)} request(s).`,
   );
+  const credit = dailyAiCosts.creditAccounting;
+  if (credit?.status === "estimated" && Number.isFinite(credit.creditUsd) && Number.isFinite(credit.estimatedCashUsd)) {
+    console.log(`Promotional credit: ${formatAdminUsd(credit.creditUsd)}; estimated cash cost: ${formatAdminUsd(credit.estimatedCashUsd)}.`);
+  } else {
+    console.log("Promotional credit and estimated cash cost unavailable; the usage total above is before credits.");
+  }
   for (const row of dailyAiCosts.byProviderModel || []) {
     console.log(
       `  ${row.provider || "unknown"}/${row.model || "unknown"}: ${formatAdminUsd(row.estimatedCostUsd)} · ${Number(row.totalTokens || 0)} token(s) · ${Number(row.requestCount || 0)} request(s).`,

package/lib/commands.js

@@ -1276,7 +1276,7 @@ export async function save(options) {
     lastSavedAt: new Date().toISOString(),
     filesHash: typeof result.filesHash === "string" ? result.filesHash : null,
   });
-  if (!options.quiet) {
+  if (!options.quiet && !options.json) {
     printSaveResult({
       result,
       build,
@@ -1286,14 +1286,31 @@ export async function save(options) {
     });
   }
 
+  const jsonReceipt = (publication = null, ok = true) => {
+    if (options.json && !options.quiet)
+      console.log(JSON.stringify({ ...result, schemaVersion: 1, ok, build, publication }));
+  };
   if (options.publish) {
     if (build?.canPublish === false) {
-      console.log(
+      if (!options.json) console.log(
         "Saved to your branch. The project owner can merge or replace main from Twinkle.",
       );
+      jsonReceipt({ published: false, reason: "contribution_requires_owner" });
+      return result;
+    }
+    let publish;
+    try { publish = await publishBuild({ options, buildId, auth }); }
+    catch (error) {
+      // Saving already succeeded. Preserve its exact receipt even if the
+      // separate publication fails; the command still exits nonzero.
+      jsonReceipt({ published: false, error: String(error?.message || error) }, false);
+      throw error;
+    }
+    if (options.json) {
+      build = publish.build || build;
+      jsonReceipt({ published: true, skipped: Boolean(publish.skipped), build: publish.build || null });
       return result;
     }
-    const publish = await publishBuild({ options, buildId, auth });
     if (publish.skipped) {
       console.log("Publish skipped: already up to date.");
     } else {
@@ -1304,6 +1321,7 @@ export async function save(options) {
     );
     console.log(`App: ${options.siteUrl}/app/${buildId}`);
   }
+  jsonReceipt();
   return result;
 }
 
@@ -1979,7 +1997,8 @@ export async function versionsCommand(options) {
     buildId,
     limit: options.limit,
   });
-  printVersionList({ result });
+  if (options.json) console.log(JSON.stringify(result));
+  else printVersionList({ result });
 }
 
 export function printVersionList({ result }) {
@@ -3196,7 +3215,7 @@ export function printHelp() {
   lumine pull [twinkle-build-url] --main
   lumine pull [twinkle-build-url] --version <n> [--main]
   lumine pull [twinkle-build-url] --published [--main]
-  lumine versions [twinkle-build-url] [--main] [--limit <n>]
+  lumine versions [twinkle-build-url] [--main] [--limit <n>] [--json]
   lumine restore <n> [--main]
   lumine reference <twinkle-build-url>
   lumine fork <twinkle-build-url>
@@ -3204,7 +3223,7 @@ export function printHelp() {
   lumine merge <twinkle-branch-url>
   lumine replace-main <twinkle-branch-url>
   lumine update-from-main [twinkle-branch-url]
-  lumine save
+  lumine save [--summary <text>] [--publish] [--json]
   lumine check [twinkle-build-url]
   lumine launch [twinkle-build-url]
   lumine sdk list

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -2,7 +2,7 @@
 
 Version: 1.68.0
 Updated: 2026-10-16
-Generated: 2026-10-22T07:54:40.033Z
+Generated: 2026-10-23T06:17:07.718Z
 
 ## Notes
 - Reward is part of completion: a reward-paying run must stay pending until awarded:true and its canonical receipt (or getReceipt status awarded). Do not show final solved/completed status, advance rewarded progress, or discard finished proof before that. Preserve the exact challenge/proof and acknowledged progress in a durable per-viewer outbox; reconcile getReceipt after a lost reply and retry the same challenge, never inventing a payment. Explain explicit practice, already collected, exhausted approved limits, preview and disclosed zero-value retry outcomes. Use the start response as a conservative elapsed-time reference, and test delayed start, network failure, lost claim reply, reload, day/viewer change and duplicate recovery.
@@ -1510,7 +1510,8 @@ world.updatePresence({ x, y, z, facing });
   - Pass null as expectedValue for an absent/null value. Both values are limited to 16 KB. Optional expectedUserId prevents a held operation from crossing an account change.
   - operationId is required: 8–64 letters, digits, underscores or hyphens. Reuse it for retries of the same logical change.
   - On conflict, rebase the intent onto the returned canonical item before comparing again. Do not retry-loop a 429.
-  - A duplicate operation returns the current canonical item without applying again. Ordinary set/remove remain unconditional; use a dedicated key for a compare-and-save workflow.
+  - An applied response confirms the save; use its canonical item as the next expectedValue. JSON storage may normalize floating-point numbers, so byte-for-byte equality with the submitted value is not a valid success check.
+  - A duplicate operation returns the current canonical item without applying again. matchesSubmittedValue is true when that current item equals this operation's submitted value after database normalization, and false if another save has since changed it. A receipt alone does not mean an older snapshot is still current. Ordinary set/remove remain unconditional; use a dedicated key for a compare-and-save workflow.
 
 ### Twinkle.reminders
 - async list({ includeDisabled, limit } = {}) | scopes: reminders:read
@@ -1579,7 +1580,7 @@ world.updatePresence({ x, y, z, facing });
   - For a paid nonogram-picture-v1 receipt, picture { title, category } may also be returned so the app can recover the reveal after a lost response. It contains no solution cells.
   - For collection practice, status:'completed' confirms a saved unpaid completion and includes completion { ruleId, setKey, at }, practice:true and receipt:null. Another challenge for the same personally completed collection set resolves to its existing receipt/completion, never a second payout.
 - await Twinkle.rewards.start({ ruleId, setKey?, levelIndex?, completionToken? }) | scopes: rewards:claim
-  - Returns: { mode: "live", challengeId, questions: [{ prompt, hint?, guide? }], setKey, reward: { xp, coins }, retryReward: { xp, coins }, attempts, maxAttempts, attemptsRemaining, firstTryAvailable, expiresAt }
+  - Returns: { mode: "live", challengeId, readyInSeconds?, questions: [{ prompt, hint?, guide? }], setKey, reward: { xp, coins }, retryReward: { xp, coins }, attempts, maxAttempts, attemptsRemaining, firstTryAvailable, expiresAt }
   - 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).
@@ -1587,6 +1588,7 @@ world.updatePresence({ x, y, z, facing });
   - For breadface-v1, breadface-v2 and breadface-v3, pass the zero-based canonical levelIndex. Record [dt, inputBits] from the first physics frame; start returns its server token and maxFrames. For study-record-v1, start returns completion { profile, usesAiEnergy: true }; there is no client-authored proof token. For groove-lab-song-v1, groove-lab-heard-v1, vigil-guest-coplay-v1, minecraft-first-link-v1 and writing-words-v1, start returns completion { profile }; there is no progress step. For groove-lab-listen-v1 and groove-lab-own-listen-v1, call start({ ruleId, completionToken: <published song entry id> }) when that song starts playing; it returns completion { profile, songEntryId, durationSeconds, listenSeconds } and refuses with a plain reason (not published, whose song, too short, already earned for this song today). Starting a different song re-binds the rule's unpaid challenge and restarts its clock. For reading-quiz-v1, call progress({ challengeId, completionToken: <chapter commentId>, record: 'open' }) when the reader opens the chapter (returns readyInSeconds, readingSeconds, alreadyEarned, attemptedToday), then progress({ ..., record: 'quiz' }) once readyInSeconds has passed to get questions [{ question, options[4] }] (never answers). getStatus returns reading { chaptersEarnedToday, readersToday } when the app uses a reading proof. For writing-words-v1, getStatus also returns writing { countedWords, checkingChapters, chapters: [{ commentId, words, countedWords, status: counted|not-counted|checking|duplicate|too-short, english, reason }] } for today. For sliding-block-v1, start deals the board (completion.board, positions, minMoves); render it, record each real slide as [ms, carIndex, newPosition], send moves with progress (frames up to maxFrames per call), then claim with the latest token. For app-check-v1, start returns completion { profile, puzzle }: show that puzzle (a repeat start of the same challenge returns the same one); there is no progress step.
   - 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.
 - 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.
@@ -1601,7 +1603,7 @@ world.updatePresence({ x, y, z, facing });
   - 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.
   - After a wrong answer, the next answer within two seconds, right or wrong, is refused with build_reward_throttled (HTTP 429): it does not count and says nothing about whether it was right. Keep the question open and let the person send it again after the wait; never treat a 429 as a wrong answer or retry-loop it.
   - Optional subject says what the reward was for; it is shown on the public bounty story on Home while the app is public (e.g. "listened to Night Drive"). title is plain text up to 80 characters, path is this app's share-link segment (the one you pass to Twinkle.app.getShareUrl, letters, digits and dashes), imageUrl a Twinkle-hosted image. A malformed subject is refused with build_reward_subject_invalid (HTTP 400); an older server without subjects ignores it. Proof-backed rules that read the item on the server (Groove Lab songs) replace it with the stored title, link, cover and creator.
-  - 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.
+  - 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. Preserve the finished proof, show reward pending, and schedule one retry using the start clock; let unrelated 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; every receipt counts, including one capped by the daily budget (cappedFrom). build_reward_lifetime_claims_reached means all rewards for this rule have been collected; do not retry it.
   - For study-record-v1, the server verifies the settled private review row and its viewer, app, exact release, challenge and day binding. It never trusts the client’s decision, requested award amount or AI answer. Each successful daily study record is claimable once; display only canonical receipt/balances. For groove-lab-song-v1, pass completionToken as the published song's sharedDb entry id; for groove-lab-heard-v1, pass none; for vigil-guest-coplay-v1, pass the guest's world guestId (from world events) or the co-play record id; for minecraft-first-link-v1, pass nothing or the Minecraft UUID to use; for reading-quiz-v1, pass completionToken as the chapter commentId and answers as the three chosen option indexes (all three must be right; a wrong attempt cannot be retried that day); for groove-lab-listen-v1 and groove-lab-own-listen-v1, pass the same song entry id after listenSeconds of foreground playback; for reading-readers-v1, pass nothing; for writing-words-v1, pass nothing (the server counts today's chapters itself and refuses with a plain reason, e.g. "320 of 500 counted words today" or "still being checked"). The server reads the app's own groove-lab-songs, groove-lab-song-parts and groove-lab-listens rows and refuses with build_reward_completion_proof_required and a plain reason when the song or listeners do not qualify.
   - For app-check-v1, pass completionToken as JSON.stringify(record), the record your check reads (at most 64 KB); the server deals the challenge again and runs the approved file's check before paying. A refused record returns { awarded: false, reason, attemptsRemaining } and uses a try; claim only when the app itself sees a finished solve.