@stage5/lumine 0.3.80 → 0.3.82

package/lib/admin-arena.js

@@ -13,13 +13,19 @@ 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)
 //   picture-audit [--items <ids> | --cursor <id>] [--limit 1-20] [--renders <dir>]
 //                              advisory JEV image review list of live picture
 //                              items; never retires or edits. --renders holds
 //                              <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] | 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) {
@@ -95,6 +101,58 @@ function readRenders(dir, itemIds) {
   return renders;
 }
 
+const TODAY_WITHDRAW_USAGE =
+  'Use today-withdraw --user <member id> (--keys <key,key,...> | --file <withdraw.json>) --reason "<why>" [--confirm].';
+const TODAY_WITHDRAW_MAX_KEYS = 100;
+
+// A withdrawal file is an array of keys, or an object with `keys` (or
+// `authorKeys`, or `items` of {key|authorKey}), an optional `userId` that must
+// match --user, and an optional `reason` used when --reason is absent.
+function readWithdrawFile(file, userId) {
+  const resolved = path.resolve(file);
+  let parsed;
+  try {
+    if (fs.statSync(resolved).size > 200_000) throw validationError("The withdrawal file must be under 200 KB.");
+    parsed = JSON.parse(fs.readFileSync(resolved, "utf8"));
+  } catch (error) {
+    if (error.code === "CLI_ADMIN_CLI_VALIDATION") throw error;
+    throw validationError(`Cannot read the withdrawal file ${resolved}: ${error.message}`);
+  }
+  const object = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  if (object?.userId !== undefined && Number(object.userId) !== userId) {
+    throw validationError(`The withdrawal file is for member ${object.userId}, not --user ${userId}.`);
+  }
+  const list = Array.isArray(parsed) ? parsed : object?.keys || object?.authorKeys || object?.items;
+  if (!Array.isArray(list)) throw validationError("The withdrawal file needs a list of question keys (an array, or {keys:[...]}).");
+  const keys = list.map((entry) => (typeof entry === "string" ? entry : entry?.authorKey ?? entry?.key));
+  return { keys, reason: typeof object?.reason === "string" ? object.reason : "" };
+}
+
+function buildTodayWithdraw(options) {
+  const userId = Number(options.adminUser);
+  if (!Number.isSafeInteger(userId) || userId <= 0) throw validationError(TODAY_WITHDRAW_USAGE);
+  const keyList = String(options.adminArenaKeys || "");
+  if (Boolean(keyList) === Boolean(options.adminFile)) throw validationError(`Pass exactly one of --keys or --file. ${TODAY_WITHDRAW_USAGE}`);
+  const fromFile = options.adminFile ? readWithdrawFile(options.adminFile, userId) : null;
+  const keys = fromFile ? fromFile.keys : keyList.split(",").map((key) => key.trim()).filter(Boolean);
+  if (!keys.length || keys.length > TODAY_WITHDRAW_MAX_KEYS ||
+      keys.some((key) => typeof key !== "string" || !/^[a-zA-Z0-9_-]{1,100}$/.test(key))) {
+    throw validationError(`Withdraw 1-${TODAY_WITHDRAW_MAX_KEYS} question keys (letters, digits, _ and -).`);
+  }
+  if (new Set(keys).size !== keys.length) throw validationError("Each question key may appear once.");
+  const reason = String(options.adminReason || fromFile?.reason || "").trim();
+  if (reason.length < 10 || reason.length > 500) throw validationError(`Give a 10-500 character --reason. ${TODAY_WITHDRAW_USAGE}`);
+  const confirm = confirmed(options);
+  return {
+    name: confirm ? "arena.today.withdraw" : "arena.today.withdraw.preview",
+    method: "POST",
+    path: "/cli/admin/arena/today/withdraw",
+    body: { userId, keys, reason, dryRun: !confirm },
+    mutates: confirm,
+    requiresRun: false,
+  };
+}
+
 export function buildArenaOperation({ action, options }) {
   if (action === "picture-audit") {
     const limit = Number(options.adminLimit ?? 10);
@@ -146,6 +204,7 @@ export function buildArenaOperation({ action, options }) {
     const confirm = confirmed(options);
     return { name: confirm ? "arena.today.import" : "arena.today.preview", method: "POST", path: "/cli/admin/arena/today/import", body: { ...payload, dryRun: !confirm }, mutates: confirm, requiresRun: false };
   }
+  if (action === "today-withdraw") return buildTodayWithdraw(options);
   if (action === "marking") {
     const cursor = Number(options.adminCursor || 0);
     const limit = Number(options.adminLimit ?? 100);
@@ -200,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 || "");
@@ -245,6 +330,16 @@ export function formatArenaResult({ operation, data }) {
   if (operation.name === "arena.today.preview" || operation.name === "arena.today.import") return [
     `${data?.dryRun ? "Dry run" : "Saved"}: ${data?.questions?.length || 0} reviewed personal questions.${data?.dryRun ? " Add --confirm to make new questions available." : ""}`,
   ];
+  if (operation.name === "arena.today.withdraw.preview" || operation.name === "arena.today.withdraw") {
+    const withdrawn = data?.withdrawn || [];
+    const skipped = data?.skipped || [];
+    return [
+      `${data?.dryRun ? "Dry run: would withdraw" : "Withdrew"} ${withdrawn.length} queued question(s) for member ${data?.userId}${withdrawn.length ? `: ${withdrawn.map((q) => q.key).join(", ")}` : ""}.`,
+      ...skipped.map((s) => `Skipped ${s.key}: ${s.reason} (${s.detail})`),
+      `Ready at preferences v${data?.revision ?? "-"}: ${data?.readyBefore ?? 0} before, ${data?.readyAfter ?? 0} after${data?.refillDue ? `; refill to ${data?.target}` : ""}.`,
+      ...(data?.dryRun && withdrawn.length ? ["Add --confirm to withdraw them."] : []),
+    ];
+  }
   if (operation.name === "arena.marking") {
     const entries = data?.entries || [];
     return [
@@ -271,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

@@ -2726,6 +2726,7 @@ export function parseArgs(args) {
     adminArenaTo: raw.to ? String(raw.to) : "",
     adminArenaRenders: raw.renders ? String(raw.renders) : "",
     adminArenaItems: raw.items ? String(raw.items) : "",
+    adminArenaKeys: raw.keys ? String(raw.keys) : "",
     // lumine admin jev-images (admin-jev-images.js)
     adminJevArea: raw.area ? String(raw.area) : "",
     adminJevKey: raw.key ? String(raw.key) : "",
@@ -3350,7 +3351,8 @@ 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)
   lumine admin storage list [--status pending|approved|rejected|all] [--cursor <id>] | show <user-id-or-username> | approve <request-id> [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <request-id> [--reason <text>] | grant <user-id-or-username> --size <500MB|1GB|2GB|n MB> [--reason <text>]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.80",
+  "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,109 @@ 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
+`ready`, never-shown question written for their current preference revision.
+Questions are prepared editorially (see the repository's
+`agent-guides/lumine-admin.md`, Today's Challenge personal refills, for the
+content rules, including the 11-03 no-answer-revealing-options and real-test
+coverage rules).
+
+```
+lumine admin arena today-queue [--cursor <id>] [--limit <1-100>] --json
+lumine admin arena today-member --user <id> --json
+lumine admin arena today-import --file <reviewed-questions.json> [--confirm] --json
+lumine admin arena today-withdraw --user <id> (--keys <key,key,...> | --file <withdraw.json>) --reason "<why>" [--confirm] --json
+```
+
+`today-import` validates without publishing; `--confirm` publishes. Keys and
+content are immutable and duplicate questions are rejected.
+
+`today-withdraw` removes that member's unserved queued questions that failed
+review, so corrected replacements are not served behind them. Without
+`--confirm` it is a preview. It withdraws only `ready` questions never assigned
+to the member; a question shown today or on an earlier day is skipped as
+`served`, and keys are looked up only in that member's queue (another member's
+key reads as `not_found`). Already-withdrawn keys are skipped, so a repeat is a
+no-op, and a retried request replays its original receipt. Each confirmed run is
+recorded in the administrator audit log (operator, time, member, keys, reason),
+and each withdrawn question keeps that record in its review evidence. The result
+lists `withdrawn` and `skipped` keys (`not_found`, `already_withdrawn`, `served`,
+`not_ready`) with `readyBefore`/`readyAfter` at the current preference revision.
+Withdrawn questions are never served or counted as ready. Their keys stay
+reserved and the identical question cannot be imported again; import the
+corrected version under a new key (it may keep the same passage and prompt).
+A withdrawal file is a JSON array of keys, or `{ "userId": <id>, "keys": [...],
+"reason": "..." }` (`userId` must match `--user`; `--reason` overrides the
+file's reason). Re-read `today-member` afterwards and refill if the member is
+due.
+
 ## Nonogram picture collection
 
 Nonogram's `nonogram-picture-v1` proof uses a private, reviewed picture bank.