@stage5/lumine 0.2.67 → 0.2.69

package/README.md

@@ -387,6 +387,17 @@ lumine admin subject unfeature 123 --json
 lumine admin featured reorder --subject-ids 30,20,10 --json
 lumine admin featured rotate --remove-subject-ids 30,20 \
   --add-subject-ids 50,40 --json
+lumine admin featured plan --remove-subject-ids 30,20 \
+  --add-subject-ids 50,40 --subject-ids 40,50,10 \
+  --posted-after 2026-09-01T00:00:00+07:00 --output featured-plan.json --json
+# Only after Mikey approves the exact mapping and final order:
+lumine admin featured apply --file featured-plan.json --approve <exact-plan-hash> --json
+lumine admin featured comments scan --checkpoint featured-read.json --json
+# Read every page file before acknowledging; downloads are not reviews.
+lumine admin featured comments acknowledge --checkpoint featured-read.json --reviewed --json
+lumine admin featured comments recommend --file featured-decisions.json \
+  --checkpoint featured-recommend.json --json
+lumine admin featured comments report --checkpoint featured-read.json --json
 lumine admin brief --days 3 --json
 lumine admin notable add Minecrarft_guy --note "Created 8 thoughtful subjects and helped peers in 23 comments this window." --json
 lumine admin post recommend comment:456 --anyone-can-reward --reward-twinkles 3 --json
@@ -418,7 +429,9 @@ Zero/Ciel responder without Lumine remaining active.
 
 `--scope full` is the default and authorizes the complete daily-management
 workflow. `--scope featured` is a deliberately narrow run for a requested
-Featured-only slice: it cannot comment, does not surface carry-over todos, does
+Featured-only slice: it can review and encourage snapshot-bound Featured
+comments, but cannot publish comments or use generic recommendation/reward
+commands. It does not surface carry-over todos, does
 not write full-run queue coverage, does not require sponsor review, and never
 advances full-run review windows. Its dedicated start endpoint also prevents an
 older API from silently interpreting it as a full run. The
@@ -427,6 +440,18 @@ the server to prove both a strict posting-date boundary and complete
 never-Featured history. `featured history` returns that evidence without the
 large repeated board snapshots in the general audit trail.
 
+`featured plan`/`apply` bind approval to the exact server-stored board and
+history revision; all approved replacements and ordering commit together.
+Equal-size swaps and reorders support the website's 100-Subject capacity while
+delegated growth remains capped at 20. The CLI verifies the final live order.
+`featured comments scan` walks every thread (including old/nested replies),
+with private, hashed pages and `--resume` recovery. `acknowledge --reviewed`
+records actual reading separately from downloading. `recommend` applies only
+agent-selected comments from acknowledged threads, with reward eligibility off
+by default, and resumes the exact decision file/checkpoint safely. See
+[the admin contract](sdk/LUMINE_ADMIN.md#exact-approved-refresh-and-resumable-comment-encouragement)
+for the decision-file format, partial-coverage rules, and deployment prerequisites.
+
 Management agents also inspect recent public Build candidates during each full
 daily review.
 `builds review` opens one published app in an isolated temporary Chromium

package/lib/admin-featured-history.js

@@ -0,0 +1,185 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { readAdminJsonFile, writeAdminJsonFile } from "./admin-news.js";
+import {
+  acquireCheckpointLock,
+  releaseCheckpointLock,
+  runAutomaticPagination,
+  combinePaginatedResults,
+  writePaginatedResultFile,
+} from "./admin-workflows.js";
+
+// API read bound, deliberately unrelated to the delegated addition policy.
+export const FEATURED_HISTORY_BATCH_SIZE = 100;
+
+function invalid(message) {
+  const error = new Error(message);
+  error.code = "CLI_ADMIN_CLI_VALIDATION";
+  return error;
+}
+
+export async function runBatchedFeaturedHistory(args) {
+  const { options, operation, runId } = args;
+  if (options.adminCursor) {
+    throw invalid("Use --resume with --all, not a single-batch --cursor.");
+  }
+  const subjectIds = operation.pagination.filters.subjectIds;
+  const fingerprint = createHash("sha256")
+    .update(
+      JSON.stringify({
+        version: 1,
+        runId,
+        apiUrl: options.apiUrl,
+        path: operation.path,
+      }),
+    )
+    .digest("hex");
+  const checkpointPath = path.resolve(
+    options.adminCheckpoint ||
+      path.join(
+        os.tmpdir(),
+        `lumine-admin-run-${runId}-featured-history-${fingerprint}.json`,
+      ),
+  );
+  const outputPath = options.adminOutput
+    ? path.resolve(options.adminOutput)
+    : null;
+  if (
+    outputPath === checkpointPath ||
+    outputPath?.startsWith(`${checkpointPath}.`)
+  ) {
+    throw invalid(
+      "History output must not overwrite its checkpoint or batch files.",
+    );
+  }
+  const lock = acquireCheckpointLock(checkpointPath, fingerprint);
+  try {
+    let generation;
+    if (options.adminResume) {
+      const saved = readAdminJsonFile(
+        checkpointPath,
+        "the Featured history batch checkpoint",
+      );
+      if (
+        saved.kind !== "featured-history-batches" ||
+        saved.fingerprint !== fingerprint ||
+        !/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(
+          saved.generation || "",
+        )
+      ) {
+        throw invalid(
+          "The checkpoint does not belong to this run and exact history request.",
+        );
+      }
+      generation = saved.generation;
+    } else {
+      generation = randomUUID();
+      writeAdminJsonFile(
+        checkpointPath,
+        { kind: "featured-history-batches", fingerprint, generation },
+        { privateFile: true },
+      );
+    }
+    const results = [];
+    for (
+      let offset = 0;
+      offset < subjectIds.length;
+      offset += FEATURED_HISTORY_BATCH_SIZE
+    ) {
+      const ids = subjectIds.slice(
+        offset,
+        offset + FEATURED_HISTORY_BATCH_SIZE,
+      );
+      const batchIndex = offset / FEATURED_HISTORY_BATCH_SIZE;
+      const batchCheckpoint = `${checkpointPath}.${generation}.batch-${batchIndex}.json`;
+      const url = new URL(operation.path, "https://lumine.invalid");
+      url.searchParams.set("subjectIds", ids.join(","));
+      const result = await runAutomaticPagination({
+        ...args,
+        options: {
+          ...options,
+          adminOutput: undefined,
+          adminCheckpoint: batchCheckpoint,
+          adminResume: !!options.adminResume && existsSync(batchCheckpoint),
+        },
+        operation: {
+          ...operation,
+          path: `${url.pathname}${url.search}`,
+          pagination: { ...operation.pagination, filters: { subjectIds: ids } },
+        },
+      });
+      if (
+        JSON.stringify(result.data.subjects?.map((subject) => subject.id)) !==
+        JSON.stringify(ids)
+      ) {
+        throw invalid(
+          "The API did not return a canonical summary for every requested subject.",
+        );
+      }
+      results.push(result);
+    }
+    const firstCoverage = results[0].data.coverage;
+    const uniformCoverage = results.every(
+      (result) =>
+        result.data.coverage?.complete === firstCoverage.complete &&
+        result.data.coverage?.startedAt === firstCoverage.startedAt,
+    );
+    const result = combinePaginatedResults(
+      {
+        ok: true,
+        status: "success",
+        data: {
+          coverage: uniformCoverage
+            ? firstCoverage
+            : { complete: false, startedAt: null },
+          subjects: results.flatMap((result) => result.data.subjects),
+          pagination: {
+            nextCursor: null,
+            hasMore: false,
+            exhausted: true,
+            snapshotMaxId: null,
+            snapshotTimeStamp: null,
+            after: null,
+            snapshotScope: "per-batch",
+            eventOrder: "subject-batch-then-id-descending",
+          },
+          scan: {
+            checkpointPath,
+            resumed: !!options.adminResume,
+            pages: results.reduce(
+              (sum, result) => sum + result.data.scan.pages,
+              0,
+            ),
+            scannedCount: results.reduce(
+              (sum, result) => sum + result.data.scan.scannedCount,
+              0,
+            ),
+            candidateCount: results.reduce(
+              (sum, result) => sum + result.data.scan.candidateCount,
+              0,
+            ),
+            batches: results.map((result, index) => ({
+              subjectIds: subjectIds.slice(
+                index * FEATURED_HISTORY_BATCH_SIZE,
+                (index + 1) * FEATURED_HISTORY_BATCH_SIZE,
+              ),
+              coverage: result.data.coverage,
+              pagination: result.data.pagination,
+              scan: result.data.scan,
+            })),
+          },
+        },
+      },
+      results,
+    );
+    if (outputPath) {
+      result.data.scan.outputPath = outputPath;
+      await writePaginatedResultFile(outputPath, result);
+    }
+    return result;
+  } finally {
+    releaseCheckpointLock(lock);
+  }
+}