@plasius/gpu-performance 0.1.14 → 0.1.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -111,6 +111,8 @@ interface FrameTargetNegotiationOptions {
111
111
  preferredFrameRates?: readonly number[];
112
112
  minimumFrameRate?: number;
113
113
  maximumFrameRate?: number;
114
+ /** Optional execution reserve in (0, 1]; omission preserves legacy thresholds. */
115
+ frameBudgetRatio?: number;
114
116
  }
115
117
  /**
116
118
  * Negotiated frame target and guardrails used by the control loop.
@@ -231,6 +233,8 @@ interface PerformanceModuleAdapter<Payload = unknown> {
231
233
  authority: ModuleAuthority;
232
234
  importance: ModuleImportance;
233
235
  getSnapshot(): PerformanceModuleSnapshot<Payload>;
236
+ /** Optional upgrade admission. A refusal retains pending governor recovery. */
237
+ canStepUp?(context: PerformanceAdjustmentContext): boolean;
234
238
  stepDown(context: PerformanceAdjustmentContext): PerformanceAdjustmentRecord<Payload> | null;
235
239
  stepUp(context: PerformanceAdjustmentContext): PerformanceAdjustmentRecord<Payload> | null;
236
240
  }
@@ -256,8 +260,17 @@ interface QualityLadderAdapterOptions<Payload = unknown> {
256
260
  importanceSignals?: Readonly<PerformanceImportanceSignals>;
257
261
  levels: readonly ModuleQualityLevel<Payload>[];
258
262
  initialLevel?: number | string;
263
+ recoveryBudget?: QualityRecoveryBudgetOptions;
259
264
  onLevelChange?: (event: QualityLadderChangeEvent<Payload>) => void;
260
265
  }
266
+ /** Opt-in measured recovery; unknown levels remain discoverable. */
267
+ interface QualityRecoveryBudgetOptions {
268
+ /** Fraction of the negotiated frame interval reserved for projected work, in (0, 1]. */
269
+ headroomRatio: number;
270
+ /** Optional adjacent upper/lower work-cost estimates, one per upward step.
271
+ * Paired execution measurements supersede these estimates when available. */
272
+ initialCostRatios?: readonly number[];
273
+ }
261
274
  /**
262
275
  * Public surface for ladder-backed adapters.
263
276
  */
@@ -266,6 +279,9 @@ interface QualityLadderAdapter<Payload = unknown> extends PerformanceModuleAdapt
266
279
  qualityDimensions?: PerformanceQualityDimensions;
267
280
  importanceSignals?: Readonly<PerformanceImportanceSignals>;
268
281
  getCurrentLevel(): ModuleQualityLevel<Payload>;
282
+ /** Record completed execution at the current level before governor.recordFrame. */
283
+ recordFrameTime(frameTimeMs: number): void;
284
+ canStepUp(context: PerformanceAdjustmentContext): boolean;
269
285
  }
270
286
  /**
271
287
  * Budget controls applied to a gpu-worker job type.
@@ -537,6 +553,9 @@ interface GpuPerformanceGovernorOptions {
537
553
  device: DeviceProfileInput | DeviceProfile;
538
554
  target?: FrameTargetNegotiationOptions;
539
555
  modules?: readonly PerformanceModuleAdapter[];
556
+ /** Recover configured initial visual levels as measured headroom permits.
557
+ * Defaults to false; authoritative modules still require explicit scaling permission. */
558
+ recoverInitialLevels?: boolean;
540
559
  adaptation?: GovernorAdaptationOptions;
541
560
  telemetry?: PerformanceTelemetryHooks;
542
561
  }
@@ -626,4 +645,4 @@ declare function createWorkerJobBudgetManifestGraph(manifest: WorkerJobBudgetMan
626
645
  */
627
646
  declare function createWorkerJobBudgetAdaptersFromManifest(manifest: WorkerJobBudgetManifest | readonly WorkerJobBudgetManifestJob[], options?: WorkerJobBudgetManifestAdapterOptions): readonly WorkerJobBudgetAdapter[];
628
647
 
629
- export { type DeviceClass, type DeviceProfile, type DeviceProfileInput, type FrameSample, type FrameTargetNegotiationOptions, type FrameTargetProfile, type GovernorAdaptationOptions, type GovernorDecision, type GovernorErrorRecord, type GovernorMetrics, type GovernorState, type GovernorWorkerGraphPriorityLaneSummary, type GovernorWorkerGraphSummary, type GpuPerformanceGovernorOptions, type GpuTier, type ModuleAuthority, type ModuleImportance, type ModuleQualityLevel, type MotionClass, type PerformanceAdjustmentContext, type PerformanceAdjustmentRecord, type PerformanceBudgetMetadata, type PerformanceDomain, type PerformanceGovernor, type PerformanceImportanceSignals, type PerformanceModuleAdapter, type PerformanceModuleSnapshot, type PerformanceQualityDimensions, type PerformanceTelemetryHooks, type PressureLevel, type QualityDimension, type QualityLadderAdapter, type QualityLadderAdapterOptions, type QualityLadderChangeEvent, type RepresentationBand, type RuntimeMode, type ThermalState, type WavefrontPathTracingBudgetAdapter, type WavefrontPathTracingBudgetAdapterOptions, type WavefrontPathTracingBudgetConfig, type WavefrontPathTracingBudgetControlSummary, type WavefrontPathTracingDenoiseMode, type WavefrontPathTracingVisibilityProbeMode, type WorkerJobBudgetAdapter, type WorkerJobBudgetAdapterOptions, type WorkerJobBudgetConfig, type WorkerJobBudgetManifest, type WorkerJobBudgetManifestAdapterOptions, type WorkerJobBudgetManifestGraph, type WorkerJobBudgetManifestGraphJob, type WorkerJobBudgetManifestJob, type WorkerJobBudgetManifestPerformance, type WorkerJobBudgetManifestPriorityLane, type WorkerJobBudgetSnapshot, type WorkerJobQueueClass, type WorkerSchedulerMode, createDeviceProfile, createGpuPerformanceGovernor, createPerformanceGovernor, createQualityLadderAdapter, createWavefrontPathTracingBudgetAdapter, createWorkerJobBudgetAdapter, createWorkerJobBudgetAdaptersFromManifest, createWorkerJobBudgetManifestGraph, defaultDomainOrder, motionClasses, negotiateFrameTarget, normalizePerformanceBudgetMetadata, normalizeWavefrontPathTracingBudgetConfig, rayTracingQualityDimensions, representationBands, wavefrontPathTracingBudgetControlKeys, wavefrontPathTracingDenoiseModes, wavefrontPathTracingVisibilityProbeModes };
648
+ export { type DeviceClass, type DeviceProfile, type DeviceProfileInput, type FrameSample, type FrameTargetNegotiationOptions, type FrameTargetProfile, type GovernorAdaptationOptions, type GovernorDecision, type GovernorErrorRecord, type GovernorMetrics, type GovernorState, type GovernorWorkerGraphPriorityLaneSummary, type GovernorWorkerGraphSummary, type GpuPerformanceGovernorOptions, type GpuTier, type ModuleAuthority, type ModuleImportance, type ModuleQualityLevel, type MotionClass, type PerformanceAdjustmentContext, type PerformanceAdjustmentRecord, type PerformanceBudgetMetadata, type PerformanceDomain, type PerformanceGovernor, type PerformanceImportanceSignals, type PerformanceModuleAdapter, type PerformanceModuleSnapshot, type PerformanceQualityDimensions, type PerformanceTelemetryHooks, type PressureLevel, type QualityDimension, type QualityLadderAdapter, type QualityLadderAdapterOptions, type QualityLadderChangeEvent, type QualityRecoveryBudgetOptions, type RepresentationBand, type RuntimeMode, type ThermalState, type WavefrontPathTracingBudgetAdapter, type WavefrontPathTracingBudgetAdapterOptions, type WavefrontPathTracingBudgetConfig, type WavefrontPathTracingBudgetControlSummary, type WavefrontPathTracingDenoiseMode, type WavefrontPathTracingVisibilityProbeMode, type WorkerJobBudgetAdapter, type WorkerJobBudgetAdapterOptions, type WorkerJobBudgetConfig, type WorkerJobBudgetManifest, type WorkerJobBudgetManifestAdapterOptions, type WorkerJobBudgetManifestGraph, type WorkerJobBudgetManifestGraphJob, type WorkerJobBudgetManifestJob, type WorkerJobBudgetManifestPerformance, type WorkerJobBudgetManifestPriorityLane, type WorkerJobBudgetSnapshot, type WorkerJobQueueClass, type WorkerSchedulerMode, createDeviceProfile, createGpuPerformanceGovernor, createPerformanceGovernor, createQualityLadderAdapter, createWavefrontPathTracingBudgetAdapter, createWorkerJobBudgetAdapter, createWorkerJobBudgetAdaptersFromManifest, createWorkerJobBudgetManifestGraph, defaultDomainOrder, motionClasses, negotiateFrameTarget, normalizePerformanceBudgetMetadata, normalizeWavefrontPathTracingBudgetConfig, rayTracingQualityDimensions, representationBands, wavefrontPathTracingBudgetControlKeys, wavefrontPathTracingDenoiseModes, wavefrontPathTracingVisibilityProbeModes };
package/dist/index.d.ts CHANGED
@@ -111,6 +111,8 @@ interface FrameTargetNegotiationOptions {
111
111
  preferredFrameRates?: readonly number[];
112
112
  minimumFrameRate?: number;
113
113
  maximumFrameRate?: number;
114
+ /** Optional execution reserve in (0, 1]; omission preserves legacy thresholds. */
115
+ frameBudgetRatio?: number;
114
116
  }
115
117
  /**
116
118
  * Negotiated frame target and guardrails used by the control loop.
@@ -231,6 +233,8 @@ interface PerformanceModuleAdapter<Payload = unknown> {
231
233
  authority: ModuleAuthority;
232
234
  importance: ModuleImportance;
233
235
  getSnapshot(): PerformanceModuleSnapshot<Payload>;
236
+ /** Optional upgrade admission. A refusal retains pending governor recovery. */
237
+ canStepUp?(context: PerformanceAdjustmentContext): boolean;
234
238
  stepDown(context: PerformanceAdjustmentContext): PerformanceAdjustmentRecord<Payload> | null;
235
239
  stepUp(context: PerformanceAdjustmentContext): PerformanceAdjustmentRecord<Payload> | null;
236
240
  }
@@ -256,8 +260,17 @@ interface QualityLadderAdapterOptions<Payload = unknown> {
256
260
  importanceSignals?: Readonly<PerformanceImportanceSignals>;
257
261
  levels: readonly ModuleQualityLevel<Payload>[];
258
262
  initialLevel?: number | string;
263
+ recoveryBudget?: QualityRecoveryBudgetOptions;
259
264
  onLevelChange?: (event: QualityLadderChangeEvent<Payload>) => void;
260
265
  }
266
+ /** Opt-in measured recovery; unknown levels remain discoverable. */
267
+ interface QualityRecoveryBudgetOptions {
268
+ /** Fraction of the negotiated frame interval reserved for projected work, in (0, 1]. */
269
+ headroomRatio: number;
270
+ /** Optional adjacent upper/lower work-cost estimates, one per upward step.
271
+ * Paired execution measurements supersede these estimates when available. */
272
+ initialCostRatios?: readonly number[];
273
+ }
261
274
  /**
262
275
  * Public surface for ladder-backed adapters.
263
276
  */
@@ -266,6 +279,9 @@ interface QualityLadderAdapter<Payload = unknown> extends PerformanceModuleAdapt
266
279
  qualityDimensions?: PerformanceQualityDimensions;
267
280
  importanceSignals?: Readonly<PerformanceImportanceSignals>;
268
281
  getCurrentLevel(): ModuleQualityLevel<Payload>;
282
+ /** Record completed execution at the current level before governor.recordFrame. */
283
+ recordFrameTime(frameTimeMs: number): void;
284
+ canStepUp(context: PerformanceAdjustmentContext): boolean;
269
285
  }
270
286
  /**
271
287
  * Budget controls applied to a gpu-worker job type.
@@ -537,6 +553,9 @@ interface GpuPerformanceGovernorOptions {
537
553
  device: DeviceProfileInput | DeviceProfile;
538
554
  target?: FrameTargetNegotiationOptions;
539
555
  modules?: readonly PerformanceModuleAdapter[];
556
+ /** Recover configured initial visual levels as measured headroom permits.
557
+ * Defaults to false; authoritative modules still require explicit scaling permission. */
558
+ recoverInitialLevels?: boolean;
540
559
  adaptation?: GovernorAdaptationOptions;
541
560
  telemetry?: PerformanceTelemetryHooks;
542
561
  }
@@ -626,4 +645,4 @@ declare function createWorkerJobBudgetManifestGraph(manifest: WorkerJobBudgetMan
626
645
  */
627
646
  declare function createWorkerJobBudgetAdaptersFromManifest(manifest: WorkerJobBudgetManifest | readonly WorkerJobBudgetManifestJob[], options?: WorkerJobBudgetManifestAdapterOptions): readonly WorkerJobBudgetAdapter[];
628
647
 
629
- export { type DeviceClass, type DeviceProfile, type DeviceProfileInput, type FrameSample, type FrameTargetNegotiationOptions, type FrameTargetProfile, type GovernorAdaptationOptions, type GovernorDecision, type GovernorErrorRecord, type GovernorMetrics, type GovernorState, type GovernorWorkerGraphPriorityLaneSummary, type GovernorWorkerGraphSummary, type GpuPerformanceGovernorOptions, type GpuTier, type ModuleAuthority, type ModuleImportance, type ModuleQualityLevel, type MotionClass, type PerformanceAdjustmentContext, type PerformanceAdjustmentRecord, type PerformanceBudgetMetadata, type PerformanceDomain, type PerformanceGovernor, type PerformanceImportanceSignals, type PerformanceModuleAdapter, type PerformanceModuleSnapshot, type PerformanceQualityDimensions, type PerformanceTelemetryHooks, type PressureLevel, type QualityDimension, type QualityLadderAdapter, type QualityLadderAdapterOptions, type QualityLadderChangeEvent, type RepresentationBand, type RuntimeMode, type ThermalState, type WavefrontPathTracingBudgetAdapter, type WavefrontPathTracingBudgetAdapterOptions, type WavefrontPathTracingBudgetConfig, type WavefrontPathTracingBudgetControlSummary, type WavefrontPathTracingDenoiseMode, type WavefrontPathTracingVisibilityProbeMode, type WorkerJobBudgetAdapter, type WorkerJobBudgetAdapterOptions, type WorkerJobBudgetConfig, type WorkerJobBudgetManifest, type WorkerJobBudgetManifestAdapterOptions, type WorkerJobBudgetManifestGraph, type WorkerJobBudgetManifestGraphJob, type WorkerJobBudgetManifestJob, type WorkerJobBudgetManifestPerformance, type WorkerJobBudgetManifestPriorityLane, type WorkerJobBudgetSnapshot, type WorkerJobQueueClass, type WorkerSchedulerMode, createDeviceProfile, createGpuPerformanceGovernor, createPerformanceGovernor, createQualityLadderAdapter, createWavefrontPathTracingBudgetAdapter, createWorkerJobBudgetAdapter, createWorkerJobBudgetAdaptersFromManifest, createWorkerJobBudgetManifestGraph, defaultDomainOrder, motionClasses, negotiateFrameTarget, normalizePerformanceBudgetMetadata, normalizeWavefrontPathTracingBudgetConfig, rayTracingQualityDimensions, representationBands, wavefrontPathTracingBudgetControlKeys, wavefrontPathTracingDenoiseModes, wavefrontPathTracingVisibilityProbeModes };
648
+ export { type DeviceClass, type DeviceProfile, type DeviceProfileInput, type FrameSample, type FrameTargetNegotiationOptions, type FrameTargetProfile, type GovernorAdaptationOptions, type GovernorDecision, type GovernorErrorRecord, type GovernorMetrics, type GovernorState, type GovernorWorkerGraphPriorityLaneSummary, type GovernorWorkerGraphSummary, type GpuPerformanceGovernorOptions, type GpuTier, type ModuleAuthority, type ModuleImportance, type ModuleQualityLevel, type MotionClass, type PerformanceAdjustmentContext, type PerformanceAdjustmentRecord, type PerformanceBudgetMetadata, type PerformanceDomain, type PerformanceGovernor, type PerformanceImportanceSignals, type PerformanceModuleAdapter, type PerformanceModuleSnapshot, type PerformanceQualityDimensions, type PerformanceTelemetryHooks, type PressureLevel, type QualityDimension, type QualityLadderAdapter, type QualityLadderAdapterOptions, type QualityLadderChangeEvent, type QualityRecoveryBudgetOptions, type RepresentationBand, type RuntimeMode, type ThermalState, type WavefrontPathTracingBudgetAdapter, type WavefrontPathTracingBudgetAdapterOptions, type WavefrontPathTracingBudgetConfig, type WavefrontPathTracingBudgetControlSummary, type WavefrontPathTracingDenoiseMode, type WavefrontPathTracingVisibilityProbeMode, type WorkerJobBudgetAdapter, type WorkerJobBudgetAdapterOptions, type WorkerJobBudgetConfig, type WorkerJobBudgetManifest, type WorkerJobBudgetManifestAdapterOptions, type WorkerJobBudgetManifestGraph, type WorkerJobBudgetManifestGraphJob, type WorkerJobBudgetManifestJob, type WorkerJobBudgetManifestPerformance, type WorkerJobBudgetManifestPriorityLane, type WorkerJobBudgetSnapshot, type WorkerJobQueueClass, type WorkerSchedulerMode, createDeviceProfile, createGpuPerformanceGovernor, createPerformanceGovernor, createQualityLadderAdapter, createWavefrontPathTracingBudgetAdapter, createWorkerJobBudgetAdapter, createWorkerJobBudgetAdaptersFromManifest, createWorkerJobBudgetManifestGraph, defaultDomainOrder, motionClasses, negotiateFrameTarget, normalizePerformanceBudgetMetadata, normalizeWavefrontPathTracingBudgetConfig, rayTracingQualityDimensions, representationBands, wavefrontPathTracingBudgetControlKeys, wavefrontPathTracingDenoiseModes, wavefrontPathTracingVisibilityProbeModes };
package/dist/index.js CHANGED
@@ -166,6 +166,10 @@ function createDeviceProfile(input = {}) {
166
166
  });
167
167
  }
168
168
  function negotiateFrameTarget(options = {}) {
169
+ const frameBudgetRatio = readPositiveNumber("frameBudgetRatio", options.frameBudgetRatio);
170
+ if (frameBudgetRatio !== void 0 && frameBudgetRatio > 1) {
171
+ throw new Error("frameBudgetRatio must be at most one.");
172
+ }
169
173
  const mode = options.mode === void 0 ? "flat" : assertEnumValue("mode", options.mode, runtimeModes);
170
174
  const minimumFrameRate = Math.round(
171
175
  readPositiveNumber("minimumFrameRate", options.minimumFrameRate) ?? 60
@@ -222,8 +226,8 @@ function negotiateFrameTarget(options = {}) {
222
226
  rationale.push("Immersive modes prefer headset-native cadence when the session supports it.");
223
227
  }
224
228
  const targetFrameTimeMs = 1e3 / targetFrameRate;
225
- const downgradeMultiplier = mode === "flat" ? 1.05 : 1.03;
226
- const upgradeMultiplier = mode === "flat" ? 0.92 : 0.95;
229
+ const downgradeMultiplier = frameBudgetRatio ?? (mode === "flat" ? 1.05 : 1.03);
230
+ const upgradeMultiplier = (frameBudgetRatio ?? 1) * (mode === "flat" ? 0.92 : 0.95);
227
231
  return Object.freeze({
228
232
  mode,
229
233
  minimumFrameRate,
@@ -351,6 +355,42 @@ function normalizePerformanceBudgetMetadata(name, value) {
351
355
  });
352
356
  }
353
357
 
358
+ // src/quality-recovery.ts
359
+ function createMeasuredQualityRecovery(levelCount, options) {
360
+ const enabled = options !== void 0;
361
+ const headroom = enabled ? readPositiveNumber("recoveryBudget.headroomRatio", options?.headroomRatio) : 1;
362
+ if (headroom === void 0 || headroom > 1) {
363
+ throw new Error("recoveryBudget.headroomRatio must be in (0, 1].");
364
+ }
365
+ const initialRatios = options?.initialCostRatios;
366
+ if (initialRatios !== void 0 && (!Array.isArray(initialRatios) || initialRatios.length !== levelCount - 1 || Array.from(initialRatios).some((value) => typeof value !== "number" || !Number.isFinite(value) || value <= 0))) {
367
+ throw new Error("recoveryBudget.initialCostRatios must contain one finite positive ratio per upward step.");
368
+ }
369
+ const lastTimes = new Array(levelCount);
370
+ const recoveryRatios = initialRatios ? [...initialRatios] : new Array(levelCount);
371
+ let pending;
372
+ return {
373
+ record(index, frameTimeMs) {
374
+ const value = readNonNegativeNumber("frameTimeMs", frameTimeMs);
375
+ if (value === void 0) throw new Error("frameTimeMs is required.");
376
+ if (!enabled || value === 0) return;
377
+ lastTimes[index] = value;
378
+ if (pending?.index === index) {
379
+ recoveryRatios[index] = pending.upperTime / value;
380
+ pending = void 0;
381
+ }
382
+ },
383
+ reduced(from, to) {
384
+ const upperTime = lastTimes[from];
385
+ pending = enabled && upperTime !== void 0 ? { index: to, upperTime } : void 0;
386
+ },
387
+ canRecover(index, context) {
388
+ const ratio = recoveryRatios[index];
389
+ return !enabled || ratio === void 0 || context.metrics.latestFrameTimeMs * ratio <= context.target.targetFrameTimeMs * headroom;
390
+ }
391
+ };
392
+ }
393
+
354
394
  // src/ladder.ts
355
395
  function resolveLevelIndex(levels, initialLevel) {
356
396
  if (typeof initialLevel === "number") {
@@ -430,6 +470,7 @@ function createQualityLadderAdapter(options) {
430
470
  const levels = [...options.levels];
431
471
  const metadata = normalizePerformanceBudgetMetadata("budget metadata", options);
432
472
  let currentLevelIndex = resolveLevelIndex(levels, options.initialLevel);
473
+ const recovery = createMeasuredQualityRecovery(levels.length, options.recoveryBudget);
433
474
  const emitChange = (context, adjustment, previousLevelIndex) => {
434
475
  if (typeof options.onLevelChange !== "function") {
435
476
  return;
@@ -450,7 +491,9 @@ function createQualityLadderAdapter(options) {
450
491
  return null;
451
492
  }
452
493
  const previousLevelIndex = currentLevelIndex;
494
+ if (direction === "up" && !recovery.canRecover(currentLevelIndex, context)) return null;
453
495
  currentLevelIndex = nextLevelIndex;
496
+ if (direction === "down") recovery.reduced(previousLevelIndex, currentLevelIndex);
454
497
  const adjustment = buildAdjustment(
455
498
  direction,
456
499
  id,
@@ -476,6 +519,12 @@ function createQualityLadderAdapter(options) {
476
519
  getCurrentLevel() {
477
520
  return levels[currentLevelIndex];
478
521
  },
522
+ recordFrameTime(frameTimeMs) {
523
+ recovery.record(currentLevelIndex, frameTimeMs);
524
+ },
525
+ canStepUp(context) {
526
+ return recovery.canRecover(currentLevelIndex, context);
527
+ },
479
528
  getSnapshot() {
480
529
  return buildSnapshot(
481
530
  id,
@@ -962,6 +1011,9 @@ function createGpuPerformanceGovernor(options) {
962
1011
  throw new Error("createGpuPerformanceGovernor requires an options object.");
963
1012
  }
964
1013
  validateTelemetryHooks(options.telemetry);
1014
+ if (options.recoverInitialLevels !== void 0 && typeof options.recoverInitialLevels !== "boolean") {
1015
+ throw new Error("recoverInitialLevels must be a boolean.");
1016
+ }
965
1017
  const device = createDeviceProfile(options.device);
966
1018
  if (!device.supportsWebGpu) {
967
1019
  throw new Error(
@@ -975,7 +1027,8 @@ function createGpuPerformanceGovernor(options) {
975
1027
  supportedFrameRates: options.target?.supportedFrameRates ?? device.supportedFrameRates,
976
1028
  preferredFrameRates: options.target?.preferredFrameRates,
977
1029
  minimumFrameRate: options.target?.minimumFrameRate,
978
- maximumFrameRate: options.target?.maximumFrameRate
1030
+ maximumFrameRate: options.target?.maximumFrameRate,
1031
+ frameBudgetRatio: options.target?.frameBudgetRatio
979
1032
  });
980
1033
  const modules = /* @__PURE__ */ new Map();
981
1034
  if ((options.modules?.length ?? 0) > MAX_MODULE_COUNT) {
@@ -997,6 +1050,7 @@ function createGpuPerformanceGovernor(options) {
997
1050
  let lastDownCycle = Number.NEGATIVE_INFINITY;
998
1051
  let lastUpCycle = Number.NEGATIVE_INFINITY;
999
1052
  let recoveryStack = [];
1053
+ const initialRecovery = new Set(options.recoverInitialLevels ? modules.keys() : []);
1000
1054
  let recentErrors = [];
1001
1055
  let recentFrameIds = /* @__PURE__ */ new Set();
1002
1056
  let recentFrameIdQueue = [];
@@ -1165,25 +1219,41 @@ function createGpuPerformanceGovernor(options) {
1165
1219
  };
1166
1220
  const attemptRecovery = (metrics, workerGraph, decisionErrors, correlationId) => {
1167
1221
  const context = createContext("recover", "recovering", metrics, workerGraph);
1168
- while (recoveryStack.length > 0) {
1169
- const moduleId = recoveryStack[recoveryStack.length - 1];
1222
+ const pending = recoveryStack.map((moduleId, index) => ({ moduleId, index })).reverse();
1223
+ const reduced = new Set(recoveryStack);
1224
+ for (const moduleId of initialRecovery) {
1225
+ if (!reduced.has(moduleId)) pending.push({ moduleId, index: -1 });
1226
+ }
1227
+ for (const { moduleId, index } of pending) {
1228
+ const remove = () => {
1229
+ if (index >= 0) recoveryStack.splice(index, 1);
1230
+ else initialRecovery.delete(moduleId);
1231
+ };
1170
1232
  if (!moduleId) {
1171
- recoveryStack.pop();
1233
+ remove();
1172
1234
  continue;
1173
1235
  }
1174
1236
  const module = modules.get(moduleId);
1175
1237
  if (!module) {
1176
- recoveryStack.pop();
1238
+ remove();
1177
1239
  continue;
1178
1240
  }
1179
1241
  try {
1242
+ if (index < 0) {
1243
+ const snapshot = module.getSnapshot();
1244
+ if (snapshot.isAtMaximum || snapshot.authority === "authoritative" && !adaptation.allowAuthoritativeScaling) {
1245
+ remove();
1246
+ continue;
1247
+ }
1248
+ }
1249
+ if (module.canStepUp?.(context) === false) continue;
1180
1250
  const adjustment = module.stepUp(context);
1181
- recoveryStack.pop();
1251
+ if (index >= 0 || !adjustment) remove();
1182
1252
  if (adjustment) {
1183
1253
  return [adjustment];
1184
1254
  }
1185
1255
  } catch {
1186
- recoveryStack.pop();
1256
+ remove();
1187
1257
  appendError(
1188
1258
  createErrorRecord({
1189
1259
  cycle,
@@ -1295,9 +1365,11 @@ function createGpuPerformanceGovernor(options) {
1295
1365
  throw new Error(`Module "${module.id}" is already registered.`);
1296
1366
  }
1297
1367
  modules.set(module.id, module);
1368
+ if (options.recoverInitialLevels) initialRecovery.add(module.id);
1298
1369
  return () => {
1299
1370
  modules.delete(module.id);
1300
1371
  recoveryStack = recoveryStack.filter((id) => id !== module.id);
1372
+ initialRecovery.delete(module.id);
1301
1373
  };
1302
1374
  },
1303
1375
  getTarget() {
@@ -1326,6 +1398,8 @@ function createGpuPerformanceGovernor(options) {
1326
1398
  lastDownCycle = Number.NEGATIVE_INFINITY;
1327
1399
  lastUpCycle = Number.NEGATIVE_INFINITY;
1328
1400
  recoveryStack = [];
1401
+ initialRecovery.clear();
1402
+ if (options.recoverInitialLevels) for (const id of modules.keys()) initialRecovery.add(id);
1329
1403
  recentErrors = [];
1330
1404
  recentFrameIds = /* @__PURE__ */ new Set();
1331
1405
  recentFrameIdQueue = [];