@stage5/lumine 0.3.72 → 0.3.74

package/README.md

@@ -305,10 +305,11 @@ viewer sees (by default the MCP client's own name).
 ## Inspecting Build SDK data
 
 `lumine sdk call <namespace.method> '<jsonArgs>'` calls a build's data SDK
-endpoint with your login and prints the response, so you can inspect real data
+endpoint and prints the response, so you can inspect real data
 and measure latency while building. Run `lumine sdk list` to see callable
-methods. The JSON args are sent as the request body (shapes follow
-`TWINKLE_BUILD_SDK.md`).
+methods. Most methods use your login and send JSON args as the request body
+(shapes follow `TWINKLE_BUILD_SDK.md`). Newspaper reads use the same public
+GET routes as the app and send no login or Build API token.
 
 ```bash
 lumine sdk call aiStories.chapters '{"limit": 5}'
@@ -317,6 +318,9 @@ lumine sdk call live.list '{}'
 lumine sdk call live.get '{"sessionId": "..."}'
 lumine sdk call live.listReplays '{"limit": 20}'
 lumine sdk call live.getReplay '{"replayId": "..."}'
+lumine sdk call news.getCurrentEdition '{}' --build 1929
+lumine sdk call news.listEditions '{"limit": 12}' --build 1929
+lumine sdk call news.getEdition '{"dayIndex": 1762, "revisionNumber": 1}' --build 1929
 ```
 
 It targets the build in the current workspace, or pass `--build <id>`. Add
@@ -324,6 +328,10 @@ It targets the build in the current workspace, or pass `--build <id>`. Add
 which can differ from a method's `Twinkle.*` SDK return shape — check
 `TWINKLE_BUILD_SDK.md` for SDK return shapes. Methods that change data require
 `--allow-write`.
+For newspaper reads, omit `revisionNumber` to read the day's canonical revision;
+pass the archive's `cursor` to `news.listEditions` for the next page. These reads
+never queue generation or refresh an edition; publication uses the separate
+authorized newspaper workflow.
 Stopping a hosted stream is available as
 `lumine sdk call live.stop '{"sessionId":"..."}' --allow-write`; the command
 prints canonical server state and refuses to mint `live:write` without the

package/lib/admin-arena.js

@@ -186,12 +186,14 @@ export function formatArenaResult({ operation, data }) {
       ...types.map(
         (t) =>
           `${t.examFamily} ${t.difficulty || "normal"} ${t.itemType}: ${t.live} live, ${t.activeLearners ?? "unknown"} active learner(s), ${t.minFresh} unseen${
-            t.stockLow && !t.refillDue ? " (low stock; no active demand)" : ""
+            t.refillUse === "complete-paper-only" ? " (complete paper required; check paper-queue)"
+              : t.refillUse === "unknown-type" ? " (unknown current type; review before authoring)"
+                : t.stockLow && !t.refillDue && t.activeLearners === 0 ? " (low stock; no active demand)" : ""
           }${
             t.refillDue ? ` -> write ${t.toWrite}` : ""
           }`,
       ),
-      due.length ? `${due.length} type(s) due for a refill.` : "No refill due.",
+      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.import.preview") {

package/lib/math-lab-build-sheet.js

@@ -14,11 +14,37 @@ import {
   verifyRewardEconomy,
 } from "./math-lab-preservation.js";
 
+export function serializeMathLabSets(sets) {
+  return sets.map((set) => ({
+    key: set.key,
+    // This also makes a set eligible as a rematch of the named puzzle.
+    // It remains an ordinary collection puzzle for other learners.
+    // Preserve it for existing and appended sets; let canonical validation
+    // reject invalid references instead of silently changing their meaning.
+    ...(set.variantOf !== undefined ? { variantOf: set.variantOf } : {}),
+    questions: set.questions.map((q) => ({
+      prompt: q.prompt,
+      answer: q.answer,
+      ...(q.hint ? { hint: q.hint } : {}),
+      ...(q.guide ? { guide: q.guide } : {}),
+    })),
+  }));
+}
+
 export async function buildMathLabSheet({
   contentDir,
+  apiRoot,
+  appDir,
+  outputFile,
   args = process.argv.slice(2),
 }) {
   const here = path.resolve(contentDir);
+  // Private review directories need not imitate the historical sibling layout.
+  // Defaults preserve existing wrappers; explicit paths retain the same guards.
+  const policyRoot = path.resolve(
+    apiRoot || path.join(here, "..", "..", "twinkle-api"),
+  );
+  const declaredApp = path.resolve(appDir || path.join(here, "..", "math-lab"));
   const parts = path.join(here, "parts");
   if (
     args.length !== 2 ||
@@ -59,18 +85,12 @@ export async function buildMathLabSheet({
     }
     const data = JSON.parse(fs.readFileSync(file, "utf8"));
     sheet.rules[`${level}-daily`] = {
-      sets: data.sets.map((set) => ({
-        key: set.key,
-        questions: set.questions.map((q) => ({
-          prompt: q.prompt,
-          answer: q.answer,
-          ...(q.hint ? { hint: q.hint } : {}),
-          ...(q.guide ? { guide: q.guide } : {}),
-        })),
-      })),
+      sets: serializeMathLabSets(data.sets),
     };
   }
-  const out = path.resolve(here, "..", "math-lab-sheet.json");
+  const out = path.resolve(
+    outputFile || path.join(here, "..", "math-lab-sheet.json"),
+  );
   if (missing.length)
     throw new Error(
       `Missing grade parts: ${missing.join(", ")}. No sheet was written.`,
@@ -80,22 +100,11 @@ export async function buildMathLabSheet({
   // Server-identical validation: rewards.json + sheet → approved-shape config.
   const policy = await import(
     pathToFileURL(
-      path.resolve(
-        here,
-        "..",
-        "..",
-        "twinkle-api",
-        "helpers",
-        "build",
-        "rewardsPolicy.ts",
-      ),
+      path.join(policyRoot, "helpers", "build", "rewardsPolicy.ts"),
     ).href
   );
   const declared = JSON.parse(
-    fs.readFileSync(
-      path.resolve(here, "..", "math-lab", "rewards.json"),
-      "utf8",
-    ),
+    fs.readFileSync(path.join(declaredApp, "rewards.json"), "utf8"),
   );
   const composed = policy.composeRewardConfig({ declared, sheet });
   if (composed.errors.length) {

package/lib/sdk.js

@@ -13,6 +13,11 @@ import { findLocalProjectMetadata } from "./workspace.js";
 // TWINKLE_BUILD_SDK.md. Methods that mutate data require --allow-write.
 // Anything not listed can be called with --path api/<endpoint>.
 export const SDK_CLI_METHODS = {
+  // Newspaper reads use the public GET routes, not POST /api/* or Build
+  // tokens. Generation remains a separate, explicitly authorized workflow.
+  "news.getCurrentEdition": { special: "newsRead", operation: "current", publicRead: true },
+  "news.listEditions": { special: "newsRead", operation: "list", publicRead: true },
+  "news.getEdition": { special: "newsRead", operation: "edition", publicRead: true },
   "soundtracks.searchSources": { path: "api/soundtracks/sources", scopes: ["sharedDb:read"] },
   "soundtracks.getTags": { path: "api/soundtracks/tags", scopes: ["sharedDb:read"] },
   "soundtracks.getRecommendations": { path: "api/soundtracks/recommendations", scopes: ["sharedDb:read"] },
@@ -114,6 +119,8 @@ export const SDK_CLI_METHODS = {
   "sharedDb.getTopics": { path: "api/shared-db/topics", scopes: ["sharedDb:read"] },
   "sharedDb.createTopic": { path: "api/shared-db/topic", scopes: ["sharedDb:write"], write: true },
   "sharedDb.getEntries": { path: "api/shared-db/entries", scopes: ["sharedDb:read"] },
+  "sharedDb.queryEntries": { path: "api/shared-db/entries", scopes: ["sharedDb:read"],
+    mapArgs: ({ authorUserId, fields, where, countBy, includeAuthor, ...args }) => ({ ...args, query: { authorUserId, fields, where, countBy, includeAuthor } }) },
   "sharedDb.getEntriesByIds": { path: "api/shared-db/entries/by-ids", scopes: ["sharedDb:read"] },
   "sharedDb.addEntry": { path: "api/shared-db/entry", scopes: ["sharedDb:write"], write: true },
   "sharedDb.addEntries": { path: "api/shared-db/entries/batch", scopes: ["sharedDb:write"], write: true },
@@ -456,7 +463,7 @@ export async function sdkCommand(options) {
 
 export function printSdkMethodList() {
   console.log(
-    "Callable Build endpoints (args JSON = request body). Prints the raw\n" +
+    "Callable Build endpoints (args JSON selects the documented request fields). Prints the raw\n" +
       "endpoint response, which can differ from the SDK return shape (*).\n",
   );
   const byNamespace = new Map();
@@ -483,8 +490,10 @@ Usage:
   lumine sdk call leaderboards.get '{"boardKey": "default", "limit": 10}'
   lumine sdk call aiStories.list '{"difficulty": 1}' --repeat 5 --build 1374
   lumine sdk call userDb.query '{"sql": "SELECT * FROM sqlite_master"}'
+  lumine sdk call news.getEdition '{"dayIndex": 1762, "revisionNumber": 1}' --build 1929
 
-Request-body (args) shapes follow TWINKLE_BUILD_SDK.md. Output is the raw
+Argument shapes follow TWINKLE_BUILD_SDK.md; public newspaper reads use GET
+without a login or Build token. Output is the raw
 endpoint response; (*) methods are reshaped by their Twinkle.* SDK wrapper, so
 check TWINKLE_BUILD_SDK.md for the real SDK return shape. Add --repeat <n> for
 latency stats, --build <id> to target a build outside the current workspace.
@@ -568,6 +577,9 @@ export async function sdkCall(options) {
   const requestedScopes = options.sdkScopes.length
     ? options.sdkScopes
     : endpoint.scopes || [];
+  if (endpoint.publicRead && options.sdkScopes.length) {
+    throw new Error(`${methodName} is a public read and does not use --scopes.`);
+  }
   // A curated readOnly method (rewards.getStatus) needs a scope whose name is
   // write-capable but only ever sends its read operation; its own default
   // scopes do not trip the gate. Explicit --scopes overrides always do.
@@ -595,12 +607,23 @@ export async function sdkCall(options) {
   // before any auth side effects, so invalid local input fails immediately
   // instead of after starting the device-login flow.
   const buildId = await resolveSdkBuildId(options);
-  const auth = await ensureAuth(options);
-  await assertAuthScope({ options, auth, scope: "build:sdk" });
+  // Validate selectors before login/network calls. Public reads deliberately
+  // carry no saved login, even when one is available in this CLI session.
+  const newsUrl = endpoint.special === "newsRead"
+    ? buildNewsReadUrl({ apiUrl: options.apiUrl, buildId, operation: endpoint.operation, args })
+    : null;
+  const auth = endpoint.publicRead ? null : await ensureAuth(options);
+  if (auth) await assertAuthScope({ options, auth, scope: "build:sdk" });
   const attempts = [];
   let lastResult = null;
 
-  if (endpoint.special === "leaderboardGet" || endpoint.special === "leaderboardSubmit") {
+  if (endpoint.special === "newsRead") {
+    for (let attempt = 0; attempt < options.repeat; attempt += 1) {
+      lastResult = await executeSdkHttpCall({ options, method: "GET", url: newsUrl });
+      attempts.push(lastResult);
+      printSdkAttemptLine(attempts.length, lastResult);
+    }
+  } else if (endpoint.special === "leaderboardGet" || endpoint.special === "leaderboardSubmit") {
     const boardKey = String(args.boardKey || "default");
     const rest = { ...args };
     delete rest.boardKey;
@@ -740,6 +763,39 @@ export async function sdkCall(options) {
   }
 }
 
+function buildNewsReadUrl({ apiUrl, buildId, operation, args }) {
+  const allowed = operation === "edition" ? ["dayIndex", "revisionNumber"]
+    : operation === "list" ? ["limit", "cursor"] : [];
+  if (Object.keys(args).some((key) => !allowed.includes(key))) {
+    throw new Error(`Unexpected newspaper selector; accepted fields: ${allowed.join(", ") || "none"}.`);
+  }
+  let suffix = "current";
+  if (operation === "edition") {
+    if (!Number.isSafeInteger(args.dayIndex) || args.dayIndex < 0) {
+      throw new Error("dayIndex is required and must be a nonnegative integer.");
+    }
+    if (args.revisionNumber != null && (!Number.isSafeInteger(args.revisionNumber) || args.revisionNumber <= 0)) {
+      throw new Error("revisionNumber must be a positive integer.");
+    }
+    suffix = `editions/${args.dayIndex}`;
+  } else if (operation === "list") {
+    if (args.limit != null && (!Number.isSafeInteger(args.limit) || args.limit < 1)) {
+      throw new Error("limit must be a positive integer (capped at 30).");
+    }
+    if (args.cursor != null && (typeof args.cursor !== "string" || args.cursor.length > 200)) {
+      throw new Error("cursor must be the string returned by news.listEditions.");
+    }
+    suffix = "editions";
+  }
+  const url = new URL(`${apiUrl}/build/${buildId}/news/${suffix}`);
+  for (const [key, value] of operation === "edition"
+    ? [["revision", args.revisionNumber]] : operation === "list"
+      ? [["limit", args.limit == null ? null : Math.min(30, args.limit)], ["cursor", args.cursor]] : []) {
+    if (value != null) url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+
 export function printSdkAttemptLine(attemptNumber, result) {
   console.error(
     `#${attemptNumber} ${result.status}${result.ok ? " OK" : ""} · ` +

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.73.0
-Updated: 2026-10-27
-Generated: 2026-10-26T22:37:17.385Z
+Version: 1.74.0
+Updated: 2026-10-29
+Generated: 2026-10-28T20:08:43.889Z
 
 ## Platform rules
 Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed frame, even when the code itself is correct. They outrank every other guideline: follow them in every change, including small ones, and fix any break of them you see in code you touch.
@@ -1402,6 +1402,19 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Use limit or pageSize to choose how many entries to fetch per page. Default is 20, max is 100.
   - For oldest-first chronological reads, pass order: 'asc' or order: 'oldest'. sort and direction are accepted as aliases.
   - Supports cursor-based pagination. Newest-first cursors page toward older entries; oldest-first cursors page toward newer entries.
+- async queryEntries(topicName, { limit, pageSize, cursor, order, authorUserId, fields, where, countBy, includeAuthor } = {}) | scopes: sharedDb:read
+  - Returns: { entries?, groups?, cursor, hasMore, queryVersion: 1 }
+  - Read selected shared data fields with server-side creator filtering, scalar matching and grouped counts.
+  - Returns the same paginated entries as getEntries, plus queryVersion: 1.
+  - authorUserId filters to one entry creator on the server. It does not change read or write permissions.
+  - fields selects at most 24 top-level data field names; missing selected fields are null. Omit fields for complete data; [] returns only row metadata.
+  - where: { field, equals } filters one top-level data field by exact JSON scalar equality (string, number, boolean or null).
+  - Alternatively where: { field, truthy: true } requires a present JSON value other than null, false, zero or an empty string.
+  - countBy groups matching entries by one top-level data field and returns { groups: [{ value, count }], cursor, hasMore, queryVersion: 1 } instead of entries. This avoids transferring documents just to count comments. Groups page in first-entry order; use the returned cursor with the same query. Per-viewer hidden entries are excluded before counting.
+  - includeAuthor: false skips username/profile-photo enrichment for count/index reads; id, topicId, userId and timestamps remain available.
+  - Field names use letters, digits and underscores, starting with a letter or underscore, at most 64 characters. No SQL or nested paths.
+  - Keep the same filters/fields/order when passing a cursor. Reads retain app/topic boundaries, published guest opt-ins and per-viewer content visibility. Signed-in queries read canonical writer state.
+  - Use metadata lists for browsing and getEntriesByIds only when a member opens a full recording/document.
 - async loadMoreEntries(topicName, { limit, pageSize, cursor, order, sort, direction } = {}) | scopes: sharedDb:read
   - Returns: { entries: [{ id, topicId, userId, username, profilePicUrl, data, createdAt, updatedAt }], cursor?, hasMore }
   - Fetch the next sharedDb page.