gamealgo-cli 0.3.9 → 0.4.2

package/README.md

@@ -35,6 +35,20 @@ gamealgo listapi
 gamealgo docs api GameAlgo.Init --platform lua
 ```
 
+Report Pack v2 uses materialized ordinary Datasets and inline Views. Common report commands are:
+
+```bash
+gamealgo report pull --out gamealgo-report-pack.json
+gamealgo report validate gamealgo-report-pack.json
+gamealgo report preview --pack gamealgo-report-pack.json
+gamealgo report publish gamealgo-report-pack.json
+gamealgo report result --from 2026-09-04 --to 2026-09-17 --platform maker --tab-id overview
+gamealgo report advanced run --query-id battle_analysis --from 2026-09-04 --to 2026-09-17 --platform maker --wait
+gamealgo report advanced list
+```
+
+All Report Packs use `schemaVersion: 2`, with custom `groups[].views` or platform-owned `groups[].standard`. Advanced query runs are explicit, are never preloaded, and remain available as immutable reports for 30 days.
+
 Help and documentation are fetched from the configured Server on every invocation. The CLI intentionally does not keep a documentation cache.
 
 ## Agent skill

package/dist/client.js

@@ -168,6 +168,24 @@ export class GameAlgoAdminClient {
         const query = params.size ? `?${params.toString()}` : "";
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/reports/manifest${query}`);
     }
+    async readReportDataset(input) {
+        const params = new URLSearchParams({
+            platform: input.platform,
+            startDate: input.startDate,
+            endDate: input.endDate,
+        });
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/report-datasets/${encodeURIComponent(input.datasetFingerprint)}/results?${params.toString()}`);
+    }
+    async createAdvancedReportRun(body, options = {}) {
+        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/reports/advanced-runs`, body, options);
+    }
+    async getAdvancedReportRun(runId, includeResult = true) {
+        const params = new URLSearchParams({ includeResult: includeResult ? "true" : "false" });
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/reports/advanced-runs/${encodeURIComponent(runId)}?${params.toString()}`);
+    }
+    async listAdvancedReportRuns(limit = 50) {
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/reports/advanced-runs?limit=${encodeURIComponent(String(limit))}`);
+    }
     async queryReportDashboard(body, options = {}) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/reports/query`, body, options);
     }
@@ -231,8 +249,8 @@ export class GameAlgoAdminClient {
     async listGameKeys() {
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/keys`);
     }
-    async createGameKey(name) {
-        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/keys`, { name });
+    async createGameKey(name, platform) {
+        return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/keys`, { name, ...(platform ? { platform } : {}) });
     }
     async revealGameKey(selector) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/keys/reveal`, selector);

package/dist/commands/experiment.js

@@ -129,7 +129,7 @@ export async function handleExperimentStrategy(client, args, global) {
         const platform = flags.platform === undefined ? undefined : experimentPlatform(flags.platform);
         const message = requiredMessage(flags, "experiment strategy rollback");
         if (!strategyKey || !versionId) {
-            throw new Error("usage: gamealgo experiment strategy rollback <strategyKey> --version-id <versionId> [--platform ios|android|rest] --message <reason> --yes");
+            throw new Error("usage: gamealgo experiment strategy rollback <strategyKey> --version-id <versionId> [--platform ios|android|maker|web] --message <reason> --yes");
         }
         await requireYes(flags, global, "experiment strategy rollback");
         await printResult(await client.rollbackExperimentV2Strategy(strategyKey, versionId, message, platform), global);

package/dist/commands/integration.js

@@ -16,7 +16,7 @@ export async function handleIntegration(client, args, global) {
         await writeIntegrationOutput(response, flags, global);
         return;
     }
-    throw new Error("usage: gamealgo integration get-plan --environment <domestic|overseas> --platform <ios|android|maker|rest>");
+    throw new Error("usage: gamealgo integration get-plan --environment <domestic|overseas> --platform <ios|android|maker|web>");
 }
 export async function writeIntegrationOutput(value, flags, global) {
     if (flags.out) {

package/dist/commands/keys.js

@@ -1,7 +1,7 @@
 import { parseFlags } from "../args.js";
 import { confirm, isInteractive, printResult } from "../output.js";
 import { announceTargetGame } from "../target.js";
-import { optionalString } from "../utils.js";
+import { integrationPlatform, optionalString } from "../utils.js";
 export async function handleGameKey(client, args, global) {
     const sub = args.shift();
     if (sub === "list") {
@@ -15,8 +15,9 @@ export async function handleGameKey(client, args, global) {
         const flags = parseFlags(args);
         const name = optionalString(flags.name) || optionalString(args.shift());
         if (!name)
-            throw new Error("usage: gamealgo key create --name <key-name>");
-        const response = await client.createGameKey(name);
+            throw new Error("usage: gamealgo key create --name <key-name> [--platform ios|android|maker|web]");
+        const platform = flags.platform === undefined ? undefined : integrationPlatform(flags.platform);
+        const response = await client.createGameKey(name, platform);
         await printResult({
             ok: true,
             created: response.created !== false,
@@ -25,6 +26,7 @@ export async function handleGameKey(client, args, global) {
             prefix: response.key.keyPrefix,
             keyPrefix: response.key.keyPrefix,
             status: response.key.status,
+            platform: response.key.platform,
             createdAt: response.key.createdAt,
         }, global);
         return;
@@ -40,6 +42,7 @@ export async function handleGameKey(client, args, global) {
             prefix: response.key.keyPrefix,
             keyPrefix: response.key.keyPrefix,
             status: response.key.status,
+            platform: response.key.platform,
             createdAt: response.key.createdAt,
         }, global);
         return;
@@ -72,6 +75,7 @@ export function publicGameKeyForCli(key) {
         prefix: key.keyPrefix,
         keyPrefix: key.keyPrefix,
         status: key.status,
+        platform: key.platform,
         createdAt: key.createdAt,
     };
 }

package/dist/commands/report.js

@@ -4,16 +4,24 @@ import { formatDuration, markCommandFailed, printResult, reportTimeoutMs, startP
 import { reportDashboardCsv, reportDashboardCsvExports } from "../report-csv.js";
 import { normalizeReportSampleRows, summarizeReportDashboard, summarizeReportManifest, summarizeReportValidation, } from "../report-summary.js";
 import { objectValue, readJsonFile, writeTextFile } from "../resources.js";
+import { queryReportPackV2Result } from "../report-v2/result.js";
+import { assertWritableReportPackV2, reportPackSchemaVersion } from "../report-v2/schema.js";
+import { summarizeReportPackV2Manifest } from "../report-v2/summary.js";
 import { announceTargetGame } from "../target.js";
 import { optionalString } from "../utils.js";
 export async function handleReport(client, args, global) {
     const sub = args.shift();
+    if (sub === "advanced") {
+        await handleAdvancedReport(client, args, global);
+        return;
+    }
     if (sub === "pull") {
         const flags = parseFlags(args);
         const pack = await client.getReportPack();
-        const out = String(flags.out || "gamealgo-report-pack-v1.json");
+        const schemaVersion = reportPackSchemaVersion(pack.reportPack.content);
+        const out = String(flags.out || `gamealgo-report-pack-v${schemaVersion}.json`);
         await writeTextFile(out, JSON.stringify(pack.reportPack.content, null, 2) + "\n");
-        await printResult({ ok: true, out }, global);
+        await printResult({ ok: true, out, schemaVersion }, global);
         return;
     }
     if (sub === "validate") {
@@ -23,6 +31,7 @@ export async function handleReport(client, args, global) {
         const flags = parseFlags(args);
         const full = reportFullOutput(flags);
         const content = await readJsonFile(filePath);
+        assertWritableReportPackV2(content, "report validate");
         const response = await client.previewReportPack(content, { responseMode: full ? "full" : "summary" });
         const summary = summarizeReportValidation(response);
         await printResult(full ? response : summary, global);
@@ -36,6 +45,7 @@ export async function handleReport(client, args, global) {
             throw new Error("usage: gamealgo report publish <report-pack.json>");
         parseFlags(args);
         const content = await readJsonFile(filePath);
+        assertWritableReportPackV2(content, "report publish");
         await announceTargetGame(client);
         const response = await client.putReportPack(content);
         await printResult({ ok: true, validation: response.reportPack.validation }, global);
@@ -45,7 +55,10 @@ export async function handleReport(client, args, global) {
         const flags = parseFlags(args);
         const full = reportFullOutput(flags);
         const response = await client.reportManifest({ responseMode: full ? "full" : "summary" });
-        await printResult(full ? response : summarizeReportManifest(response), global);
+        const manifest = objectValue(objectValue(response)?.manifest);
+        await printResult(full
+            ? response
+            : manifest?.schemaVersion === 2 ? summarizeReportPackV2Manifest(response) : summarizeReportManifest(response), global);
         return;
     }
     if (sub === "result") {
@@ -54,32 +67,50 @@ export async function handleReport(client, args, global) {
         const startDate = String(flags.from || flags.start || flags.startDate || "");
         const endDate = String(flags.to || flags.end || flags.endDate || "");
         if (!startDate || !endDate)
-            throw new Error("usage: gamealgo report result --from YYYY-MM-DD --to YYYY-MM-DD [--platform ios|android|rest] [--tab name] [--group name] [--chart name] [--selector k=v] [--sample-rows 0..20] [--full] [--format json|csv] [--out file-or-directory]");
+            throw new Error("usage: gamealgo report result --from YYYY-MM-DD --to YYYY-MM-DD [--platform ios|android|maker|web] [--tab name] [--group name] [--chart name] [--selector k=v] [--sample-rows 0..20] [--full] [--format json|csv] [--out file-or-directory]");
         requireReportQueryScope(flags, "report result");
         const timeoutMs = reportTimeoutMs(flags);
         const format = reportOutputFormat(flags.format);
         const full = reportFullOutput(flags) || format === "csv";
         const sampleRows = reportSampleRows(flags, full);
         const platform = await resolveCliReportPlatform(client, flags.platform, selectors.platform, startDate, endDate);
+        const manifestResponse = await client.reportManifest({ responseMode: "full" });
+        const manifest = objectValue(objectValue(manifestResponse)?.manifest);
+        const schemaVersion = manifest?.schemaVersion === 2 ? 2 : 1;
         const startedAt = Date.now();
-        const stopProgress = startProgress("Querying report results", timeoutMs);
+        const stopProgress = startProgress(schemaVersion === 2 ? "Reading report results" : "Querying report results", timeoutMs);
         let response;
         try {
-            response = await client.queryReportDashboard({
-                startDate,
-                endDate,
-                tab: optionalString(flags.tab),
-                tabId: optionalString(flags["tab-id"]),
-                group: optionalString(flags.group),
-                groupId: optionalString(flags["group-id"]),
-                chart: optionalString(flags.chart),
-                chartId: optionalString(flags["chart-id"]),
-                platform,
-                selectors,
-                refresh: Boolean(flags.refresh),
-                responseMode: full ? "full" : "summary",
-                sampleRows,
-            }, { timeoutMs });
+            response = schemaVersion === 2
+                ? await queryReportPackV2Result(client, manifestResponse, {
+                    startDate,
+                    endDate,
+                    tab: optionalString(flags.tab),
+                    tabId: optionalString(flags["tab-id"]),
+                    group: optionalString(flags.group),
+                    groupId: optionalString(flags["group-id"]),
+                    chart: optionalString(flags.chart),
+                    chartId: optionalString(flags["chart-id"]),
+                    platform,
+                    selectors,
+                    refresh: Boolean(flags.refresh),
+                    timeoutMs,
+                })
+                : await client.queryReportDashboard({
+                    startDate,
+                    endDate,
+                    tab: optionalString(flags.tab),
+                    tabId: optionalString(flags["tab-id"]),
+                    group: optionalString(flags.group),
+                    groupId: optionalString(flags["group-id"]),
+                    chart: optionalString(flags.chart),
+                    chartId: optionalString(flags["chart-id"]),
+                    platform,
+                    selectors,
+                    refresh: Boolean(flags.refresh),
+                    responseMode: full ? "full" : "summary",
+                    sampleRows,
+                }, { timeoutMs });
         }
         finally {
             stopProgress();
@@ -93,53 +124,159 @@ export async function handleReport(client, args, global) {
         return;
     }
     if (sub === "preview") {
-        const selectors = parseSelectorFlags(args);
         const flags = parseFlags(args);
         const filePath = String(flags.pack || flags.file || args.shift() || "");
-        const startDate = String(flags.from || flags.start || flags.startDate || "");
-        const endDate = String(flags.to || flags.end || flags.endDate || "");
-        if (!filePath || !startDate || !endDate) {
-            throw new Error("usage: gamealgo report preview --pack report-pack.json --from YYYY-MM-DD --to YYYY-MM-DD [--platform ios|android|rest] [--tab name] [--group name] [--chart name] [--selector k=v] [--sample-rows 0..20] [--full] [--format json|csv] [--out file-or-directory]");
-        }
-        requireReportQueryScope(flags, "report preview");
+        if (!filePath)
+            throw new Error("usage: gamealgo report preview --pack report-pack.json [--full]");
         const content = await readJsonFile(filePath);
+        assertWritableReportPackV2(content, "report preview");
         const timeoutMs = reportTimeoutMs(flags);
-        const format = reportOutputFormat(flags.format);
-        const full = reportFullOutput(flags) || format === "csv";
-        const sampleRows = reportSampleRows(flags, full);
-        const platform = await resolveCliReportPlatform(client, flags.platform, selectors.platform, startDate, endDate);
+        const full = reportFullOutput(flags);
         const startedAt = Date.now();
-        const stopProgress = startProgress("Previewing report results", timeoutMs);
+        const stopProgress = startProgress("Validating Report Pack v2 preview", timeoutMs);
         let response;
         try {
-            response = await client.previewReportDashboard({
-                content,
-                startDate,
-                endDate,
-                tab: optionalString(flags.tab),
-                tabId: optionalString(flags["tab-id"]),
-                group: optionalString(flags.group),
-                groupId: optionalString(flags["group-id"]),
-                chart: optionalString(flags.chart),
-                chartId: optionalString(flags["chart-id"]),
-                platform,
-                selectors,
-                responseMode: full ? "full" : "summary",
-                sampleRows,
-            }, { timeoutMs });
+            response = await client.previewReportPack(content, { responseMode: full ? "full" : "summary" });
         }
         finally {
             stopProgress();
         }
         const elapsedMs = Date.now() - startedAt;
         const rawOutputValue = withCliMeta(response, { elapsedMs, timeoutMs });
-        const statusSummary = summarizeReportDashboard(rawOutputValue, { command: "report.preview", sampleRows });
+        const statusSummary = summarizeReportValidation(rawOutputValue, "report.preview");
         const outputValue = full ? rawOutputValue : statusSummary;
-        process.stderr.write(`Report preview finished in ${formatDuration(elapsedMs)}.\n`);
-        await writeReportQueryOutput(outputValue, flags, global, elapsedMs, statusSummary.ok);
+        process.stderr.write(`Report Pack preview finished in ${formatDuration(elapsedMs)}.\n`);
+        const out = optionalString(flags.out);
+        if (flags.out === true)
+            throw new Error("--out requires a file path");
+        if (out) {
+            await writeTextFile(out, JSON.stringify(outputValue, null, 2) + "\n");
+            await printResult({ ok: statusSummary.ok, out, elapsedMs }, global);
+        }
+        else {
+            await printResult(outputValue, global);
+        }
+        if (!statusSummary.ok)
+            markCommandFailed();
         return;
     }
-    throw new Error("usage: gamealgo report <pull|validate|publish|manifest|result|preview>");
+    throw new Error("usage: gamealgo report <pull|validate|publish|manifest|result|preview|advanced>");
+}
+async function handleAdvancedReport(client, args, global) {
+    const action = args.shift();
+    if (action === "run") {
+        const flags = parseFlags(args);
+        const queryId = requiredTextFlag(flags["query-id"], "--query-id");
+        const startDate = requiredTextFlag(flags.from || flags.start || flags.startDate, "--from");
+        const endDate = requiredTextFlag(flags.to || flags.end || flags.endDate, "--to");
+        const platform = optionalCliReportPlatform(flags.platform, "--platform");
+        if (!platform)
+            throw new Error("--platform is required for report advanced run");
+        if (flags.format !== undefined && flags.format !== "json")
+            throw new Error("report advanced currently supports only --format json");
+        const packPath = optionalString(flags.pack);
+        if (flags.pack === true)
+            throw new Error("--pack requires a file path");
+        const pack = packPath ? await readJsonFile(packPath) : undefined;
+        if (pack !== undefined)
+            assertWritableReportPackV2(pack, "report advanced run");
+        const wait = booleanFlag(flags.wait, "--wait");
+        const timeoutMs = reportTimeoutMs(flags) ?? 15 * 60 * 1000;
+        await announceTargetGame(client);
+        const created = await client.createAdvancedReportRun({
+            queryId,
+            startDate,
+            endDate,
+            platform,
+            ...(pack !== undefined ? { pack } : {}),
+        }, { timeoutMs: Math.min(timeoutMs, 30_000) });
+        if (!wait) {
+            await writeAdvancedOutput(created, flags, global);
+            return;
+        }
+        const runId = requiredRunId(created.run?.id);
+        const startedAt = Date.now();
+        const stopProgress = startProgress(`Waiting for advanced report ${runId}`, timeoutMs);
+        let response;
+        try {
+            response = await waitForAdvancedReport(client, runId, timeoutMs, startedAt);
+        }
+        finally {
+            stopProgress();
+        }
+        await writeAdvancedOutput(withCliMeta(response, { elapsedMs: Date.now() - startedAt, timeoutMs }), flags, global);
+        if (response.run.status === "failed")
+            markCommandFailed();
+        return;
+    }
+    if (action === "get") {
+        const runId = args.shift();
+        if (!runId)
+            throw new Error("usage: gamealgo report advanced get <run-id> [--metadata-only] [--out file]");
+        const flags = parseFlags(args);
+        const metadataOnly = booleanFlag(flags["metadata-only"], "--metadata-only");
+        const response = await client.getAdvancedReportRun(runId, !metadataOnly);
+        await writeAdvancedOutput(response, flags, global);
+        if (response.run.status === "failed")
+            markCommandFailed();
+        return;
+    }
+    if (action === "list") {
+        const flags = parseFlags(args);
+        const limit = positiveIntegerFlag(flags.limit, "--limit", 50);
+        await writeAdvancedOutput(await client.listAdvancedReportRuns(limit), flags, global);
+        return;
+    }
+    throw new Error("usage: gamealgo report advanced <run|get|list>");
+}
+async function waitForAdvancedReport(client, runId, timeoutMs, startedAt) {
+    while (true) {
+        const response = await client.getAdvancedReportRun(runId, true);
+        if (response.run.status === "succeeded" || response.run.status === "failed")
+            return response;
+        if (Date.now() - startedAt >= timeoutMs) {
+            throw new Error(`advanced report ${runId} did not finish within ${formatDuration(timeoutMs)}; use report advanced get ${runId} later`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 2_000));
+    }
+}
+async function writeAdvancedOutput(value, flags, global) {
+    if (flags.format !== undefined && flags.format !== "json")
+        throw new Error("report advanced currently supports only --format json");
+    const out = optionalString(flags.out);
+    if (flags.out === true)
+        throw new Error("--out requires a file path");
+    if (!out) {
+        await printResult(value, global);
+        return;
+    }
+    await writeTextFile(out, JSON.stringify(value, null, 2) + "\n");
+    await printResult({ ok: true, out }, global);
+}
+function requiredTextFlag(value, flag) {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${flag} is required`);
+    return value.trim();
+}
+function requiredRunId(value) {
+    if (typeof value !== "string" || !value)
+        throw new Error("advanced report create response is missing run.id");
+    return value;
+}
+function booleanFlag(value, flag) {
+    if (value === undefined)
+        return false;
+    if (value !== true)
+        throw new Error(`${flag} does not accept a value`);
+    return true;
+}
+function positiveIntegerFlag(value, flag, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "string" || !/^\d+$/.test(value) || Number(value) < 1) {
+        throw new Error(`${flag} must be a positive integer`);
+    }
+    return Number(value);
 }
 function reportFullOutput(flags) {
     if (flags.full === undefined)
@@ -293,7 +430,7 @@ export async function resolveCliReportPlatform(client, flagValue, selectorValue,
     const detected = objectValue(await client.countEventPlatforms(startDate, endDate));
     const detectedPlatform = optionalCliReportPlatform(detected?.recommendedPlatform, "detected report platform");
     if (!detectedPlatform) {
-        throw new Error("report platform could not be detected for the selected date range; pass --platform ios, --platform android, or --platform rest");
+        throw new Error("report platform could not be detected for the selected date range; pass --platform ios, android, maker, or web");
     }
     process.stderr.write(`Report platform: ${detectedPlatform} (detected from event data)\n`);
     return detectedPlatform;
@@ -301,7 +438,7 @@ export async function resolveCliReportPlatform(client, flagValue, selectorValue,
 export function optionalCliReportPlatform(value, field) {
     if (value === undefined || value === null || value === "")
         return undefined;
-    if (value === "ios" || value === "android" || value === "rest")
+    if (value === "ios" || value === "android" || value === "maker" || value === "web")
         return value;
-    throw new Error(`${field} must be ios, android, or rest`);
+    throw new Error(`${field} must be ios, android, maker, or web`);
 }

package/dist/compatibility.js

@@ -1,6 +1,6 @@
 import { loadPackageMetadata } from "./config.js";
 import { requestJson } from "./http.js";
-export const CLI_PROTOCOL_VERSION = 1;
+export const CLI_PROTOCOL_VERSION = 2;
 export async function assertServerCompatibility(host) {
     const metadata = await requestJson(host, "/admin/v1/cli/meta", {
         headers: { "Cache-Control": "no-cache" },

package/dist/docs.js

@@ -459,12 +459,12 @@ export function parseDocsApiPlatform(value) {
     if (value === undefined || value === false || value === "")
         return undefined;
     const platform = String(value).trim().toLowerCase();
-    if (platform === "maker")
-        return "lua";
-    if (platform === "lua" || platform === "ios" || platform === "android" || platform === "rest") {
+    if (platform === "lua")
+        return "maker";
+    if (platform === "maker" || platform === "ios" || platform === "android" || platform === "web") {
         return platform;
     }
-    throw new Error("--platform must be lua, maker, ios, android, or rest");
+    throw new Error("--platform must be ios, android, maker, or web");
 }
 export async function printDocsApiResult(options) {
     const { query, platform, manifest, topic, document, webUrl, host, global } = options;
@@ -537,8 +537,8 @@ export function parseDocsApiEntries(content) {
         if (!symbols.length)
             continue;
         const platforms = parseDocsApiMetadataList(section, "平台")
-            .map((item) => item.toLowerCase())
-            .filter((item) => item === "lua" || item === "ios" || item === "android" || item === "rest");
+            .map((item) => item.toLowerCase() === "lua" ? "maker" : item.toLowerCase())
+            .filter((item) => item === "maker" || item === "ios" || item === "android" || item === "web");
         const summaryMatch = section.match(/^-\s*用途[：:]\s*(.+)$/m);
         entries.push({
             name: stripInlineMarkdown(heading[1]),

package/dist/report-summary.js

@@ -2,7 +2,7 @@ export const REPORT_SUMMARY_SCHEMA_VERSION = 1;
 export const REPORT_SUMMARY_MAX_ITEMS = 200;
 export const REPORT_SUMMARY_MAX_ISSUES = 100;
 export const REPORT_SUMMARY_MAX_SAMPLE_ROWS = 20;
-export function summarizeReportValidation(value) {
+export function summarizeReportValidation(value, command = "report.validate") {
     const root = objectValue(value);
     const validation = objectValue(root?.validation);
     const errorMessages = stringValues(validation?.errors);
@@ -24,7 +24,7 @@ export function summarizeReportValidation(value) {
     const items = statementItems.slice(0, REPORT_SUMMARY_MAX_ITEMS);
     return {
         schemaVersion: REPORT_SUMMARY_SCHEMA_VERSION,
-        command: "report.validate",
+        command,
         ok: validation?.ok === true && errorMessages.length === 0,
         summary: {
             errorCount: errorMessages.length,
@@ -146,6 +146,13 @@ export function summarizeReportDashboard(value, options) {
         if (result?.stale === true) {
             allWarnings.push({ scope, message: "Report result is stale" });
         }
+        if (result?.partial === true) {
+            const missingDates = stringValues(result.missingDates);
+            allWarnings.push({
+                scope,
+                message: `Report Dataset coverage is partial${missingDates.length ? `; missing dates: ${missingDates.join(", ")}` : ""}`,
+            });
+        }
         allItems.push(compactObject({
             kind: "chart-result",
             status,
@@ -162,6 +169,9 @@ export function summarizeReportDashboard(value, options) {
             cached: typeof result?.cached === "boolean" ? result.cached : undefined,
             cachedAt: stringValue(result?.cachedAt),
             stale: typeof result?.stale === "boolean" ? result.stale : undefined,
+            partial: typeof result?.partial === "boolean" ? result.partial : undefined,
+            missingDates: stringValues(result?.missingDates),
+            snapshotVersion: stringValue(result?.snapshotVersion),
             truncated,
             rowLimit: finiteNonNegativeNumber(result?.rowLimit),
             error,
@@ -243,6 +253,8 @@ function reportResultStatus(result) {
         return "retrying";
     if (result?.refreshing === true)
         return "refreshing";
+    if (result?.partial === true)
+        return "partial";
     if (result?.stale === true)
         return "stale";
     return "ready";

package/dist/report-v2/expression.js

@@ -0,0 +1,130 @@
+export function parseReportFormula(source) {
+    const tokens = tokenize(String(source ?? ""));
+    let cursor = 0;
+    const peek = (value) => tokens[cursor]?.value === value;
+    const take = (value) => {
+        if (!peek(value))
+            throw new Error(`expected ${value || "expression"}`);
+        return tokens[cursor++];
+    };
+    const parsePrimary = () => {
+        const token = tokens[cursor];
+        if (!token)
+            throw new Error("unexpected end of formula");
+        if (token.type === "number") {
+            cursor += 1;
+            return { type: "number", value: Number(token.value) };
+        }
+        if (token.type === "identifier") {
+            cursor += 1;
+            return { type: "identifier", name: token.value };
+        }
+        if (token.value === "(") {
+            cursor += 1;
+            const expression = parseAdditive();
+            take(")");
+            return expression;
+        }
+        throw new Error(`unexpected token ${token.value}`);
+    };
+    const parseUnary = () => {
+        if (peek("+") || peek("-")) {
+            const operator = tokens[cursor++].value;
+            return { type: "unary", operator, argument: parseUnary() };
+        }
+        return parsePrimary();
+    };
+    const parseMultiplicative = () => {
+        let expression = parseUnary();
+        while (peek("*") || peek("/")) {
+            const operator = tokens[cursor++].value;
+            expression = { type: "binary", operator, left: expression, right: parseUnary() };
+        }
+        return expression;
+    };
+    const parseAdditive = () => {
+        let expression = parseMultiplicative();
+        while (peek("+") || peek("-")) {
+            const operator = tokens[cursor++].value;
+            expression = { type: "binary", operator, left: expression, right: parseMultiplicative() };
+        }
+        return expression;
+    };
+    if (!tokens.length)
+        throw new Error("formula must not be empty");
+    const expression = parseAdditive();
+    if (cursor !== tokens.length)
+        throw new Error(`unexpected token ${tokens[cursor].value}`);
+    return expression;
+}
+export function reportFormulaReferences(source) {
+    const references = new Set();
+    visit(parseReportFormula(source), (node) => {
+        if (node.type === "identifier")
+            references.add(node.name);
+    });
+    return [...references].sort();
+}
+export function evaluateReportFormula(expression, values) {
+    if (expression.type === "number")
+        return expression.value;
+    if (expression.type === "identifier")
+        return finiteNumber(values[expression.name]);
+    if (expression.type === "unary") {
+        const value = evaluateReportFormula(expression.argument, values);
+        if (value === null)
+            return null;
+        return expression.operator === "-" ? -value : value;
+    }
+    const left = evaluateReportFormula(expression.left, values);
+    const right = evaluateReportFormula(expression.right, values);
+    if (left === null || right === null)
+        return null;
+    const result = expression.operator === "+" ? left + right
+        : expression.operator === "-" ? left - right
+            : expression.operator === "*" ? left * right
+                : right === 0 ? null : left / right;
+    return typeof result === "number" && Number.isFinite(result) ? result : null;
+}
+function tokenize(source) {
+    const tokens = [];
+    let cursor = 0;
+    while (cursor < source.length) {
+        const char = source[cursor];
+        if (/\s/.test(char)) {
+            cursor += 1;
+            continue;
+        }
+        if ("+-*/()".includes(char)) {
+            tokens.push({ type: "operator", value: char });
+            cursor += 1;
+            continue;
+        }
+        const number = source.slice(cursor).match(/^(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?/);
+        if (number) {
+            tokens.push({ type: "number", value: number[0] });
+            cursor += number[0].length;
+            continue;
+        }
+        const identifier = source.slice(cursor).match(/^[A-Za-z_][A-Za-z0-9_]*/);
+        if (identifier) {
+            tokens.push({ type: "identifier", value: identifier[0] });
+            cursor += identifier[0].length;
+            continue;
+        }
+        throw new Error(`unsupported formula token at position ${cursor}`);
+    }
+    return tokens;
+}
+function visit(node, callback) {
+    callback(node);
+    if (node.type === "unary")
+        visit(node.argument, callback);
+    if (node.type === "binary") {
+        visit(node.left, callback);
+        visit(node.right, callback);
+    }
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}

package/dist/report-v2/result.js

@@ -0,0 +1,209 @@
+import { executeReportPackV2View } from "./view-executor.js";
+export async function queryReportPackV2Result(client, manifestResponse, options) {
+    const root = requiredObject(manifestResponse, "manifest response");
+    const manifest = requiredObject(root.manifest, "manifest");
+    if (manifest.schemaVersion !== 2)
+        throw new Error("Report Pack v2 manifest is required");
+    const selected = selectResultItems(manifest, options);
+    if (options.refresh && selected.standardCharts.length === 0) {
+        throw new Error("--refresh is only supported for standard Groups; custom v2 Views read materialized Dataset snapshots");
+    }
+    const fingerprints = new Set(selected.views.map(({ view }) => viewDatasetFingerprint(view)));
+    const datasets = new Map();
+    const standardPromise = selected.standardCharts.length
+        ? client.queryReportDashboard({
+            startDate: options.startDate,
+            endDate: options.endDate,
+            platform: options.platform,
+            selectors: options.selectors,
+            refresh: Boolean(options.refresh),
+            responseMode: "full",
+            ...queryScope(options),
+        }, { timeoutMs: options.timeoutMs })
+        : Promise.resolve(null);
+    const [, standardPayload] = await Promise.all([
+        Promise.all([...fingerprints].map(async (datasetFingerprint) => {
+            const payload = requiredObject(await client.readReportDataset({
+                datasetFingerprint,
+                platform: options.platform,
+                startDate: options.startDate,
+                endDate: options.endDate,
+            }), `Dataset ${datasetFingerprint}`);
+            datasets.set(datasetFingerprint, payload);
+        })),
+        standardPromise,
+    ]);
+    const viewResults = selected.views.map(({ tab, group, view }) => {
+        const fingerprint = viewDatasetFingerprint(view);
+        const dataset = datasets.get(fingerprint);
+        const status = String(dataset.status || "waiting");
+        if (status === "abnormal") {
+            return reportResult(tab, group, view, fingerprint, [], [], {
+                error: String(dataset.abnormalMessage || dataset.abnormalCode || "Dataset materialization is abnormal"),
+            });
+        }
+        const data = requiredObject(view.data, "view.data");
+        const rows = status === "waiting"
+            ? []
+            : executeReportPackV2View(view, recordRows(dataset.rows), {
+                selectorFilters: selectorFilters(group, data, options.selectors, recordRows(dataset.rows)),
+            });
+        const columns = [
+            ...stringArray(data.groupBy, "view.data.groupBy"),
+            ...Object.keys(requiredObject(data.metrics, "view.data.metrics")),
+        ];
+        return reportResult(tab, group, view, fingerprint, columns, rows, {
+            cached: true,
+            cachedAt: dataset.updatedAt,
+            pending: status === "waiting" || undefined,
+            partial: status === "partial" || undefined,
+            missingDates: dataset.missingDates,
+            snapshotVersion: dataset.snapshotVersion,
+        });
+    });
+    const standardResults = standardPayload
+        ? arrayValues(requiredObject(standardPayload, "standard report result").results)
+        : [];
+    return {
+        reportPack: root.reportPack,
+        dateRange: { startDate: options.startDate, endDate: options.endDate, platform: options.platform },
+        selectors: options.selectors,
+        results: [...standardResults, ...viewResults],
+    };
+}
+function selectResultItems(manifest, options) {
+    const views = [];
+    const standardCharts = [];
+    const groups = [];
+    arrayValues(manifest.tabs).forEach((rawTab) => {
+        const tab = requiredObject(rawTab, "manifest tab");
+        arrayValues(tab.groups).forEach((rawGroup) => {
+            const group = requiredObject(rawGroup, "manifest group");
+            groups.push({ tab, group });
+            arrayValues(group.views).forEach((rawView) => {
+                views.push({ tab, group, view: requiredObject(rawView, "manifest view") });
+            });
+            arrayValues(group.charts).forEach((rawChart) => {
+                standardCharts.push({ tab, group, chart: requiredObject(rawChart, "manifest chart") });
+            });
+        });
+    });
+    const chart = options.chartId || options.chart;
+    if (chart) {
+        const matchingViews = views.filter(({ group, view }) => matchesValue(chart, [
+            view.id,
+            view.title,
+            `${group.id}/${view.id}`,
+            `${group.id}__${view.id}`,
+        ]));
+        const matchingCharts = standardCharts.filter(({ group, chart: standardChart }) => matchesValue(chart, [
+            standardChart.id,
+            standardChart.title,
+            `${group.id}/${standardChart.id}`,
+            `${group.id}__${standardChart.id}`,
+        ]));
+        if (matchingViews.length + matchingCharts.length === 0)
+            throw new Error(`chart not found: ${chart}`);
+        if (matchingViews.length + matchingCharts.length > 1) {
+            const ids = [
+                ...matchingViews.map(({ group, view }) => `${String(group.id)}/${String(view.id)}`),
+                ...matchingCharts.map(({ group, chart: item }) => `${String(group.id)}/${String(item.id)}`),
+            ];
+            throw new Error(`ambiguous_chart_id: ${chart}; candidates: ${ids.join(", ")}`);
+        }
+        return { views: matchingViews, standardCharts: matchingCharts };
+    }
+    const group = options.groupId || options.group;
+    if (group) {
+        const matchingGroups = groups.filter((entry) => matches(group, [entry.group.id, entry.group.title]));
+        if (!matchingGroups.length)
+            throw new Error(`group not found: ${group}`);
+        const selectedGroups = new Set(matchingGroups.map((entry) => entry.group));
+        return {
+            views: views.filter((entry) => selectedGroups.has(entry.group)),
+            standardCharts: standardCharts.filter((entry) => selectedGroups.has(entry.group)),
+        };
+    }
+    const tab = options.tabId || options.tab;
+    if (tab) {
+        const matchingTabs = new Set(groups
+            .filter((entry) => matches(tab, [entry.tab.id, entry.tab.title]))
+            .map((entry) => entry.tab));
+        if (!matchingTabs.size)
+            throw new Error(`tab not found: ${tab}`);
+        return {
+            views: views.filter((entry) => matchingTabs.has(entry.tab)),
+            standardCharts: standardCharts.filter((entry) => matchingTabs.has(entry.tab)),
+        };
+    }
+    throw new Error("report result requires one of --tab, --tab-id, --group, --group-id, --chart, or --chart-id");
+}
+function queryScope(options) {
+    return Object.fromEntries(Object.entries({
+        tab: options.tab,
+        tabId: options.tabId,
+        group: options.group,
+        groupId: options.groupId,
+        chart: options.chart,
+        chartId: options.chartId,
+    }).filter((entry) => typeof entry[1] === "string"));
+}
+function matches(query, candidates) {
+    return matchesValue(query, candidates);
+}
+function matchesValue(query, candidates) {
+    return candidates.some((candidate) => typeof candidate === "string" && candidate.toLocaleLowerCase() === query.toLocaleLowerCase());
+}
+function selectorFilters(group, data, values, rows) {
+    const bindings = objectValue(data.selectorBindings) ?? {};
+    const selectors = arrayValues(group.selectors).map((value) => requiredObject(value, "selector"));
+    return Object.entries(bindings).flatMap(([selectorId, rawField]) => {
+        const selector = selectors.find((item) => item.id === selectorId);
+        const value = values[selectorId] ?? (typeof selector?.defaultValue === "string" ? selector.defaultValue : "all");
+        if (!value || value === "all")
+            return [];
+        const field = String(rawField);
+        const sample = rows.find((row) => row[field] !== undefined)?.[field];
+        const typed = typeof sample === "number" && Number.isFinite(Number(value))
+            ? Number(value)
+            : typeof sample === "boolean" ? value === "true" : value;
+        return [{ field, op: "eq", value: typed }];
+    });
+}
+function reportResult(tab, group, view, fingerprint, columns, rows, extra) {
+    return {
+        tab: { id: tab.id, title: tab.title },
+        group: { id: group.id, title: group.title },
+        chart: view,
+        reportId: `dataset:${fingerprint}`,
+        columns,
+        rows,
+        ...extra,
+    };
+}
+function viewDatasetFingerprint(view) {
+    const fingerprint = requiredObject(view.data, "view.data").datasetFingerprint;
+    if (typeof fingerprint !== "string" || !fingerprint)
+        throw new Error("v2 View is missing datasetFingerprint");
+    return fingerprint;
+}
+function recordRows(value) {
+    return arrayValues(value).map((row) => requiredObject(row, "Dataset row"));
+}
+function requiredObject(value, path) {
+    const object = objectValue(value);
+    if (!object)
+        throw new Error(`${path} must be an object`);
+    return object;
+}
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function arrayValues(value) {
+    return Array.isArray(value) ? value : [];
+}
+function stringArray(value, path) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
+        throw new Error(`${path} must be an array of strings`);
+    return value;
+}

package/dist/report-v2/schema.js

@@ -0,0 +1,18 @@
+export function reportPackSchemaVersion(value) {
+    const pack = objectValue(value);
+    if (!pack)
+        throw new Error("Report Pack must be a JSON object");
+    if (pack.schemaVersion === undefined)
+        return 1;
+    if (pack.schemaVersion === 2)
+        return 2;
+    throw new Error(`unsupported Report Pack schemaVersion: ${String(pack.schemaVersion)}`);
+}
+export function assertWritableReportPackV2(value, command) {
+    if (reportPackSchemaVersion(value) !== 2) {
+        throw new Error(`${command} only accepts Report Pack schemaVersion 2; pull the current Pack and migrate it before writing`);
+    }
+}
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}

package/dist/report-v2/summary.js

@@ -0,0 +1,110 @@
+import { REPORT_SUMMARY_MAX_ITEMS, REPORT_SUMMARY_SCHEMA_VERSION } from "../report-summary.js";
+export function summarizeReportPackV2Manifest(value) {
+    const root = objectValue(value);
+    const manifest = objectValue(root?.manifest);
+    if (!manifest || manifest.schemaVersion !== 2) {
+        return {
+            schemaVersion: REPORT_SUMMARY_SCHEMA_VERSION,
+            command: "report.manifest",
+            ok: false,
+            summary: {},
+            errors: [{ scope: "manifest", message: "Report Pack v2 manifest is missing" }],
+            warnings: [],
+            items: [],
+            truncated: false,
+        };
+    }
+    const tabs = arrayValues(manifest.tabs);
+    const advancedQueries = arrayValues(manifest.advancedQueries);
+    const allItems = [];
+    let groupCount = 0;
+    let viewCount = 0;
+    let standardChartCount = 0;
+    for (const [scope, containers] of [["dashboard", tabs], ["advanced", advancedQueries]]) {
+        for (const rawContainer of containers) {
+            const container = objectValue(rawContainer);
+            for (const rawGroup of arrayValues(container?.groups)) {
+                const group = objectValue(rawGroup);
+                groupCount += 1;
+                for (const rawView of arrayValues(group?.views)) {
+                    const view = objectValue(rawView);
+                    const data = objectValue(view?.data);
+                    viewCount += 1;
+                    allItems.push(compact({
+                        kind: "view",
+                        scope,
+                        containerId: text(container?.id),
+                        containerTitle: text(container?.title),
+                        groupId: text(group?.id),
+                        groupTitle: text(group?.title),
+                        viewId: text(view?.id),
+                        viewTitle: text(view?.title),
+                        viewType: text(view?.type),
+                        datasetId: text(data?.dataset),
+                        datasetFingerprint: text(data?.datasetFingerprint),
+                        selectorIds: arrayValues(group?.selectors).flatMap((rawSelector) => {
+                            const id = text(objectValue(rawSelector)?.id);
+                            return id ? [id] : [];
+                        }),
+                    }));
+                }
+                if (scope === "dashboard") {
+                    for (const rawChart of arrayValues(group?.charts)) {
+                        const chart = objectValue(rawChart);
+                        standardChartCount += 1;
+                        allItems.push(compact({
+                            kind: "standard_chart",
+                            scope,
+                            containerId: text(container?.id),
+                            containerTitle: text(container?.title),
+                            groupId: text(group?.id),
+                            groupTitle: text(group?.title),
+                            standardRef: text(group?.standardRef),
+                            chartId: text(chart?.id),
+                            chartTitle: text(chart?.title),
+                            chartType: text(chart?.type),
+                            reportId: text(chart?.report),
+                        }));
+                    }
+                }
+            }
+        }
+    }
+    const datasets = objectValue(manifest.datasets) ?? {};
+    const items = allItems.slice(0, REPORT_SUMMARY_MAX_ITEMS);
+    return {
+        schemaVersion: REPORT_SUMMARY_SCHEMA_VERSION,
+        command: "report.manifest",
+        ok: true,
+        summary: compact({
+            reportPack: root?.reportPack,
+            reportPackSchemaVersion: 2,
+            title: text(manifest.title),
+            packFingerprint: text(manifest.packFingerprint),
+            tabCount: tabs.length,
+            advancedQueryCount: advancedQueries.length,
+            groupCount,
+            viewCount,
+            standardChartCount,
+            datasetCount: Object.keys(datasets).length,
+            datasetIds: Object.keys(datasets),
+            returnedItemCount: items.length,
+        }),
+        errors: [],
+        warnings: [],
+        items,
+        truncated: allItems.length > items.length,
+    };
+}
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function arrayValues(value) {
+    return Array.isArray(value) ? value : [];
+}
+function text(value) {
+    return typeof value === "string" && value ? value : undefined;
+}
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}

package/dist/report-v2/view-executor.js

@@ -0,0 +1,198 @@
+import { evaluateReportFormula, parseReportFormula, reportFormulaReferences } from "./expression.js";
+const BASE_AGGREGATIONS = new Set(["sum", "min", "max", "count"]);
+/** Pure v2 evaluator. It intentionally has no dependency on legacy reports. */
+export function executeReportPackV2View(rawView, datasetRows, options = {}) {
+    const view = requiredObject(rawView, "view");
+    const data = requiredObject(view.data, "view.data");
+    const groupBy = stringArray(data.groupBy, "view.data.groupBy");
+    const metrics = requiredObject(data.metrics, "view.data.metrics");
+    if (!Object.keys(metrics).length)
+        throw new Error("view.data.metrics must not be empty");
+    const selectorFilters = Array.isArray(options.selectorFilters) ? options.selectorFilters : [];
+    const filteredRows = datasetRows.filter((row) => (matchesFilter(row, data.filter)
+        && selectorFilters.every((filter) => matchesFilter(row, filter))));
+    const groups = groupRows(filteredRows, groupBy);
+    const formulas = prepareFormulas(metrics);
+    const rows = [];
+    for (const group of groups.values()) {
+        const output = { ...group.dimensions };
+        for (const [metricId, rawDefinition] of Object.entries(metrics)) {
+            const definition = objectValue(rawDefinition);
+            if (definition?.agg)
+                output[metricId] = aggregateMetric(group.rows, metricId, definition);
+        }
+        evaluateFormulas(output, formulas);
+        rows.push(output);
+    }
+    if (!filteredRows.length && !groupBy.length) {
+        const output = {};
+        for (const [metricId, rawDefinition] of Object.entries(metrics)) {
+            const definition = objectValue(rawDefinition);
+            if (definition?.agg)
+                output[metricId] = aggregateMetric([], metricId, definition);
+        }
+        evaluateFormulas(output, formulas);
+        rows.push(output);
+    }
+    const orderBy = normalizeOrderBy(view.orderBy);
+    if (orderBy.length) {
+        const stable = [
+            ...orderBy,
+            ...groupBy.filter((field) => !orderBy.some((order) => order.field === field)).map((field) => ({ field, direction: "asc" })),
+        ];
+        rows.sort((left, right) => compareRows(left, right, stable));
+    }
+    const limit = view.limit === undefined ? undefined : positiveInteger(view.limit, "view.limit");
+    return limit === undefined ? rows : rows.slice(0, limit);
+}
+function groupRows(rows, groupBy) {
+    const groups = new Map();
+    for (const row of rows) {
+        const dimensions = Object.fromEntries(groupBy.map((field) => [field, row[field] ?? null]));
+        const key = JSON.stringify(groupBy.map((field) => [typeof row[field], row[field] ?? null]));
+        const existing = groups.get(key);
+        if (existing)
+            existing.rows.push(row);
+        else
+            groups.set(key, { dimensions, rows: [row] });
+    }
+    return groups;
+}
+function aggregateMetric(rows, metricId, definition) {
+    const aggregation = String(definition.agg || "");
+    if (!BASE_AGGREGATIONS.has(aggregation))
+        throw new Error(`unsupported aggregation for ${metricId}: ${aggregation}`);
+    if (aggregation === "count")
+        return rows.length;
+    const field = String(definition.field || "");
+    if (!field)
+        throw new Error(`view.data.metrics.${metricId}.field is required`);
+    const values = rows.flatMap((row) => typeof row[field] === "number" && Number.isFinite(row[field]) ? [row[field]] : []);
+    if (aggregation === "sum")
+        return values.reduce((sum, value) => sum + value, 0);
+    if (!values.length)
+        return null;
+    return aggregation === "min" ? Math.min(...values) : Math.max(...values);
+}
+function prepareFormulas(metrics) {
+    const formulas = new Map();
+    for (const [metricId, rawDefinition] of Object.entries(metrics)) {
+        const definition = objectValue(rawDefinition);
+        if (typeof definition?.formula !== "string")
+            continue;
+        formulas.set(metricId, {
+            expression: parseReportFormula(definition.formula),
+            references: reportFormulaReferences(definition.formula),
+        });
+    }
+    return formulas;
+}
+function evaluateFormulas(output, formulas) {
+    const pending = new Map(formulas);
+    while (pending.size) {
+        let progressed = false;
+        for (const [metricId, formula] of pending) {
+            if (formula.references.some((reference) => pending.has(reference)))
+                continue;
+            output[metricId] = evaluateReportFormula(formula.expression, output);
+            pending.delete(metricId);
+            progressed = true;
+        }
+        if (!progressed)
+            throw new Error(`formula dependency cycle: ${[...pending.keys()].sort().join(", ")}`);
+    }
+}
+function matchesFilter(row, rawFilter) {
+    if (rawFilter === undefined || rawFilter === null)
+        return true;
+    const filter = requiredObject(rawFilter, "filter");
+    const op = String(filter.op || "");
+    if (op === "and" || op === "or") {
+        if (!Array.isArray(filter.filters))
+            throw new Error(`filter ${op} requires filters`);
+        return op === "and"
+            ? filter.filters.every((child) => matchesFilter(row, child))
+            : filter.filters.some((child) => matchesFilter(row, child));
+    }
+    if (op === "not")
+        return !matchesFilter(row, filter.filter);
+    const field = String(filter.field || "");
+    if (!field)
+        throw new Error("filter.field is required");
+    const actual = row[field] ?? null;
+    if (op === "eq")
+        return Object.is(actual, filter.value ?? null);
+    if (op === "ne")
+        return !Object.is(actual, filter.value ?? null);
+    if (["gt", "gte", "lt", "lte"].includes(op) && (actual === null || filter.value === null || filter.value === undefined))
+        return false;
+    if (op === "gt")
+        return compareValues(actual, filter.value) > 0;
+    if (op === "gte")
+        return compareValues(actual, filter.value) >= 0;
+    if (op === "lt")
+        return compareValues(actual, filter.value) < 0;
+    if (op === "lte")
+        return compareValues(actual, filter.value) <= 0;
+    if (op === "in" || op === "not_in") {
+        if (!Array.isArray(filter.values))
+            throw new Error(`filter ${op} requires values`);
+        const included = filter.values.some((value) => Object.is(actual, value));
+        return op === "in" ? included : !included;
+    }
+    if (op === "is_null")
+        return actual === null;
+    if (op === "is_not_null")
+        return actual !== null;
+    throw new Error(`unsupported filter operation: ${op}`);
+}
+function normalizeOrderBy(value) {
+    if (value === undefined)
+        return [];
+    return (Array.isArray(value) ? value : [value]).map((raw, index) => {
+        const item = requiredObject(raw, `view.orderBy[${index}]`);
+        const field = String(item.field || "");
+        const direction = String(item.direction || "asc");
+        if (!field || (direction !== "asc" && direction !== "desc"))
+            throw new Error(`invalid view.orderBy[${index}]`);
+        return { field, direction };
+    });
+}
+function compareRows(left, right, orders) {
+    for (const order of orders) {
+        const result = compareValues(left[order.field], right[order.field]);
+        if (result)
+            return order.direction === "desc" ? -result : result;
+    }
+    return 0;
+}
+function compareValues(left, right) {
+    if (Object.is(left, right))
+        return 0;
+    if (left === null || left === undefined)
+        return 1;
+    if (right === null || right === undefined)
+        return -1;
+    if (typeof left === "number" && typeof right === "number")
+        return left - right;
+    return String(left).localeCompare(String(right));
+}
+function requiredObject(value, path) {
+    const object = objectValue(value);
+    if (!object)
+        throw new Error(`${path} must be an object`);
+    return object;
+}
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringArray(value, path) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item))
+        throw new Error(`${path} must be an array of strings`);
+    return value;
+}
+function positiveInteger(value, path) {
+    if (!Number.isInteger(value) || Number(value) <= 0)
+        throw new Error(`${path} must be a positive integer`);
+    return Number(value);
+}

package/dist/utils.js

@@ -10,15 +10,15 @@ export function integrationEnvironment(value) {
 }
 export function integrationPlatform(value) {
     const platform = optionalString(value);
-    if (platform === "ios" || platform === "android" || platform === "maker" || platform === "rest")
+    if (platform === "ios" || platform === "android" || platform === "maker" || platform === "web")
         return platform;
-    throw new Error("--platform must be ios, android, maker, or rest");
+    throw new Error("--platform must be ios, android, maker, or web");
 }
 export function experimentPlatform(value) {
     const platform = optionalString(value);
-    if (platform === "ios" || platform === "android" || platform === "rest")
+    if (platform === "ios" || platform === "android" || platform === "maker" || platform === "web")
         return platform;
-    throw new Error("--platform must be ios, android, or rest for experiments");
+    throw new Error("--platform must be ios, android, maker, or web for experiments");
 }
 export function optionalString(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gamealgo-cli",
-  "version": "0.3.9",
+  "version": "0.4.2",
   "description": "GameAlgo command-line client for AI agents and game developers",
   "repository": {
     "type": "git",

package/skills/gamealgo/SKILL.md

@@ -34,7 +34,7 @@ Classify the requested work by the actions it requires, not only by the user's t
 
 Use each topic's section list as the router. Read the whole topic only when the task genuinely spans most of it; when that is necessary, load one full topic per tool call. If any tool marks documentation output as truncated, treat it as incomplete, retrieve the missing sections, and do not infer that unseen guidance is absent or switch workflows based on the partial output.
 
-- SDK installation, identity, lifecycle, telemetry, attribution, advertising, or purchase work: run `gamealgo integration get-plan --environment <domestic|overseas> --platform <ios|android|maker|rest> --json`, then list the `sdk-integration` sections and read the relevant shared and platform-specific sections.
+- SDK installation, identity, lifecycle, telemetry, attribution, advertising, or purchase work: run `gamealgo integration get-plan --environment <domestic|overseas> --platform <ios|android|maker|web> --json`, then list the `sdk-integration` sections and read the relevant shared and platform-specific sections.
 - Calling or changing a concrete public SDK function: additionally run `gamealgo docs api <function> --platform <platform>` for each affected function. Never infer one platform's API from another.
 - Adding or changing events: additionally run `gamealgo events list --days 30 --json` before defining fields or names.
 - Querying an existing dashboard or report: read `gamealgo docs reports --section report-query` plus the section that defines the relevant metric or template. Creating, changing, previewing, or publishing Report Packs, charts, report SQL, or business metrics: list the `reports` sections and read every section affected by the change before interpreting data or editing definitions.
@@ -47,7 +47,17 @@ For `report validate`, `report manifest`, `report preview`, and JSON `report res
 
 When changing an existing Report Pack, run `gamealgo report pull --out <working-pack.json>` before editing and use that current published Pack as the baseline. Do not start from a remembered or stale local copy. Run `gamealgo events diff --pack <working-pack.json>` after defining the Pack events; if it reports missing fields, type conflicts, or blocked/deprecated events, inspect the actual game call sites and prepare real business descriptions rather than inventing catalog text from field names. The diff is read-only and does not authorize `events apply` or event activation.
 
-Validate with the compact default output, then preview every chart or group affected by the change without querying unrelated tabs. A report query must explicitly select a tab, group, or chart. A globally unique bare chart id is accepted; if the Server returns `ambiguous_chart_id`, use its candidate ids and the local Pack structure to retry without asking the developer to choose an internal chart id. Before applying event metadata or publishing the Pack, show the exact changes and impact unless the developer already authorized them. After publishing, pull the effective Pack again and verify the expected manifest or report result.
+Validate with the compact default output, then use `report preview` to inspect v2 validation and generated Dataset SQL without running a warehouse query. After publishing, verify only the affected tab, group, or View with `report result`; do not query unrelated tabs. A report result request must explicitly select a tab, group, or chart/View. A globally unique bare id is accepted; if the Server returns an ambiguity error, use its candidate ids and the local Pack structure to retry without asking the developer to choose an internal id. Before applying event metadata or publishing the Pack, show the exact changes and impact unless the developer already authorized them. After publishing, pull the effective Pack again and verify the expected manifest and materialized result state.
+
+### Use Report Pack v2
+
+Every Report Pack must declare `schemaVersion: 2`. v2 uses independent `datasets`, inline `groups[].views`, platform-owned `groups[].standard`, `tabs`, and optional `experimentViews` and `advancedQueries`. It has no top-level `reports` or `charts` and no author-managed Pack version. Generate, explain, validate, preview, and publish only this structure; do not expose migration-era formats to the developer.
+
+An ordinary v2 Dataset must read only `adn.dwd_gamealgo_events_enriched_di`, include `dt` in its output grain, and be independently computable for each natural day. Before selector filtering, each `datasetFingerprint × platform × dt` must remain at or below 100 rows and 128 KiB. Estimate the output cardinality from every `groupBy` dimension before publishing. If it may exceed either limit, reduce or bucket dimensions, split the business question, or move it into `advancedQueries`; a table View, front-end selector, or `dataset.limit` does not bypass the ordinary limit.
+
+Keep ratio and average components as additive Dataset columns and calculate the final value in the View after range aggregation. For example, materialize `wins` and `attempts`, then define `win_rate = wins / attempts` in `groups[].views[].data.metrics`. Each View references exactly one Dataset. A selector switch is a local View recalculation and must not be modeled as a new warehouse request.
+
+Use `gamealgo report result` to read an existing ordinary v2 materialization for an explicit date range and scope. It never starts a DW query. Use `gamealgo report advanced run --query-id <id> --platform <platform> --from <date> --to <date>` only when an explicit high-dimensional or non-preloaded query is required. `--pack <file>` supplies an immutable v2 Pack snapshot for that Run without publishing it. `advanced get` and `advanced list` only read the saved Run/history. Advanced results are whole-run bounded to 20,000 rows and 20 MiB and retained for 30 days; never replace this path with local production scans or a hidden query side channel.
 
 For initial integration or business dashboard work, standard dashboards are only the baseline. During the initial integration, inspect the actual game loop and define a separate game-specific new-user flow dashboard with meaningful milestones and drop-off diagnostics. Add required milestone telemetry and event catalog fields in the same integration instead of waiting for production volume. Validate the pipeline with test data; label business conclusions as awaiting data when production samples are immature, but do not omit the dashboard design.
 
@@ -79,7 +89,7 @@ Reading documentation does not grant permission to mutate production. CLI and Se
 For SDK integration or telemetry changes, determine the actual deployment environment and runtime platform, then run:
 
 ```bash
-gamealgo integration get-plan --environment <domestic|overseas> --platform <ios|android|maker|rest> --json
+gamealgo integration get-plan --environment <domestic|overseas> --platform <ios|android|maker|web> --json
 ```
 
 Inspect the existing project before editing. Reuse existing SDK wrappers, user identity, lifecycle, event, advertising, purchase, and attribution flows.
@@ -166,11 +176,11 @@ Before delivery, inspect changed client code for Variant or assignment-identity
 
 ## Preserve Experiment Platform Scope
 
-A Strategy key is shared by the game and keeps a global fallback default, while every Run belongs to exactly one runtime platform: `ios`, `android`, or `rest` (`rest` includes TapTap Maker). A promoted Run updates only its own platform default. Other platform defaults remain unchanged, and a platform without an explicit default continues to use the global fallback.
+A Strategy key is shared by the game and keeps a global fallback default, while every Run belongs to exactly one runtime platform: `ios`, `android`, `maker`, or `web`. A promoted Run updates only its own platform default. Other platform defaults remain unchanged, and a platform without an explicit default continues to use the global fallback.
 
 - When a Run includes `variantId: default`, the Server snapshots the effective default for that Run's platform, falling back to the global Strategy default only when that platform has no promoted default.
 - `experiment run promote` needs no platform flag because the Run records its platform.
-- When rolling a platform back to a global historical version, pass `experiment strategy rollback ... --platform <ios|android|rest>` so the global version is copied into that platform default rather than replacing the global fallback.
+- When rolling a platform back to a global historical version, pass `experiment strategy rollback ... --platform <ios|android|maker|web>` so the global version is copied into that platform default rather than replacing the global fallback.
 - Treat `experiment strategy publish` and `experiment strategy default` as global-fallback operations; they do not overwrite existing promoted platform defaults.
 
 ## Require Explicit Approval Before Publishing Experiments