@stage5/lumine 0.3.82 → 0.3.83

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

@@ -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.82",
+  "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