@mpgd/cli 0.40.0 → 0.41.0

package/dist/game-acceptance.d.ts

@@ -1,3 +1,4 @@
+import { type PerformanceAcceptanceEvidence, type PerformanceAcceptanceInput } from './performance-acceptance.js';
 export declare const defaultGameAcceptanceCommandTimeoutMs: number;
 export declare const maximumGameplayE2EReportBytes: number;
 export declare function resolveGameAcceptanceReleaseManifestFile(gameRoot: string, env?: NodeJS.ProcessEnv): string;
@@ -32,6 +33,7 @@ export interface GameAcceptanceReport {
   readonly options: Readonly<Record<string, string | boolean | null>>;
   readonly steps: readonly GameAcceptanceStepResult[];
   readonly evidence: {
+    readonly performance?: PerformanceAcceptanceEvidence;
     readonly releaseManifest: {
       readonly file: string;
       readonly found: boolean;
@@ -57,6 +59,8 @@ export interface RunGameAcceptanceInput {
   readonly reportDir: string;
   readonly releaseManifestFile?: string;
   readonly gameplayE2EReportFile?: string;
+  /** Optional fresh performance collection and consumer-authored budget. */
+  readonly performance?: PerformanceAcceptanceInput;
   readonly requireGameplayE2EReport?: boolean;
   /** Step that must replace any previous gameplay report before evidence is accepted. */
   readonly gameplayE2EStepId?: string;

package/dist/game-acceptance.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import { escapeMarkdownInline, escapeMarkdownTable, formatDuration, formatError, readBoundedUtf8File, relativeOrAbsolute, writeEvidenceReportFiles, } from './evidence-io.js';
 import { collectGameplayE2EPathEvidence, maximumGameplayE2EStates, readGameplayE2EPlan, resolveGameplayE2EPathInsideGameRoot, } from './gameplay-e2e.js';
+import { preparePerformanceAcceptance, readPerformanceAcceptanceEvidence, } from './performance-acceptance.js';
 export const defaultGameAcceptanceCommandTimeoutMs = 30 * 60 * 1_000;
 const defaultGameAcceptanceReleaseManifestFile = 'artifacts/release-manifest.json';
 export const maximumGameplayE2EReportBytes = 1_024 * 1_024;
@@ -22,10 +23,25 @@ export function runGameAcceptance(input) {
     const commandRunner = input.commandRunner
         ?? ((step) => runAcceptanceCommand(step, input.env ?? process.env, commandTimeoutMs));
     const gameRoot = path.resolve(input.gameRoot);
+    const reportDir = path.resolve(input.reportDir);
+    const jsonFile = path.join(reportDir, 'acceptance-report.json');
+    const markdownFile = path.join(reportDir, 'acceptance-report.md');
     const startedAtMs = now();
     const results = [];
     let failed = false;
     let gameplayE2EReportFileToReplace;
+    const performance = input.performance === undefined
+        ? undefined
+        : preparePerformanceAcceptance(gameRoot, input.performance);
+    if (performance !== undefined && [jsonFile, markdownFile].some((file) => file === performance.reportFile || file === path.resolve(gameRoot, performance.budgetEvidence.file))) {
+        throw new Error('Performance budget and report must not overwrite acceptance handoff files.');
+    }
+    let performanceStartedAtMs;
+    if (input.performance !== undefined
+        && (input.steps.filter((step) => step.id === input.performance?.stepId).length !== 1
+            || input.steps.some((step) => step.id === input.performance?.stepId && step.skipReason !== undefined))) {
+        throw new Error('Performance evidence needs exactly one runnable collection step.');
+    }
     if (input.gameplayE2EStepId !== undefined) {
         if (input.gameplayE2EReportFile === undefined) {
             throw new Error('A gameplay E2E evidence step needs a report file.');
@@ -50,6 +66,16 @@ export function runGameAcceptance(input) {
                 continue;
             }
         }
+        if (!failed && step.id === input.performance?.stepId && performance !== undefined) {
+            try {
+                rmSync(resolveGameplayE2EPathInsideGameRoot(gameRoot, performance.reportFile, 'Performance report'), { force: true });
+            }
+            catch (error) {
+                results.push(failedStepResult(step, now(), formatError(error)));
+                failed = true;
+                continue;
+            }
+        }
         if (failed) {
             results.push(skippedStepResult(step, now(), 'A previous acceptance step failed.'));
             continue;
@@ -70,6 +96,9 @@ export function runGameAcceptance(input) {
         const cwd = path.resolve(runnableStep.cwd);
         const stepStartedAtMs = now();
         const startedAt = new Date(stepStartedAtMs).toISOString();
+        if (step.id === input.performance?.stepId) {
+            performanceStartedAtMs = stepStartedAtMs;
+        }
         log(`[mpgd:accept] ${step.label}`);
         let commandResult;
         try {
@@ -103,11 +132,23 @@ export function runGameAcceptance(input) {
             || !gameplayE2E.found
             || gameplayE2E.parseError !== null
             || gameplayE2E.validationError !== null);
+    const performanceEvidence = performance === undefined
+        ? undefined
+        : readPerformanceAcceptanceEvidence({
+            gameRoot,
+            prepared: performance,
+            startedAtMs: performanceStartedAtMs,
+            finishedAtMs: now(),
+            profile: typeof input.options.profile === 'string' ? input.options.profile : undefined,
+            releaseManifestFile: input.releaseManifestFile,
+        });
+    const performanceFailed = performanceEvidence?.validationError !== undefined
+        && performanceEvidence.validationError !== null;
     const finishedAtMs = now();
     const report = {
         schemaVersion: 1,
         generatedAt: new Date(finishedAtMs).toISOString(),
-        status: failed || evidenceFailed ? 'failed' : 'passed',
+        status: failed || evidenceFailed || performanceFailed ? 'failed' : 'passed',
         gameRoot,
         durationMs: Math.max(0, finishedAtMs - startedAtMs),
         options: input.options,
@@ -115,11 +156,9 @@ export function runGameAcceptance(input) {
         evidence: {
             releaseManifest,
             gameplayE2E,
+            ...(performanceEvidence === undefined ? {} : { performance: performanceEvidence }),
         },
     };
-    const reportDir = path.resolve(input.reportDir);
-    const jsonFile = path.join(reportDir, 'acceptance-report.json');
-    const markdownFile = path.join(reportDir, 'acceptance-report.md');
     mkdirSync(reportDir, { recursive: true });
     writeEvidenceReportFiles({
         jsonFile,
@@ -180,6 +219,12 @@ export function renderGameAcceptanceMarkdown(report) {
     else {
         lines.push(`- Gameplay E2E report: ${escapeMarkdownInline(report.evidence.gameplayE2E.file)}`);
     }
+    if (report.evidence.performance !== undefined) {
+        const performance = report.evidence.performance;
+        lines.push('', '## Performance Evidence', '', `- Report: ${escapeMarkdownInline(performance.file)}`, `- Budget: ${escapeMarkdownInline(performance.budget.file)} (${performance.budget.sha256})`, performance.validationError === null
+            ? '- Budget validation passed.'
+            : `- Validation failed: ${escapeMarkdownInline(performance.validationError)}`);
+    }
     return `${lines.join('\n')}\n`;
 }
 function runAcceptanceCommand(step, env, timeoutMs) {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { renderGameAcceptanceMarkdown, resolveGameAcceptanceReleaseManifestFile, runGameAcceptance, defaultGameAcceptanceCommandTimeoutMs, maximumGameplayE2EReportBytes, type GameAcceptanceCommandResult, type GameAcceptanceCommandRunner, type GameAcceptanceReport, type GameAcceptanceStatus, type GameAcceptanceStep, type GameAcceptanceStepResult, type GameAcceptanceStepStatus, type RunGameAcceptanceInput, type RunGameAcceptanceResult, } from './game-acceptance.js';
+export { maximumPerformanceEvidenceBytes, preparePerformanceAcceptance, readPerformanceAcceptanceEvidence, validatePerformanceBudget, type PerformanceAcceptanceEvidence, type PerformanceAcceptanceInput, type PerformanceBudget, type PerformanceBudgetProfile, type PerformanceMetricBudget, type PreparedPerformanceAcceptance, } from './performance-acceptance.js';
 export { applyCapacitorShellStarter, materializeCapacitorShellStarter, planCapacitorShellStarter, type CapacitorShellCommandRunner, type CapacitorShellStarterInput, type CapacitorShellStarterPlan, } from './capacitor-shell-starter.js';
 export { ReleaseProcessError, runReleaseProcess, type ReleaseProcessInput, type ReleaseProcessResult, } from './deploy-process.js';
 export { installPinnedReleaseDependencies, pinNativeDeploymentPlan, preparePinnedReleaseWorkspace, runPinnedNativeBuild, withPinnedReleaseWorkspace, type PinnedNativeBuildResult, type PinnedReleaseInput, type PinnedReleaseWorkspace, } from './release-workspace.js';

package/dist/index.js

@@ -18,7 +18,7 @@ import { initializeNativeDeployWorkflow } from './native-deploy-workflow.js';
 import { normalizeConfiguredBuildTargets, normalizeBuildTarget as normalizeConfiguredTargetName, supportedBuildTargets, } from './build-targets.js';
 import { escapeMarkdownInline as escapeEvidenceMarkdownInline, writeEvidenceReportFiles, } from './evidence-io.js';
 import { defaultGameAcceptanceCommandTimeoutMs, resolveGameAcceptanceReleaseManifestFile, runGameAcceptance, } from './game-acceptance.js';
-import { resolveGameplayE2EReportFile } from './gameplay-e2e.js';
+import { resolveGameplayE2EPathInsideGameRoot, resolveGameplayE2EReportFile, } from './gameplay-e2e.js';
 import { cloudflarePagesDeploymentProfiles, hostedPwaDeploymentHosts, verifyHostedPwaDeployment, } from './hosted-pwa-deployment.js';
 import { createMicrosoftStorePackageAcceptanceRuntime, runMicrosoftStorePackageAcceptance, } from './microsoft-store-package-acceptance.js';
 import { runMicrosoftStorePackageGeneration } from './microsoft-store-package-generation.js';
@@ -31,6 +31,7 @@ import { readStoreCredential, runNativeDeployment } from './native-deploy-run.js
 import { submitRecordedNativeTarget } from './native-deploy-submission.js';
 import { readNativeReleaseStatus as readNativeReleaseStatusForCli } from './release-state.js';
 export { renderGameAcceptanceMarkdown, resolveGameAcceptanceReleaseManifestFile, runGameAcceptance, defaultGameAcceptanceCommandTimeoutMs, maximumGameplayE2EReportBytes, } from './game-acceptance.js';
+export { maximumPerformanceEvidenceBytes, preparePerformanceAcceptance, readPerformanceAcceptanceEvidence, validatePerformanceBudget, } from './performance-acceptance.js';
 export { applyCapacitorShellStarter, materializeCapacitorShellStarter, planCapacitorShellStarter, } from './capacitor-shell-starter.js';
 export { ReleaseProcessError, runReleaseProcess, } from './deploy-process.js';
 export { installPinnedReleaseDependencies, pinNativeDeploymentPlan, preparePinnedReleaseWorkspace, runPinnedNativeBuild, withPinnedReleaseWorkspace, } from './release-workspace.js';
@@ -111,6 +112,7 @@ const acceptanceStepIds = {
     targetBuild: 'target-build',
     targetSmoke: 'target-smoke',
     gameplayE2E: 'gameplay-e2e',
+    performance: 'performance',
 };
 /** Whether the last run reported a deadline failure that leaves
  * uncancellable filesystem work pending: the standalone binary forces its
@@ -725,6 +727,18 @@ const gameCommand = defineI18n({
                     required: false,
                     description: 'Skip the game-owned playtest package script.',
                 },
+                performance: {
+                    type: 'boolean', required: false,
+                    description: 'Collect and validate fresh foreground performance evidence.',
+                },
+                'performance-script': {
+                    type: 'string', required: false, default: 'performance:e2e',
+                    description: 'Game-owned performance collection package script.',
+                },
+                'performance-budget': {
+                    type: 'string', required: false, default: 'agent/performance.budget.json',
+                    description: 'Consumer-authored performance budget JSON inside the game root.',
+                },
                 'skip-gameplay-e2e': {
                     type: 'boolean',
                     required: false,
@@ -764,6 +778,9 @@ const gameCommand = defineI18n({
                     skipGraph: ctx.values['skip-graph'] === true,
                     skipPlaytest: ctx.values['skip-playtest'] === true,
                     skipGameplayE2E: ctx.values['skip-gameplay-e2e'] === true,
+                    performance: ctx.values.performance === true,
+                    performanceScript: readOptionalString(ctx.values['performance-script']) ?? 'performance:e2e',
+                    performanceBudget: readOptionalString(ctx.values['performance-budget']) ?? 'agent/performance.budget.json',
                     skipTargetBuild: ctx.values['skip-target-build'] === true,
                     skipTargetSmoke: ctx.values['skip-target-smoke'] === true,
                 });
@@ -923,7 +940,7 @@ function acceptGame(input) {
     const packageManager = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm';
     const gameplayE2EEnabled = !input.skipGameplayE2E
         && gamePackage.scripts?.[input.gameplayScript] !== undefined;
-    const gameplayE2ETargets = gameplayE2EEnabled
+    const gameplayE2ETargets = gameplayE2EEnabled || input.performance
         ? parseTargetList(input.targets, {
             ...process.env,
             MPGD_PLATFORM_TARGETS_FILE: targetsFile,
@@ -1014,12 +1031,30 @@ function acceptGame(input) {
             skipped: input.skipGameplayE2E,
         }),
     ];
+    const performanceReportFile = input.performance
+        ? resolveGameplayE2EPathInsideGameRoot(gameRoot, readOptionalString(process.env.MPGD_PERFORMANCE_REPORT_FILE) ?? 'artifacts/performance/report.json', 'Performance report')
+        : undefined;
+    if (input.performance) {
+        steps.push(packageScriptAcceptanceStep({
+            id: acceptanceStepIds.performance,
+            label: 'Foreground performance collection',
+            script: input.performanceScript,
+            gameRoot,
+            packageManager,
+            scripts: gamePackage.scripts,
+            required: true,
+        }));
+    }
     const reportDir = path.resolve(gameRoot, input.reportDir ?? 'artifacts/acceptance');
     const releaseManifestFile = resolveGameAcceptanceReleaseManifestFile(gameRoot);
     const gameplayE2EReportFile = resolveGameplayE2EReportFile(gameRoot);
     const result = runGameAcceptance({
         gameRoot,
         reportDir,
+        ...(performanceReportFile === undefined ? {} : { performance: {
+                budgetFile: input.performanceBudget, reportFile: performanceReportFile,
+                stepId: acceptanceStepIds.performance, targets: gameplayE2ETargets,
+            } }),
         ...(input.skipTargetBuild
             ? {}
             : { releaseManifestFile }),
@@ -1038,6 +1073,8 @@ function acceptGame(input) {
             iosVariant: input.iosVariant ?? null,
             playtestScript: input.playtestScript,
             gameplayScript: input.gameplayScript,
+            ...(input.performance ? { performance: true, performanceScript: input.performanceScript,
+                performanceBudget: input.performanceBudget } : {}),
             skipTest: input.skipTest,
             skipGraph: input.skipGraph,
             skipPlaytest: input.skipPlaytest,
@@ -1051,12 +1088,16 @@ function acceptGame(input) {
         env: {
             ...process.env,
             MPGD_KIT_PATH: kitPath,
-            MPGD_ACCEPTANCE_TARGETS: gameplayE2EEnabled
+            MPGD_ACCEPTANCE_TARGETS: gameplayE2EEnabled || input.performance
                 ? gameplayE2ETargets.join(',')
                 : input.targets,
             MPGD_ACCEPTANCE_PROFILE: input.profile,
             MPGD_RELEASE_MANIFEST_FILE: releaseManifestFile,
             MPGD_GAMEPLAY_E2E_REPORT_FILE: gameplayE2EReportFile,
+            ...(performanceReportFile === undefined ? {} : {
+                MPGD_PERFORMANCE_REPORT_FILE: performanceReportFile,
+                MPGD_PERFORMANCE_BUDGET_FILE: path.resolve(gameRoot, input.performanceBudget),
+            }),
         },
     });
     console.info(`[mpgd:accept] JSON report: ${result.jsonFile}`);

package/dist/native-build-info.json

@@ -1,5 +1,5 @@
 {
-  "kitGitSha": "ccd019a49651a6730a4f0214d9dfcf0094bda226",
+  "kitGitSha": "ca727bc6ebd8c1ecb7515ceb76f48ea5e913ab82",
   "kitDirty": false,
-  "packageVersion": "0.40.0"
+  "packageVersion": "0.41.0"
 }

package/dist/performance-acceptance.d.ts

@@ -0,0 +1,56 @@
+import { type GameplayE2EPathEvidence } from './gameplay-e2e.js';
+export declare const maximumPerformanceEvidenceBytes: number;
+export interface PerformanceMetricBudget {
+  readonly p95?: number;
+  readonly p99?: number;
+  readonly max?: number;
+}
+export interface PerformanceBudgetProfile {
+  readonly id: string;
+  readonly target: string;
+  readonly scenario: string;
+  readonly renderer: string;
+  readonly device: string;
+  readonly minSamples: number;
+  readonly metrics: Readonly<Record<string, PerformanceMetricBudget>>;
+  readonly maxExcludedFrames?: number;
+  readonly maxHeapGrowthBytes?: number;
+  readonly hitchThresholdMs?: number;
+  readonly maxHitches?: number;
+}
+export interface PerformanceBudget {
+  readonly schemaVersion: 1;
+  readonly profiles: readonly PerformanceBudgetProfile[];
+}
+export interface PerformanceAcceptanceInput {
+  readonly budgetFile: string;
+  readonly reportFile: string;
+  readonly stepId: string;
+  readonly targets: readonly string[];
+}
+export interface PreparedPerformanceAcceptance {
+  readonly budget: PerformanceBudget;
+  readonly budgetEvidence: GameplayE2EPathEvidence;
+  readonly reportFile: string;
+}
+export interface PerformanceAcceptanceEvidence {
+  readonly file: string;
+  readonly found: boolean;
+  readonly validationError: string | null;
+  readonly budget: GameplayE2EPathEvidence;
+  readonly report: GameplayE2EPathEvidence | null;
+  readonly value: unknown;
+}
+/** Consumer-authored budgets: no universal device/FPS thresholds are supplied. */
+export declare function validatePerformanceBudget(value: unknown): PerformanceBudget;
+export declare function preparePerformanceAcceptance(gameRoot: string, input: PerformanceAcceptanceInput): PreparedPerformanceAcceptance;
+/** Accept only fresh untraced foreground measurements with matching authored
+* context, adequate sample counts and current artifact/budget provenance. */
+export declare function readPerformanceAcceptanceEvidence(input: {
+  readonly gameRoot: string;
+  readonly prepared: PreparedPerformanceAcceptance;
+  readonly startedAtMs: number | undefined;
+  readonly finishedAtMs: number;
+  readonly profile: string | undefined;
+  readonly releaseManifestFile?: string | undefined;
+}): PerformanceAcceptanceEvidence;

package/dist/performance-acceptance.js

@@ -0,0 +1,269 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { formatError, readBoundedUtf8File, relativeOrAbsolute } from './evidence-io.js';
+import { collectGameplayE2EPathEvidence, resolveGameplayE2EPathInsideGameRoot, } from './gameplay-e2e.js';
+export const maximumPerformanceEvidenceBytes = 1_024 * 1_024;
+function record(value, label) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    return value;
+}
+function text(value, label) {
+    if (typeof value !== 'string' || value.trim().length === 0 || value.length > 256) {
+        throw new Error(`${label} must be a bounded non-empty string.`);
+    }
+    return value;
+}
+function number(value, label, signed = false) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || (!signed && value < 0)) {
+        throw new Error(`${label} must be a finite ${signed ? '' : 'non-negative '}number.`);
+    }
+    return value;
+}
+function count(value, label, min = 0) {
+    const n = number(value, label);
+    if (!Number.isSafeInteger(n) || n < min || n > 1_000_000_000) {
+        throw new Error(`${label} must be an integer between ${min} and 1000000000.`);
+    }
+    return n;
+}
+function keys(value, allowed, label) {
+    if (Object.keys(value).some((key) => !allowed.includes(key))) {
+        throw new Error(`${label} contains an unknown field.`);
+    }
+}
+/** Consumer-authored budgets: no universal device/FPS thresholds are supplied. */
+export function validatePerformanceBudget(value) {
+    const input = record(value, 'Performance budget');
+    keys(input, ['schemaVersion', 'profiles'], 'Performance budget');
+    if (input.schemaVersion !== 1 || !Array.isArray(input.profiles)
+        || input.profiles.length === 0 || input.profiles.length > 64) {
+        throw new Error('Performance budget needs schemaVersion 1 and 1–64 profiles.');
+    }
+    const ids = new Set();
+    const profiles = input.profiles.map((item) => {
+        const profile = record(item, 'Performance profile');
+        keys(profile, ['id', 'target', 'scenario', 'renderer', 'device', 'minSamples', 'metrics',
+            'maxExcludedFrames', 'maxHeapGrowthBytes', 'hitchThresholdMs', 'maxHitches'], 'Performance profile');
+        for (const name of ['id', 'target', 'scenario', 'renderer', 'device']) {
+            text(profile[name], `Performance profile ${name}`);
+        }
+        const id = text(profile.id, 'Performance profile id');
+        if (ids.has(id)) {
+            throw new Error(`Duplicate performance profile: ${id}`);
+        }
+        ids.add(id);
+        count(profile.minSamples, `${id} minSamples`, 2);
+        const metrics = record(profile.metrics, `${id} metrics`);
+        const metricNames = Object.keys(metrics);
+        const builtInMetrics = ['intervalMs', 'totalCpuMs'];
+        const customNames = metricNames.filter((field) => !builtInMetrics.includes(field));
+        if (metricNames.length === 0 || customNames.length > 64) {
+            throw new Error(`${id} needs 1–66 metric budgets.`);
+        }
+        if (customNames.some((field) => field.length > 64 || !/^[a-z][a-zA-Z0-9]*$/.test(field)
+            || ['constructor', 'prototype'].includes(field))) {
+            throw new Error(`${id} has an invalid profiler metric name.`);
+        }
+        for (const [field, itemBudget] of Object.entries(metrics)) {
+            text(field, 'Performance metric name');
+            const budget = record(itemBudget, `${id}/${field} budget`);
+            keys(budget, ['p95', 'p99', 'max'], `${id}/${field} budget`);
+            if (Object.keys(budget).length === 0) {
+                throw new Error(`${id}/${field} needs a threshold.`);
+            }
+            for (const [quantile, threshold] of Object.entries(budget)) {
+                number(threshold, `${id}/${field}/${quantile}`);
+            }
+        }
+        for (const name of ['maxHeapGrowthBytes', 'hitchThresholdMs']) {
+            if (profile[name] !== undefined) {
+                number(profile[name], `${id} ${name}`);
+            }
+        }
+        for (const name of ['maxExcludedFrames', 'maxHitches']) {
+            if (profile[name] !== undefined) {
+                count(profile[name], `${id} ${name}`);
+            }
+        }
+        if ((profile.maxHitches === undefined) !== (profile.hitchThresholdMs === undefined)
+            || profile.hitchThresholdMs === 0) {
+            throw new Error(`${id} hitch budgets need maxHitches and a positive hitchThresholdMs.`);
+        }
+        const snapshot = structuredClone(profile);
+        for (const metric of Object.values(snapshot.metrics)) {
+            Object.freeze(metric);
+        }
+        Object.freeze(snapshot.metrics);
+        return Object.freeze(snapshot);
+    });
+    return Object.freeze({ schemaVersion: 1, profiles: Object.freeze(profiles) });
+}
+function readJson(file, label) {
+    const content = readBoundedUtf8File(file, maximumPerformanceEvidenceBytes);
+    if (content === null) {
+        throw new Error(`${label} exceeds its byte limit.`);
+    }
+    return JSON.parse(content);
+}
+function evidence(gameRoot, value, label) {
+    const input = record(value, label);
+    const file = text(input.file, `${label} file`);
+    const current = collectGameplayE2EPathEvidence(gameRoot, file, label);
+    if (current.kind === 'symbolic-link' || current.kind !== input.kind || current.sha256 !== input.sha256) {
+        throw new Error(`${label} no longer matches its current file/directory hash.`);
+    }
+    return current;
+}
+export function preparePerformanceAcceptance(gameRoot, input) {
+    const budgetFile = resolveGameplayE2EPathInsideGameRoot(gameRoot, input.budgetFile, 'Performance budget');
+    const reportFile = resolveGameplayE2EPathInsideGameRoot(gameRoot, input.reportFile, 'Performance report');
+    if (budgetFile === reportFile) {
+        throw new Error('Performance report must not overwrite its budget.');
+    }
+    const budget = validatePerformanceBudget(readJson(budgetFile, 'Performance budget'));
+    if (budget.profiles.some((profile) => !input.targets.includes(profile.target))) {
+        throw new Error('Performance budget targets must belong to the selected acceptance targets.');
+    }
+    const budgetEvidence = collectGameplayE2EPathEvidence(gameRoot, budgetFile, 'Performance budget');
+    if (budgetEvidence.kind !== 'file') {
+        throw new Error('Performance budget must be a regular file.');
+    }
+    return Object.freeze({ budget, budgetEvidence: Object.freeze(budgetEvidence), reportFile });
+}
+/** Accept only fresh untraced foreground measurements with matching authored
+ * context, adequate sample counts and current artifact/budget provenance. */
+export function readPerformanceAcceptanceEvidence(input) {
+    const { gameRoot, prepared } = input;
+    const result = {
+        file: relativeOrAbsolute(gameRoot, prepared.reportFile),
+        found: false,
+        validationError: null,
+        budget: prepared.budgetEvidence,
+        report: null,
+        value: null,
+    };
+    let value;
+    try {
+        const file = resolveGameplayE2EPathInsideGameRoot(gameRoot, prepared.reportFile, 'Performance report');
+        if (!existsSync(file)) {
+            throw new Error('Performance collector did not produce its report.');
+        }
+        value = readJson(file, 'Performance report');
+        const reportEvidence = collectGameplayE2EPathEvidence(gameRoot, file, 'Performance report');
+        const report = record(value, 'Performance report');
+        if (report.schemaVersion !== 1 || input.startedAtMs === undefined) {
+            throw new Error('Performance report needs schemaVersion 1 and a completed collection step.');
+        }
+        text(report.profile, 'Performance report profile');
+        const at = Date.parse(text(report.generatedAt, 'Performance generatedAt'));
+        if (!Number.isFinite(at) || new Date(at).toISOString() !== report.generatedAt
+            || at < input.startedAtMs || at > input.finishedAtMs) {
+            throw new Error('Performance report timestamp must be inside this collection run.');
+        }
+        if (input.profile !== undefined && report.profile !== input.profile) {
+            throw new Error('Performance report profile must match acceptance.');
+        }
+        const currentBudget = evidence(gameRoot, report.budget, 'Performance budget');
+        if (currentBudget.file !== prepared.budgetEvidence.file
+            || currentBudget.sha256 !== prepared.budgetEvidence.sha256) {
+            throw new Error('Performance budget changed during acceptance.');
+        }
+        if (!Array.isArray(report.measurements) || report.measurements.length !== prepared.budget.profiles.length) {
+            throw new Error('Performance report must cover every budget profile exactly once.');
+        }
+        const seen = new Set();
+        const release = input.releaseManifestFile === undefined
+            ? undefined
+            : record(readJson(input.releaseManifestFile, 'Release manifest'), 'Release manifest');
+        for (const item of report.measurements) {
+            const measurement = record(item, 'Performance measurement');
+            const id = text(measurement.id, 'Performance measurement id');
+            const budget = prepared.budget.profiles.find((profile) => profile.id === id);
+            if (budget === undefined || seen.has(id)) {
+                throw new Error('Performance measurements have missing/duplicate profiles.');
+            }
+            seen.add(id);
+            const context = record(measurement.context, `${id} context`);
+            for (const name of ['target', 'scenario', 'renderer', 'device']) {
+                if (context[name] !== budget[name]) {
+                    throw new Error(`${id} ${name} does not match its budget.`);
+                }
+            }
+            const dpr = number(context.devicePixelRatio, `${id} devicePixelRatio`);
+            if (dpr === 0 || dpr > 64 || context.foreground !== true) {
+                throw new Error(`${id} must record a positive DPR and foreground measurement.`);
+            }
+            const instrumentation = record(context.instrumentation, `${id} instrumentation`);
+            if (instrumentation.trace !== false || instrumentation.screenshots !== false) {
+                throw new Error(`${id} needs an untraced measurement without screenshot capture.`);
+            }
+            for (const name of ['logicalWidth', 'logicalHeight', 'backingWidth', 'backingHeight']) {
+                if (number(context[name], `${id} ${name}`) === 0) {
+                    throw new Error(`${id} dimensions must be positive.`);
+                }
+            }
+            const artifact = evidence(gameRoot, measurement.artifact, `${id} target artifact`);
+            if (release !== undefined) {
+                const target = record(record(release.targets, 'Release targets')[budget.target], `${id} release target`);
+                if (typeof target.artifact !== 'string'
+                    || path.resolve(gameRoot, target.artifact) !== path.resolve(gameRoot, artifact.file)
+                    || (target.profile !== undefined && target.profile !== report.profile)) {
+                    throw new Error(`${id} artifact/profile differs from the release target.`);
+                }
+            }
+            const snapshot = record(measurement.snapshot, `${id} snapshot`);
+            const metrics = record(snapshot.metrics, `${id} metrics`);
+            const maximums = record(snapshot.maximums, `${id} maximums`);
+            const samples = record(snapshot.sampleCounts, `${id} sampleCounts`);
+            const retained = count(snapshot.retainedSamples, `${id} retainedSamples`);
+            const frames = count(snapshot.frames, `${id} frames`);
+            const excluded = count(snapshot.excludedFrames, `${id} excludedFrames`);
+            if (frames < retained || (budget.maxExcludedFrames !== undefined && excluded > budget.maxExcludedFrames)) {
+                throw new Error(`${id} has inconsistent frame counts or too many excluded frames.`);
+            }
+            for (const [field, thresholds] of Object.entries(budget.metrics)) {
+                const n = count(samples[field], `${id}/${field} sampleCount`);
+                if (n < budget.minSamples || n > retained) {
+                    throw new Error(`${id}/${field} has insufficient/inconsistent samples.`);
+                }
+                const quantiles = record(metrics[field], `${id}/${field} quantiles`);
+                const p50 = number(quantiles.p50, `${id}/${field} p50`);
+                const p95 = number(quantiles.p95, `${id}/${field} p95`);
+                const p99 = number(quantiles.p99, `${id}/${field} p99`);
+                const max = number(maximums[field], `${id}/${field} max`);
+                if (p50 > p95 || p95 > p99 || p99 > max) {
+                    throw new Error(`${id}/${field} quantiles are inconsistent.`);
+                }
+                for (const [key, threshold] of Object.entries(thresholds)) {
+                    const measured = key === 'max' ? max : number(quantiles[key], `${id}/${field}/${key}`);
+                    if (measured > threshold) {
+                        throw new Error(`${id}/${field} ${key} exceeds its budget.`);
+                    }
+                }
+            }
+            if (budget.maxHeapGrowthBytes !== undefined
+                && number(measurement.heapGrowthBytes, `${id} heapGrowthBytes`, true) > budget.maxHeapGrowthBytes) {
+                throw new Error(`${id} heap growth exceeds its budget.`);
+            }
+            if (budget.maxHitches !== undefined) {
+                const hitches = record(measurement.hitches, `${id} hitches`);
+                const n = count(hitches.count, `${id} hitch count`);
+                const total = count(hitches.samples, `${id} hitch samples`, budget.minSamples);
+                if (n > total || n > budget.maxHitches || hitches.thresholdMs !== budget.hitchThresholdMs) {
+                    throw new Error(`${id} hitches exceed or do not match their budget.`);
+                }
+            }
+        }
+        return { ...result, found: true, report: reportEvidence, value };
+    }
+    catch (error) {
+        return {
+            ...result,
+            found: existsSync(prepared.reportFile),
+            validationError: formatError(error),
+            value: value ?? null,
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -59,8 +59,8 @@
     "vite": "8.1.3",
     "yauzl": "3.4.0",
     "@mpgd/catalog": "0.8.0",
-    "@mpgd/target-config": "0.20.0",
-    "@mpgd/phaser-assets": "0.8.0"
+    "@mpgd/phaser-assets": "0.9.0",
+    "@mpgd/target-config": "0.21.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -68,15 +68,15 @@
     "@types/yauzl": "3.4.0",
     "ttsc": "0.30.4",
     "typescript": "7.0.2",
-    "@mpgd/adapter-ait": "0.13.2",
+    "@mpgd/adapter-ait": "0.13.3",
     "@mpgd/adapter-browser": "0.9.0",
-    "@mpgd/adapter-capacitor": "0.7.3",
+    "@mpgd/adapter-capacitor": "0.7.4",
     "@mpgd/adapter-devvit": "0.9.17",
+    "@mpgd/adapter-verse8": "0.4.3",
     "@mpgd/analytics": "0.4.3",
-    "@mpgd/adapter-verse8": "0.4.2",
     "@mpgd/game-services": "0.19.0",
     "@mpgd/bridge": "0.11.0",
-    "@mpgd/game-runtime": "0.5.0",
+    "@mpgd/game-runtime": "0.6.0",
     "@mpgd/i18n": "0.6.8",
     "@mpgd/platform": "0.17.0"
   },

package/templates/phaser-game/agent/acceptance.md

@@ -82,3 +82,10 @@ the snapshot bounds for persistent controls.
 Build and smoke the configured ONE play target using the game-owned kit path. Validate server-issued reward/checkout binding, raw-byte signed SSV, purchase token API verification, ledger-before-consume/acknowledge, retries without duplicate grants, signed PNS orphan-purchase recovery and atomic cancellation fences. Missing finalization must keep PNS pending; a busy SDK must report native not-started before rejecting a new checkout. Permit five minutes of provider/server clock skew while rejecting timestamps outside the intent window.
 
 Use an authenticated server session rather than the SDK player pseudonym. Confirm ad IDs, real payments, lifecycle, HTTPS iframe hosting and PNS/SSV in ONE store with issued ONEconsole credentials. Generic fixture and artifact smoke do not certify real-app commerce.
+
+Performance evidence can be required with `mpgd game accept . --performance`.
+Provide a game-owned `performance:e2e` script and `agent/performance.budget.json`;
+collect a fresh foreground report at `MPGD_PERFORMANCE_REPORT_FILE`. Calibrate
+per-device/scenario CPU and cadence budgets independently, link the tested
+artifact/budget hashes and keep trace/screenshots in separate diagnostic runs.
+See the [report contract](https://github.com/imjlk/mpgd-kit/blob/main/docs/GAME_PERFORMANCE_ACCEPTANCE.md).