@simulatte/doppler 0.1.5 → 0.1.7

package/src/debug/config.js

@@ -50,6 +50,108 @@ const originalConsoleInfo = console.info;
 const originalConsoleWarn = console.warn;
 let warnedBenchmarkMode = false;
 
+function requirePlainObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must be an object when provided.`);
+  }
+  return value;
+}
+
+function requireNonNegativeIntegerArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array of non-negative integers when provided.`);
+  }
+  return value.map((entry, index) => {
+    const parsed = Number(entry);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+      throw new Error(`${label}[${index}] must be a non-negative integer.`);
+    }
+    return parsed;
+  });
+}
+
+function requireNonNegativeInteger(value, label) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${label} must be a non-negative integer when provided.`);
+  }
+  return parsed;
+}
+
+function requireBoolean(value, label) {
+  if (typeof value !== 'boolean') {
+    throw new Error(`${label} must be a boolean when provided.`);
+  }
+  return value;
+}
+
+function normalizeLogLevel(level) {
+  if (typeof level !== 'string' || !level.trim()) {
+    throw new Error('setLogLevel(level) requires a non-empty log level string.');
+  }
+  return level.trim().toLowerCase();
+}
+
+function normalizeTraceCategories(categories) {
+  if (typeof categories === 'string') {
+    const values = categories
+      .split(',')
+      .map((value) => value.trim())
+      .filter(Boolean);
+    if (values.length === 0) {
+      throw new Error('setTrace(categories) requires at least one trace category.');
+    }
+    return values;
+  }
+  if (Array.isArray(categories) && categories.length > 0) {
+    return categories.map((value, index) => {
+      if (typeof value !== 'string' || !value.trim()) {
+        throw new Error(`setTrace(categories)[${index}] must be a non-empty string.`);
+      }
+      return value.trim();
+    });
+  }
+  throw new Error(
+    'setTrace(categories) requires false, a comma-delimited string, or a non-empty string array.'
+  );
+}
+
+function validateTraceCategoryToken(token) {
+  if (token === 'all') {
+    return;
+  }
+  const value = token.startsWith('-') ? token.slice(1) : token;
+  if (!TRACE_CATEGORIES.includes(value)) {
+    throw new Error(
+      `Unknown trace category "${token}". Allowed categories: all, ${TRACE_CATEGORIES.join(', ')}.`
+    );
+  }
+}
+
+function normalizeTraceOptions(options) {
+  if (options == null) {
+    return {};
+  }
+  const normalized = requirePlainObject(options, 'setTrace(options)');
+  return {
+    ...(normalized.layers === undefined ? {} : {
+      layers: requireNonNegativeIntegerArray(normalized.layers, 'setTrace(options).layers'),
+    }),
+    ...(normalized.maxDecodeSteps === undefined ? {} : {
+      maxDecodeSteps: requireNonNegativeInteger(
+        normalized.maxDecodeSteps,
+        'setTrace(options).maxDecodeSteps'
+      ),
+    }),
+    ...(normalized.breakOnAnomaly === undefined ? {} : {
+      breakOnAnomaly: requireBoolean(
+        normalized.breakOnAnomaly,
+        'setTrace(options).breakOnAnomaly'
+      ),
+    }),
+  };
+}
+
 export function setLogLevel(level) {
   const levelMap = {
     debug: LOG_LEVELS.DEBUG,
@@ -59,8 +161,14 @@ export function setLogLevel(level) {
     error: LOG_LEVELS.ERROR,
     silent: LOG_LEVELS.SILENT,
   };
-  currentLogLevel = levelMap[level.toLowerCase()] ?? LOG_LEVELS.INFO;
-  console.log(`[Doppler] Log level set to: ${level.toUpperCase()}`);
+  const normalizedLevel = normalizeLogLevel(level);
+  if (!Object.prototype.hasOwnProperty.call(levelMap, normalizedLevel)) {
+    throw new Error(
+      `Unknown log level "${level}". Allowed levels: ${Object.keys(levelMap).join(', ')}.`
+    );
+  }
+  currentLogLevel = levelMap[normalizedLevel];
+  console.log(`[Doppler] Log level set to: ${normalizedLevel.toUpperCase()}`);
 }
 
 export function getLogLevel() {
@@ -77,9 +185,11 @@ export function setTrace(categories, options) {
     return;
   }
 
-  const catArray = typeof categories === 'string'
-    ? categories.split(',').map(s => s.trim())
-    : categories;
+  const catArray = normalizeTraceCategories(categories);
+  const traceOptions = normalizeTraceOptions(options);
+  for (const cat of catArray) {
+    validateTraceCategoryToken(cat);
+  }
 
   enabledTraceCategories.clear();
 
@@ -101,14 +211,14 @@ export function setTrace(categories, options) {
     }
   }
 
-  if (options?.layers) {
-    traceLayerFilter = options.layers;
+  if (traceOptions.layers !== undefined) {
+    traceLayerFilter = traceOptions.layers;
   }
-  if (options?.maxDecodeSteps !== undefined) {
-    traceMaxDecodeSteps = options.maxDecodeSteps;
+  if (traceOptions.maxDecodeSteps !== undefined) {
+    traceMaxDecodeSteps = traceOptions.maxDecodeSteps;
   }
-  if (options?.breakOnAnomaly !== undefined) {
-    traceBreakOnAnomaly = options.breakOnAnomaly;
+  if (traceOptions.breakOnAnomaly !== undefined) {
+    traceBreakOnAnomaly = traceOptions.breakOnAnomaly;
   }
 
   const enabled = [...enabledTraceCategories].join(',') || 'none';
@@ -184,11 +294,13 @@ export function setSilentMode(enabled) {
     console.log = noop;
     console.debug = noop;
     console.info = noop;
+    console.warn = noop;
     originalConsoleLog('[Doppler] Silent mode enabled - logging silenced');
   } else {
     console.log = originalConsoleLog;
     console.debug = originalConsoleDebug;
     console.info = originalConsoleInfo;
+    console.warn = originalConsoleWarn;
     console.log('[Doppler] Silent mode disabled - logging restored');
   }
 }

package/src/debug/signals.js

@@ -24,7 +24,13 @@ export function signalResult(data) {
 
 
 export function signalError(error, details) {
-  console.log(`${SIGNALS.ERROR} ${JSON.stringify({ error, ...details })}`);
+  if (details != null && (typeof details !== 'object' || Array.isArray(details))) {
+    throw new Error('signalError details must be an object when provided.');
+  }
+  if (details && Object.hasOwn(details, 'error')) {
+    throw new Error('signalError details.error is reserved. Pass the primary error as the first argument.');
+  }
+  console.log(`${SIGNALS.ERROR} ${JSON.stringify({ error, ...(details ?? {}) })}`);
 }
 
 

package/src/debug/tensor.d.ts

@@ -63,6 +63,8 @@ export interface TensorInspectOptions {
 }
 
 export interface TensorSnapshot {
+  ok: boolean;
+  error: string | null;
   shape: number[];
   dtype: string;
   stats: {

package/src/debug/tensor.js

@@ -202,7 +202,13 @@ export const tensor = {
 
 export async function snapshotTensor(buffer, shape, dtype = 'f32') {
   try {
-    if (!gpuDevice) {
+    if (
+      !gpuDevice
+      || typeof gpuDevice.createBuffer !== 'function'
+      || typeof gpuDevice.createCommandEncoder !== 'function'
+      || !gpuDevice.queue
+      || typeof gpuDevice.queue.submit !== 'function'
+    ) {
       throw new Error('GPU device not initialized');
     }
     const elementSize = dtype === 'f16' ? 2 : 4;
@@ -224,8 +230,11 @@ export async function snapshotTensor(buffer, shape, dtype = 'f32') {
     staging.destroy();
     const arr = new Float32Array(data);
     return snapshotFromArray(arr, shape ?? [arr.length], dtype);
-  } catch {
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
     return {
+      ok: false,
+      error: message,
       shape: shape ?? [0],
       dtype,
       stats: { min: 0, max: 0, maxAbs: 0, mean: 0, std: 0 },
@@ -241,6 +250,8 @@ export function snapshotFromArray(arr, shape, dtype = 'f32') {
   const stats = computeArrayStats(arr, Math.min(arr.length, numElements));
 
   return {
+    ok: true,
+    error: null,
     shape,
     dtype,
     stats: {

package/src/distribution/p2p-control-plane.js

@@ -38,10 +38,17 @@ function asOptionalTimestamp(value, label) {
   return Math.floor(parsed);
 }
 
-function asNonNegativeInteger(value, fallback) {
+function asOptionalNonNegativeInteger(value, label) {
+  if (value === undefined || value === null) {
+    return null;
+  }
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed < 0) {
-    return fallback;
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label} must be a non-negative integer when provided.`,
+      { label }
+    );
   }
   return parsed;
 }
@@ -104,12 +111,11 @@ export function normalizeControlPlaneSessionUpdate(value, label = 'p2p control-p
 
 export function normalizeP2PPolicyDecision(value, label = 'p2p control-plane policy decision') {
   if (value === undefined || value === null) {
-    return {
-      allow: true,
-      reason: null,
-      sessionUpdate: null,
-      metadata: null,
-    };
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label} must return an explicit boolean or object decision.`,
+      { label }
+    );
   }
 
   if (typeof value === 'boolean') {
@@ -129,9 +135,40 @@ export function normalizeP2PPolicyDecision(value, label = 'p2p control-plane pol
     );
   }
 
-  const allow = value.allow === false || value.deny === true
-    ? false
-    : true;
+  const hasAllow = Object.prototype.hasOwnProperty.call(value, 'allow');
+  const hasDeny = Object.prototype.hasOwnProperty.call(value, 'deny');
+  if (!hasAllow && !hasDeny) {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label} must include allow or deny.`,
+      { label }
+    );
+  }
+  if (hasAllow && typeof value.allow !== 'boolean') {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label}.allow must be a boolean when provided.`,
+      { label }
+    );
+  }
+  if (hasDeny && typeof value.deny !== 'boolean') {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label}.deny must be a boolean when provided.`,
+      { label }
+    );
+  }
+  if (hasAllow && hasDeny && value.allow === value.deny) {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `${label} has conflicting allow/deny values.`,
+      { label }
+    );
+  }
+
+  const allow = hasAllow
+    ? value.allow
+    : value.deny !== true;
   const reason = asOptionalString(value.reason, `${label}.reason`);
   const sessionUpdate = normalizeControlPlaneSessionUpdate(
     {
@@ -180,7 +217,10 @@ export function normalizeP2PControlPlaneConfig(config = {}) {
     contractVersion: assertSupportedP2PControlPlaneContract(
       raw.contractVersion ?? P2P_CONTROL_PLANE_CONTRACT_VERSION
     ),
-    tokenRefreshSkewMs: asNonNegativeInteger(raw.tokenRefreshSkewMs, DEFAULT_TOKEN_REFRESH_SKEW_MS),
+    tokenRefreshSkewMs: asOptionalNonNegativeInteger(
+      raw.tokenRefreshSkewMs,
+      'p2p.controlPlane.tokenRefreshSkewMs'
+    ) ?? DEFAULT_TOKEN_REFRESH_SKEW_MS,
     tokenProvider,
     policyEvaluator,
   };

package/src/distribution/p2p-observability.js

@@ -12,6 +12,14 @@ function asFiniteNumber(value, fallback = 0) {
   return Number.isFinite(parsed) ? parsed : fallback;
 }
 
+function assertFiniteNumber(value, label) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`P2P observability ${label} must be a finite number.`);
+  }
+  return parsed;
+}
+
 function asNonNegativeInteger(value, fallback = 0) {
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed < 0) {
@@ -69,15 +77,43 @@ function percentile(values, ratio) {
 }
 
 function resolveSLOTargets(options = {}) {
-  const targets = options.targets && typeof options.targets === 'object'
-    ? options.targets
-    : {};
+  const hasExplicitTargets = Object.hasOwn(options, 'targets');
+  if (hasExplicitTargets && (options.targets == null || typeof options.targets !== 'object' || Array.isArray(options.targets))) {
+    throw new Error('P2P observability targets must be an object when provided.');
+  }
+  const targets = hasExplicitTargets ? options.targets : {};
+
+  const minAvailability = Object.hasOwn(targets, 'minAvailability')
+    ? assertFiniteNumber(targets.minAvailability, 'targets.minAvailability')
+    : DEFAULT_SLO_TARGETS.minAvailability;
+  const minP2PHitRate = Object.hasOwn(targets, 'minP2PHitRate')
+    ? assertFiniteNumber(targets.minP2PHitRate, 'targets.minP2PHitRate')
+    : DEFAULT_SLO_TARGETS.minP2PHitRate;
+  const maxHttpFallbackRate = Object.hasOwn(targets, 'maxHttpFallbackRate')
+    ? assertFiniteNumber(targets.maxHttpFallbackRate, 'targets.maxHttpFallbackRate')
+    : DEFAULT_SLO_TARGETS.maxHttpFallbackRate;
+  const maxP95LatencyMs = Object.hasOwn(targets, 'maxP95LatencyMs')
+    ? assertFiniteNumber(targets.maxP95LatencyMs, 'targets.maxP95LatencyMs')
+    : DEFAULT_SLO_TARGETS.maxP95LatencyMs;
+
+  if (minAvailability < 0 || minAvailability > 1) {
+    throw new Error('P2P observability targets.minAvailability must be between 0 and 1.');
+  }
+  if (minP2PHitRate < 0 || minP2PHitRate > 1) {
+    throw new Error('P2P observability targets.minP2PHitRate must be between 0 and 1.');
+  }
+  if (maxHttpFallbackRate < 0 || maxHttpFallbackRate > 1) {
+    throw new Error('P2P observability targets.maxHttpFallbackRate must be between 0 and 1.');
+  }
+  if (maxP95LatencyMs < 0) {
+    throw new Error('P2P observability targets.maxP95LatencyMs must be >= 0.');
+  }
 
   return {
-    minAvailability: asFiniteNumber(targets.minAvailability, DEFAULT_SLO_TARGETS.minAvailability),
-    minP2PHitRate: asFiniteNumber(targets.minP2PHitRate, DEFAULT_SLO_TARGETS.minP2PHitRate),
-    maxHttpFallbackRate: asFiniteNumber(targets.maxHttpFallbackRate, DEFAULT_SLO_TARGETS.maxHttpFallbackRate),
-    maxP95LatencyMs: asFiniteNumber(targets.maxP95LatencyMs, DEFAULT_SLO_TARGETS.maxP95LatencyMs),
+    minAvailability,
+    minP2PHitRate,
+    maxHttpFallbackRate,
+    maxP95LatencyMs,
   };
 }
 

package/src/distribution/p2p-webrtc-browser.js

@@ -200,6 +200,16 @@ function assertOpenDataChannel(channel, peerId) {
 }
 
 function toRequestMessage(requestId, context) {
+  if (context?.contractVersion !== P2P_WEBRTC_DATA_PLANE_CONTRACT_VERSION) {
+    throw createP2PTransportError(
+      P2P_TRANSPORT_ERROR_CODES.payloadInvalid,
+      `Unexpected WebRTC data-plane contractVersion "${context?.contractVersion}".`,
+      {
+        expectedContractVersion: P2P_WEBRTC_DATA_PLANE_CONTRACT_VERSION,
+        actualContractVersion: context?.contractVersion ?? null,
+      }
+    );
+  }
   return {
     schemaVersion: P2P_WEBRTC_MESSAGE_SCHEMA_VERSION,
     contractVersion: P2P_WEBRTC_DATA_PLANE_CONTRACT_VERSION,
@@ -377,6 +387,16 @@ export function createBrowserWebRTCDataPlaneTransport(config = {}) {
   const maxPayloadBytes = Math.max(1, asNonNegativeInteger(config.maxPayloadBytes, DEFAULT_MAX_PAYLOAD_BYTES));
 
   return async function webRtcDataPlaneTransport(context) {
+    if (context?.contractVersion !== P2P_WEBRTC_DATA_PLANE_CONTRACT_VERSION) {
+      throw createP2PTransportError(
+        P2P_TRANSPORT_ERROR_CODES.contractUnsupported,
+        `Unsupported p2p.webrtc contractVersion "${context?.contractVersion}". Supported: ${P2P_WEBRTC_DATA_PLANE_CONTRACT_VERSION}.`,
+        {
+          contractVersion: context?.contractVersion ?? null,
+        }
+      );
+    }
+
     const selection = normalizePeerSelectionResult(
       selectPeer ? await selectPeer(context) : { peerId: staticPeerId }
     );

package/src/distribution/shard-delivery.js

@@ -55,22 +55,30 @@ const inFlightDeliveries = new Map();
 const p2pTransportPolicyState = new WeakMap();
 
 function normalizeDistributionSourceOrder(rawSources = []) {
-  if (!Array.isArray(rawSources)) {
+  if (rawSources === undefined || rawSources === null) {
     return [...DISTRIBUTION_SOURCES];
   }
+  if (!Array.isArray(rawSources)) {
+    throw new Error('distribution.sourceOrder must be an array when provided.');
+  }
 
   const normalized = [];
   const seen = new Set();
 
   for (const value of rawSources) {
     const source = String(value || '').trim().toLowerCase();
-    if (!DISTRIBUTION_SOURCES.includes(source)) continue;
+    if (!DISTRIBUTION_SOURCES.includes(source)) {
+      throw new Error(`distribution.sourceOrder contains unsupported source "${source || value}".`);
+    }
     if (seen.has(source)) continue;
     seen.add(source);
     normalized.push(source);
   }
 
-  return normalized.length > 0 ? normalized : [...DISTRIBUTION_SOURCES];
+  if (normalized.length === 0) {
+    throw new Error('distribution.sourceOrder must include at least one supported source.');
+  }
+  return normalized;
 }
 
 function normalizeInteger(value, fallback, allowZero = false) {
@@ -81,6 +89,23 @@ function normalizeInteger(value, fallback, allowZero = false) {
     : fallback;
 }
 
+function normalizeRequiredInteger(value, label, { allowZero = false, fallback = null } = {}) {
+  if (value === undefined || value === null) {
+    if (fallback !== null) {
+      return fallback;
+    }
+    throw new Error(`${label} is required.`);
+  }
+  const parsed = Number(value);
+  const min = allowZero ? 0 : 1;
+  if (!Number.isInteger(parsed) || parsed < min) {
+    throw new Error(
+      `${label} must be a ${allowZero ? 'non-negative' : 'positive'} integer when provided.`
+    );
+  }
+  return parsed;
+}
+
 function normalizeContentEncodings(value) {
   if (!value) return [];
   return value
@@ -95,13 +120,17 @@ function normalizeManifestVersionSet(value) {
   return normalized || null;
 }
 
-function normalizeSamplingRate(value, fallback = 1) {
+function normalizeSamplingRate(value, fallback = 1, label = 'distribution.sourceDecision.trace.samplingRate') {
+  if (value === undefined || value === null) {
+    return fallback;
+  }
   const parsed = Number(value);
   if (!Number.isFinite(parsed)) {
-    return fallback;
+    throw new Error(`${label} must be a finite number between 0 and 1 when provided.`);
+  }
+  if (parsed < 0 || parsed > 1) {
+    throw new Error(`${label} must be between 0 and 1 when provided.`);
   }
-  if (parsed <= 0) return 0;
-  if (parsed >= 1) return 1;
   return parsed;
 }
 
@@ -479,19 +508,28 @@ function normalizeP2PConfig(config = {}) {
 
   return {
     enabled,
-    timeoutMs: normalizeInteger(rawTimeoutMs, DEFAULT_P2P_TIMEOUT_MS),
-    maxRetries: normalizeInteger(rawMaxRetries, DEFAULT_P2P_MAX_RETRIES, true),
-    retryDelayMs: normalizeInteger(rawRetryDelayMs, DEFAULT_P2P_RETRY_DELAY_MS, true),
+    timeoutMs: normalizeRequiredInteger(
+      rawTimeoutMs,
+      'distribution.p2p.timeoutMs',
+      { fallback: DEFAULT_P2P_TIMEOUT_MS }
+    ),
+    maxRetries: normalizeRequiredInteger(
+      rawMaxRetries,
+      'distribution.p2p.maxRetries',
+      { allowZero: true, fallback: DEFAULT_P2P_MAX_RETRIES }
+    ),
+    retryDelayMs: normalizeRequiredInteger(
+      rawRetryDelayMs,
+      'distribution.p2p.retryDelayMs',
+      { allowZero: true, fallback: DEFAULT_P2P_RETRY_DELAY_MS }
+    ),
     transport,
     contractVersion,
     controlPlane: normalizeP2PControlPlaneConfig({
       ...DEFAULT_DISTRIBUTION_CONFIG.p2p.controlPlane,
       ...rawControlPlane,
-      tokenRefreshSkewMs: normalizeInteger(
-        rawControlPlane.tokenRefreshSkewMs,
-        DEFAULT_P2P_CONTROL_PLANE_TOKEN_REFRESH_SKEW_MS,
-        true
-      ),
+      tokenRefreshSkewMs: rawControlPlane.tokenRefreshSkewMs
+        ?? DEFAULT_P2P_CONTROL_PLANE_TOKEN_REFRESH_SKEW_MS,
     }),
     security: {
       requireSessionToken: rawSecurity.requireSessionToken === true,
@@ -499,19 +537,20 @@ function normalizeP2PConfig(config = {}) {
       tokenExpiresAtMs: normalizeOptionalTimestamp(rawSecurity.tokenExpiresAtMs),
     },
     abuse: {
-      rateLimitPerMinute: normalizeInteger(
+      rateLimitPerMinute: normalizeRequiredInteger(
         rawAbuse.rateLimitPerMinute,
-        DEFAULT_P2P_RATE_LIMIT_PER_MINUTE,
-        true
+        'distribution.p2p.abuse.rateLimitPerMinute',
+        { allowZero: true, fallback: DEFAULT_P2P_RATE_LIMIT_PER_MINUTE }
       ),
-      maxConsecutiveFailures: normalizeInteger(
+      maxConsecutiveFailures: normalizeRequiredInteger(
         rawAbuse.maxConsecutiveFailures,
-        DEFAULT_P2P_MAX_CONSECUTIVE_FAILURES
+        'distribution.p2p.abuse.maxConsecutiveFailures',
+        { fallback: DEFAULT_P2P_MAX_CONSECUTIVE_FAILURES }
       ),
-      quarantineMs: normalizeInteger(
+      quarantineMs: normalizeRequiredInteger(
         rawAbuse.quarantineMs,
-        DEFAULT_P2P_QUARANTINE_MS,
-        true
+        'distribution.p2p.abuse.quarantineMs',
+        { allowZero: true, fallback: DEFAULT_P2P_QUARANTINE_MS }
       ),
     },
   };
@@ -1293,9 +1332,21 @@ async function downloadShardFromHttp(baseUrl, shardInfo, shardIndex, options = {
   const startTime = performance.now();
   const url = buildShardUrl(baseUrl, shardInfo);
   let lastError;
-  const maxRetries = normalizeInteger(options.maxRetries, 3, true);
-  const initialRetryDelayMs = normalizeInteger(options.initialRetryDelayMs, 1000);
-  const maxRetryDelayMs = normalizeInteger(options.maxRetryDelayMs, 30000);
+  const maxRetries = normalizeRequiredInteger(
+    options.maxRetries,
+    'download.maxRetries',
+    { allowZero: true, fallback: 3 }
+  );
+  const initialRetryDelayMs = normalizeRequiredInteger(
+    options.initialRetryDelayMs,
+    'download.initialRetryDelayMs',
+    { allowZero: true, fallback: 1000 }
+  );
+  const maxRetryDelayMs = normalizeRequiredInteger(
+    options.maxRetryDelayMs,
+    'download.maxRetryDelayMs',
+    { allowZero: true, fallback: 30000 }
+  );
   const progressTotalBytes = Number.isFinite(options.expectedSize)
     ? Math.floor(options.expectedSize)
     : (Number.isFinite(shardInfo?.size) ? Math.floor(shardInfo.size) : 0);