@stage5/lumine 0.3.81 → 0.3.82

package/lib/admin-arena.js

@@ -13,6 +13,9 @@ import path from "node:path";
 //                              at once; a dry run (validation only) unless --confirm;
 //                              re-importing a folder retires that paper's earlier items
 //   status --item <id> --to live|retired|checked
+//   revise --file <revisions.json>   in-place text/passage/visual/review fixes to
+//                              live items: same item id, a new content version;
+//                              a dry run unless --confirm; audited
 //   today-withdraw --user <id> (--keys <k,...> | --file <withdraw.json>) --reason <text>
 //                              withdraw that member's unserved queued Today's
 //                              Challenge questions (preview unless --confirm; audited)
@@ -22,7 +25,7 @@ import path from "node:path";
 //                              <itemId>.png renders of picture-option items
 //                              (panels are drawn by the web, not stored)
 export const ARENA_USAGE =
-  "Usage: lumine admin arena queue | paper-queue [--cursor <id>] [--limit <1-100>] | marking [--cursor <id>] [--limit <1-200>] | import (--dir <paper folder> | --additive --file <reviewed-items.json>) [--audio audio/<exam>/<paper>] [--live] [--confirm] | status --item <id> --to live|retired|checked [--confirm] | today-queue [--cursor <id>] [--limit <1-100>] | today-member --user <id> | today-import --file <reviewed-questions.json> [--confirm] | today-withdraw --user <id> (--keys <key,...> | --file <withdraw.json>) --reason <text> [--confirm] | picture-audit [--items <id,id,...> | --cursor <id>] [--limit <1-20>] [--renders <dir of <itemId>.png>] [--output <review-list.json>] [--json]";
+  "Usage: lumine admin arena queue | paper-queue [--cursor <id>] [--limit <1-100>] | marking [--cursor <id>] [--limit <1-200>] | import (--dir <paper folder> | --additive --file <reviewed-items.json>) [--audio audio/<exam>/<paper>] [--live] [--confirm] | status --item <id> --to live|retired|checked [--confirm] | revise --file <revisions.json> [--confirm] | today-queue [--cursor <id>] [--limit <1-100>] | today-member --user <id> | today-import --file <reviewed-questions.json> [--confirm] | today-withdraw --user <id> (--keys <key,...> | --file <withdraw.json>) --reason <text> [--confirm] | picture-audit [--items <id,id,...> | --cursor <id>] [--limit <1-20>] [--renders <dir of <itemId>.png>] [--output <review-list.json>] [--json]";
 const MAX_ITEMS = 300;
 
 function validationError(message) {
@@ -256,6 +259,32 @@ export function buildArenaOperation({ action, options }) {
       timeoutMs: 120000,
     };
   }
+  if (action === "revise") {
+    if (!options.adminFile) throw validationError("Use revise --file <revisions.json> [--confirm].");
+    const file = path.resolve(options.adminFile);
+    let parsed;
+    try {
+      if (fs.statSync(file).size > 5_000_000) throw validationError("The revision file must be under 5 MB.");
+      parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch (error) {
+      if (error.code === "CLI_ADMIN_CLI_VALIDATION") throw error;
+      throw validationError(`Cannot read the revision file ${file}: ${error.message}`);
+    }
+    const items = Array.isArray(parsed) ? parsed : parsed?.items;
+    if (!Array.isArray(items) || !items.length || items.length > MAX_ITEMS) {
+      throw validationError(`A revision file holds 1 to ${MAX_ITEMS} revisions: an array, or {reason, items:[...]}.`);
+    }
+    const confirm = confirmed(options);
+    return {
+      name: confirm ? "arena.revise" : "arena.revise.preview",
+      method: "POST",
+      path: "/cli/admin/arena/items/revise",
+      body: { items, ...(typeof parsed?.reason === "string" ? { reason: parsed.reason } : {}), dryRun: !confirm },
+      mutates: confirm,
+      requiresRun: false,
+      timeoutMs: 120000,
+    };
+  }
   if (action === "status") {
     const id = Number(options.adminArenaItem);
     const to = String(options.adminArenaTo || "");
@@ -337,6 +366,16 @@ export function formatArenaResult({ operation, data }) {
       due.length ? `${due.length} type(s) due for a refill.` : "No standalone practice refill due; check paper-queue for waiting exams.",
     ];
   }
+  if (operation.name === "arena.revise.preview" || operation.name === "arena.revise") {
+    const revised = data?.revised || [];
+    const unchanged = data?.unchanged || [];
+    return [
+      `${data?.dryRun ? "Dry run: would revise" : "Revised"} ${revised.length} item(s)${unchanged.length ? `; ${unchanged.length} already as written` : ""}.`,
+      ...revised.map((r) => `Item ${r.itemId}${r.paper ? ` (${r.paper} #${r.number})` : r.number ? ` (#${r.number})` : ""}: v${r.fromVersion} -> v${r.toVersion}, ${r.changed.join(", ")}${r.fromPassageVersion !== r.toPassageVersion ? `; passage ${r.passageId} v${r.fromPassageVersion} -> v${r.toPassageVersion}` : ""}`),
+      ...unchanged.map((r) => `Item ${r.itemId}: ${r.status === "already_applied" ? "already revised" : "no change"} (v${r.version})`),
+      ...(data?.dryRun && revised.length ? ["Add --confirm to publish these versions."] : []),
+    ];
+  }
   if (operation.name === "arena.import.preview") {
     return [`Dry run: ${data?.wouldImport ?? 0} item(s) pass validation. Add --confirm to import.`];
   }

package/lib/commands.js

@@ -3351,7 +3351,7 @@ export function printHelp() {
   lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]
   lumine admin craft seed --build <id> --file <pairs.json> [--confirm] | stats --build <id> [--limit <1-100>] | revise --build <id> --item <id|name> [--why <text>] [--emoji <emoji>] [--category <field>] [--confirm] | revise --build <id> --pair <pairId|a+b> --why <text> [--confirm] | retire --build <id> --item <id|name> --reason <text> [--confirm] | unfizzle --build <id> [--since <iso>] [--pair <a+b>] [--confirm]   (Twinkle.craft curation: dry run without --confirm)
   lumine admin sliding-block status | add --file <levels.json> [--confirm]   (sliding-block-v1 campaign refills, RushHour: dry run without --confirm; the server solves each board and appends it)
-  lumine admin arena queue | paper-queue [--cursor <id>] [--limit <1-100>] | import --dir <paper folder> [--audio audio/<exam>/<paper>] [--live] [--confirm] | status --item <id> --to live|retired|checked --confirm | picture-audit [--items <id,id,...> | --cursor <id>] [--limit 1-20] [--renders <dir of <itemId>.png>] [--output <review-list.json>]   (Arena's mock-exam bank; picture-audit is an advisory JEV image review list that never retires or edits items; import is a validation-only dry run without --confirm; upload audio first with twinkle-api scripts/arena-upload-media.ts)
+  lumine admin arena queue | paper-queue [--cursor <id>] [--limit <1-100>] | import --dir <paper folder> [--audio audio/<exam>/<paper>] [--live] [--confirm] | status --item <id> --to live|retired|checked --confirm | revise --file <revisions.json> [--confirm] | picture-audit [--items <id,id,...> | --cursor <id>] [--limit 1-20] [--renders <dir of <itemId>.png>] [--output <review-list.json>]   (Arena's mock-exam bank; picture-audit is an advisory JEV image review list that never retires or edits items; import and revise are validation-only dry runs without --confirm; revise fixes a live item in place as a new content version; upload audio first with twinkle-api scripts/arena-upload-media.ts)
   lumine admin arena today-queue [--cursor <id>] | today-member --user <id> | today-import --file <reviewed-questions.json> [--confirm] | today-withdraw --user <id> (--keys <key,...> | --file <withdraw.json>) --reason <text> [--confirm]   (Today's Challenge personal queues; import and withdraw are dry runs without --confirm; withdraw removes only unserved queued questions and is audited)
   lumine admin nonogram status | add --file <pictures.json> | retire <key> | restore <key> [--confirm]   (private reviewed pictures; changes are dry runs without --confirm)
   lumine admin build-plans stuck [--days <1-90>] [--all] | recheck <buildId> [<buildId> ...] [--confirm]   (Lumine Build plans stuck on one milestone: runs, Energy vs estimate, gradings, loop-guard state; recheck re-grades the current milestone with today's evaluator, free for the creator, dry run without --confirm)

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -5695,6 +5695,71 @@ Bridge Builder qualifies from QR check-ins: 7 different people, or one meetup a
 Every decision requires Mikey's authorization for that crew and action. Mutations are audited and idempotent; `--output <path>` is an explicit request to retain the canonical JSON. General write receipts omit private crew details.
 
 
+## Arena timed-bank item revisions
+
+Reviewed text, option and visual fixes to a published paper go live in place, without
+re-importing the paper:
+
+```
+lumine admin arena revise --file <revisions.json> --json
+lumine admin arena revise --file <revisions.json> --confirm --json
+```
+
+The file is `{ "reason": "...", "items": [ { "itemId": <live id>,
+"expectedVersion": <version you read>, "paper": "<edition>", "number": <n>,
+"content": { "stem", "body", "choices", "answer", "accepted",
+"transformation", "review", "visual", "passage" (any subset) }, "reason": "...", "review":
+"<options-only check + blind solve evidence>" } ] }` (or a bare array). `paper`
+and `number` are optional guards; a per-item `reason` overrides the file's.
+Without `--confirm` it is a dry run.
+
+- The item keeps its id, so exposures, question identity, paper completeness
+  and passed/solo exclusions are unchanged. The old content is archived as its
+  version and the item gets the next version. Finished papers, open sittings,
+  marking, review cards and drills keep the version they froze. A cover or
+  challenge prepared before the revision starts on the new version.
+- Stem, body, choices, key (`answer`, `accepted`, `transformation`), review,
+  visual and an existing unrecorded text passage can change. Set membership,
+  type, number, mode, rubric and recordings stay fixed. Changing choices, key,
+  passage or visual requires the full rewritten `content.review`. Its explanation
+  is non-empty text; optional `why` notes are an array of strings, one per choice.
+  Option reasoning may instead be included in the full explanation. The same
+  field types apply to a supplied Korean translation.
+- To change a passage, send `content.passage` and top-level
+  `expectedPassageVersion` for **every live/checked item sharing that passage**,
+  each with its own expected item version and review evidence. All siblings must
+  carry the identical new text. The entire set is validated, and the old passage
+  and item versions are archived in the same transaction. Old sittings and drills
+  keep their original text; new starts use the revised item and passage together.
+  A passage also used by a retired/draft item is refused, because its unchanged
+  version must retain its old text.
+  Use `visual: null` to remove a visual; supplied diagrams/charts must validate.
+- The result is checked with the import validators together with the rest of
+  its set (choice count, key index, `why` lines, evidence spans). A version
+  other than `expectedVersion`, a retired item, an essay/spoken task or any
+  invalid result refuses the whole file; nothing is written.
+- Confirmed runs are audited (`arena.items.revise`: operator, time, item ids,
+  reasons). Each item records the revision (versions, reason, evidence,
+  audit id) in its authoring. A retried request replays its receipt;
+  re-running an applied file reports `already applied` and writes nothing.
+- The new version starts its own calibration from the item's level, as on
+  import; the old version's calibration stays on record.
+
+### Ordered timed-review explanations
+
+Authored timed items may include `review.steps`: 1–8 ordered `{text, scene?}`
+pairs. `text` is 1–1600 characters; the whole sequence is bounded to 40,000
+characters. Keep `review.explanation` as the full readable fallback. The review
+screen and Zero/Ciel use these exact step numbers. A translated `review.ko`
+must provide the same number of aligned steps when explicit steps are used.
+
+Scenes use the existing `cards`, `bars` or `passage` contract (caption up to
+300 characters; 1–12 parts with text up to 1600 characters; bars need a finite
+value from 0 to 1,000,000), or the validated `diagram` contract with a required
+accessible `alt` (up to 200 characters). No executable markup or figure-plan
+placeholders. Render and review the actual scenes at phone size before import.
+Older text-only items retain the sentence-based step behavior.
+
 ## Arena Today's Challenge personal queues
 
 Each member who chose Today's Challenge preferences is served the oldest