@stage5/lumine 0.3.81 → 0.3.83

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/admin-featured-history.js

@@ -20,6 +20,46 @@ function invalid(message) {
   return error;
 }
 
+// Resolve once before pagination so every page uses the same canonical board.
+export function resolveCurrentFeaturedHistory({ operation, receipt, all }) {
+  const subjects = receipt?.data?.subjects;
+  if (
+    receipt?.ok !== true || receipt.status !== "success" ||
+    !Array.isArray(subjects) || receipt.data.count !== subjects.length ||
+    subjects.some((subject) => !Number.isSafeInteger(subject?.id) || subject.id < 1)
+  ) {
+    throw invalid("Could not read the canonical current Featured board; history was not requested.");
+  }
+  const subjectIds = subjects.map((subject) => subject.id);
+  if (new Set(subjectIds).size !== subjectIds.length) {
+    throw invalid("The current Featured board contains duplicate subject IDs; history was not requested.");
+  }
+  if (subjectIds.length > 20_000) {
+    throw invalid("Featured history accepts at most 20000 subject IDs per CLI scan.");
+  }
+  if (subjectIds.length > FEATURED_HISTORY_BATCH_SIZE && !all) {
+    throw invalid("The current Featured board has more than 100 subjects; pass --all to batch history reads.");
+  }
+  const url = new URL(operation.path, "https://lumine.invalid");
+  url.searchParams.set("subjectIds", subjectIds.join(","));
+  return {
+    ...operation,
+    path: `${url.pathname}${url.search}`,
+    pagination: {
+      ...operation.pagination,
+      summaryKeys: [...operation.pagination.summaryKeys, "subjectSelection"],
+      filters: { subjectIds },
+    },
+    featuredHistorySelection: {
+      source: "current-featured-board",
+      subjectIds,
+      message: subjectIds.length
+        ? `Defaulted to the current Featured board (${subjectIds.length} subjects).`
+        : "Defaulted to the current Featured board, which is empty; no history was requested.",
+    },
+  };
+}
+
 export async function runBatchedFeaturedHistory(args) {
   const { options, operation, runId } = args;
   if (options.adminCursor) {
@@ -135,6 +175,9 @@ export async function runBatchedFeaturedHistory(args) {
             ? firstCoverage
             : { complete: false, startedAt: null },
           subjects: results.flatMap((result) => result.data.subjects),
+          ...(operation.featuredHistorySelection
+            ? { subjectSelection: operation.featuredHistorySelection }
+            : {}),
           pagination: {
             nextCursor: null,
             hasMore: false,

package/lib/admin.js

@@ -86,6 +86,7 @@ import {
 } from "./admin-featured.js";
 import {
   FEATURED_HISTORY_BATCH_SIZE,
+  resolveCurrentFeaturedHistory,
   runBatchedFeaturedHistory,
 } from "./admin-featured-history.js";
 
@@ -1379,7 +1380,7 @@ export async function adminCommand(options) {
     if (result && result.ok === false) process.exitCode = 1;
     return result;
   }
-  const operation = parseAdminOperation(options);
+  let operation = parseAdminOperation(options);
   if (operation.name === "news.validate") {
     const validation = validateNewsEditorial({
       claim: operation.claim,
@@ -1607,15 +1608,54 @@ export async function adminCommand(options) {
       }
       return receipt;
     };
-    const transformResult = (rawResult) =>
-      transformAdminResult({
+    if (operation.featuredHistoryCurrentBoard) {
+      // The empty-board path skips pagination, but must preserve its files too.
+      if (options.adminAll && options.adminCheckpoint && options.adminOutput &&
+          path.resolve(options.adminCheckpoint) === path.resolve(options.adminOutput)) {
+        throw cliValidationError("The pagination checkpoint and result output must use different files.");
+      }
+      if (options.adminAll && options.adminCursor) {
+        throw cliValidationError("Use --resume with the scan checkpoint instead of combining --all with --cursor.");
+      }
+      if (options.adminResume && !options.adminAll) {
+        throw cliValidationError("--resume requires --all or post skip-batch.");
+      }
+      operation = resolveCurrentFeaturedHistory({
+        operation,
+        receipt: await fetchOperation("/cli/admin/subjects/featured"),
+        all: options.adminAll,
+      });
+      if (!operation.featuredHistorySelection.subjectIds.length && (options.adminResume || options.adminCursor)) {
+        throw cliValidationError("The current Featured board is empty; it cannot supply the subject IDs for a previous history scan. Use explicit --subject-ids for a fresh scan or cursor continuation.");
+      }
+    }
+    const transformResult = (rawResult) => {
+      const transformed = transformAdminResult({
         operation,
         result: rawResult,
         options,
         recommendationContentTypes,
         viewFilter,
       });
-    if (operation.name === "spending.report") {
+      return operation.featuredHistorySelection && transformed.ok
+        ? { ...transformed, data: { ...transformed.data, subjectSelection: operation.featuredHistorySelection } }
+        : transformed;
+    };
+    if (operation.featuredHistorySelection?.subjectIds.length === 0) {
+      // An empty board is canonical; there is no valid nonempty history query.
+      // Do not invent audit coverage or a history snapshot for this case.
+      result = {
+        ok: true,
+        status: "success",
+        data: {
+          subjectSelection: operation.featuredHistorySelection,
+          subjects: [],
+          events: [],
+          coverage: null,
+          pagination: { hasMore: false, exhausted: true, nextCursor: null },
+        },
+      };
+    } else if (operation.name === "spending.report") {
       result = await completeSpendingReport(await fetchOperation(), options);
       if (result.status === "partial") process.exitCode = 1;
     } else if (operation.featuredWorkflow) {
@@ -4395,10 +4435,10 @@ export function parseAdminOperation(options) {
       return readOperation("featured.list", "/cli/admin/subjects/featured");
     }
     if (action === "history") {
-      const subjectIds = parseFeaturedSubjectIds(
-        options.adminIds,
-        "--subject-ids",
-      );
+      const currentBoard = !String(options.adminIds || "").trim();
+      const subjectIds = currentBoard
+        ? []
+        : parseFeaturedSubjectIds(options.adminIds, "--subject-ids");
       if (subjectIds.length > 20_000) {
         throw cliValidationError(
           "Featured history accepts at most 20000 subject IDs per CLI scan.",
@@ -4420,6 +4460,7 @@ export function parseAdminOperation(options) {
           limit: options.limit,
         }),
         {
+          ...(currentBoard ? { featuredHistoryCurrentBoard: true } : {}),
           pagination: {
             collectionKey: "events",
             summaryKeys: ["coverage", "subjects"],
@@ -8442,6 +8483,10 @@ function printAdminResult({ operation, result }) {
 }
 
 function printFeaturedHistorySummary(data) {
+  if (data.subjectSelection) {
+    console.log(data.subjectSelection.message);
+    if (data.subjectSelection.subjectIds.length === 0) return;
+  }
   const coverage = data.coverage || {};
   console.log(
     coverage.complete

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)
@@ -3389,7 +3389,7 @@ export function printHelp() {
   lumine admin subject creator set-made-by-poster <subject-id> [--json]
   lumine admin subject feature|unfeature <subject-id> [--json]
   lumine admin featured list [--unviewed|--viewed] [--json]
-  lumine admin featured history --subject-ids <id,id,...> [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
+  lumine admin featured history [--subject-ids <id,id,...>] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
   lumine admin featured add --subject-ids <id,id,...> --posted-after <ISO-8601-or-Unix-time> [--json]
   lumine admin featured reorder --subject-ids <id,id,...> [--json]
   lumine admin featured rotate --remove-subject-ids <id,id,...> --add-subject-ids <id,id,...> [--posted-after <timestamp>] [--json]

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -2671,6 +2671,7 @@ lumine admin subject creator set-made-by-poster 123 --json
 lumine admin subject feature 123 --json
 lumine admin subject unfeature 123 --json
 lumine admin featured list --json
+lumine admin featured history --all --json # defaults to current Featured board
 lumine admin featured history --subject-ids 50,40 --all --json
 lumine admin featured add --subject-ids 50,40 \
   --posted-after 2026-08-27T00:00:00+07:00 --json
@@ -2789,6 +2790,8 @@ unknown/deleted IDs, missing current members, non-subject rows, and more than
 100 subjects. Permanent pins and editorial ordering policy are deliberately not
 hardcoded.
 
+When `lumine admin featured history` omits `--subject-ids`, the CLI reads the current Featured board once and requests history for those IDs in board order. Human output explicitly says that it defaulted to the current board; JSON and `--output` include `data.subjectSelection` with `source: "current-featured-board"`, `subjectIds`, and the same message. An empty board succeeds with empty subjects/events and `coverage: null`, explicitly stating that no history was requested. A failed or malformed board read fails rather than being treated as empty. Explicit `--subject-ids` keeps its existing behavior and skips the board read. Pagination retains the resolved IDs for the entire scan. A no-ID `--all --resume` requires the same board IDs in the same order; a changed board is rejected by checkpoint scope validation. If the board changes, use the previous result's explicit `subjectIds` for `--cursor`, or start a fresh `--all` scan with those IDs and a new checkpoint. An empty board cannot resume a prior scan or supply IDs for its cursor.
+
 `featured history` is the compact canonical evidence path. It returns only
 coverage metadata, per-subject lifetime summaries, and paginated mutation
 events; it does not repeat full audit before/after board snapshots. An event of
@@ -5695,6 +5698,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