Normalize ConnectionThresholds field names

Rename downlink2gUpperBound/downlink3gUpperBound/downlink4gUpperBound
to lowUpperBound/midUpperBound/highUpperBound, matching the pattern
used by CpuThresholds and MemoryThresholds.

Author: SimplyLiz

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Breaking Changes
 
+- **Normalize `ConnectionThresholds` field names** — Renamed `downlink2gUpperBound` → `lowUpperBound`, `downlink3gUpperBound` → `midUpperBound`, `downlink4gUpperBound` → `highUpperBound` to match the `CpuThresholds`/`MemoryThresholds` naming pattern. Update any custom `connection` threshold objects in your `thresholds` config
 - **Rename `ConnectionTier` value `'fast'` → `'high'`** — Aligns connection tier vocabulary with CPU, memory, and GPU tiers which all use `'low' | 'mid' | 'high'`. Update any code comparing `tiers.connection === 'fast'` to use `'high'` instead
 - **`classify()` and `deriveHints()` now accept `StoredSignals` instead of `RawSignals`** — These functions never used `userAgent` or `viewport` (which are stripped before storage). The narrower type makes the API honest. Existing call sites are unaffected — `RawSignals` is structurally assignable to `StoredSignals`
 - **`profile:store` event now carries `StoredSignals` instead of `RawSignals`** — The event previously emitted the raw probe payload (including `userAgent`/`viewport`), not what was actually stored. The `signals` field now matches the persisted data. `bot:reject` still carries `RawSignals` (it fires before stripping)

docs/api/types.md

@@ -54,7 +54,7 @@ Validates custom tier thresholds after merging with defaults. Throws a descripti
 **Validation rules:**
 
 - **CPU/Memory**: `lowUpperBound` must be less than `midUpperBound`
-- **Connection**: `downlink2gUpperBound` < `downlink3gUpperBound` < `downlink4gUpperBound`
+- **Connection**: `lowUpperBound` < `midUpperBound` < `highUpperBound`
 - **GPU**: `softwarePattern` and `highEndPattern` must be `RegExp` instances
 - All numeric values must be positive (> 0)
 
@@ -156,11 +156,11 @@ Custom thresholds for tier classification. All fields are optional — unset fie
 
 ### ConnectionThresholds
 
-| Field                  | Type     | Default | Description                    |
-| ---------------------- | -------- | ------- | ------------------------------ |
-| `downlink2gUpperBound` | `number` | `0.5`   | Mbps at or below → `'2g'` tier |
-| `downlink3gUpperBound` | `number` | `2`     | Mbps at or below → `'3g'` tier |
-| `downlink4gUpperBound` | `number` | `5`     | Mbps at or below → `'4g'` tier |
+| Field            | Type     | Default | Description                    |
+| ---------------- | -------- | ------- | ------------------------------ |
+| `lowUpperBound`  | `number` | `0.5`   | Mbps at or below → `'2g'` tier |
+| `midUpperBound`  | `number` | `2`     | Mbps at or below → `'3g'` tier |
+| `highUpperBound` | `number` | `5`     | Mbps at or below → `'4g'` tier |
 
 ### GpuThresholds
 
@@ -177,7 +177,7 @@ import { classify } from '@device-router/types';
 const tiers = classify(signals, {
   cpu: { lowUpperBound: 4, midUpperBound: 8 },
   memory: { midUpperBound: 8 },
-  connection: { downlink4gUpperBound: 10 },
+  connection: { highUpperBound: 10 },
   gpu: { highEndPattern: /\bRTX\b|\bGTX\b/i },
 });
 ```

docs/getting-started.md

@@ -252,7 +252,7 @@ const { middleware, probeEndpoint } = createDeviceRouter({
   thresholds: {
     cpu: { lowUpperBound: 4, midUpperBound: 8 },
     memory: { midUpperBound: 8 },
-    connection: { downlink4gUpperBound: 10 },
+    connection: { highUpperBound: 10 },
   },
 });
 ```

packages/types/README.md

@@ -64,7 +64,7 @@ import { classify } from '@device-router/types';
 const tiers = classify(signals, {
   cpu: { lowUpperBound: 4, midUpperBound: 8 },
   memory: { midUpperBound: 8 },
-  connection: { downlink4gUpperBound: 10 },
+  connection: { highUpperBound: 10 },
   gpu: { highEndPattern: /\bRTX\b|\bGTX\b/i },
 });
 ```

packages/types/src/__tests__/classify.test.ts

@@ -93,18 +93,18 @@ describe('classifyConnection', () => {
 
   it('uses custom downlink thresholds', () => {
     // With wider 2g band (up to 1 Mbps)
-    expect(classifyConnection(undefined, 0.8, { downlink2gUpperBound: 1 })).toBe('2g');
+    expect(classifyConnection(undefined, 0.8, { lowUpperBound: 1 })).toBe('2g');
     // Default would classify 0.8 as 3g, custom keeps it as 2g
     expect(classifyConnection(undefined, 0.8)).toBe('3g');
 
     // Custom 4g upper bound
-    expect(classifyConnection(undefined, 8, { downlink4gUpperBound: 10 })).toBe('4g');
+    expect(classifyConnection(undefined, 8, { highUpperBound: 10 })).toBe('4g');
     expect(classifyConnection(undefined, 8)).toBe('high');
   });
 
   it('effectiveType string matches are not affected by thresholds', () => {
-    expect(classifyConnection('2g', undefined, { downlink2gUpperBound: 0.1 })).toBe('2g');
-    expect(classifyConnection('3g', undefined, { downlink3gUpperBound: 0.1 })).toBe('3g');
+    expect(classifyConnection('2g', undefined, { lowUpperBound: 0.1 })).toBe('2g');
+    expect(classifyConnection('3g', undefined, { midUpperBound: 0.1 })).toBe('3g');
   });
 });
 
@@ -204,7 +204,7 @@ describe('classify', () => {
       {
         cpu: { lowUpperBound: 4 },
         memory: { lowUpperBound: 4 },
-        connection: { downlink4gUpperBound: 3 },
+        connection: { highUpperBound: 3 },
       },
     );
     expect(result).toEqual({ cpu: 'low', memory: 'low', connection: 'high', gpu: 'none' });

packages/types/src/__tests__/validate.test.ts

@@ -99,7 +99,7 @@ describe('validateThresholds', () => {
       validateThresholds({
         cpu: { lowUpperBound: 2, midUpperBound: 4 },
         memory: { lowUpperBound: 2, midUpperBound: 8 },
-        connection: { downlink2gUpperBound: 0.5, downlink3gUpperBound: 2, downlink4gUpperBound: 5 },
+        connection: { lowUpperBound: 0.5, midUpperBound: 2, highUpperBound: 5 },
         gpu: { softwarePattern: /SwiftShader/i, highEndPattern: /RTX/i },
       }),
     ).not.toThrow();
@@ -138,19 +138,17 @@ describe('validateThresholds', () => {
     );
   });
 
-  it('throws on inverted connection bounds (2g >= 3g)', () => {
+  it('throws on inverted connection bounds (low >= mid)', () => {
     expect(() =>
-      validateThresholds({ connection: { downlink2gUpperBound: 5, downlink3gUpperBound: 2 } }),
-    ).toThrow(
-      /connection\.downlink2gUpperBound \(5\) must be less than connection\.downlink3gUpperBound \(2\)/,
-    );
+      validateThresholds({ connection: { lowUpperBound: 5, midUpperBound: 2 } }),
+    ).toThrow(/connection\.lowUpperBound \(5\) must be less than connection\.midUpperBound \(2\)/);
   });
 
-  it('throws on inverted connection bounds (3g >= 4g)', () => {
+  it('throws on inverted connection bounds (mid >= high)', () => {
     expect(() =>
-      validateThresholds({ connection: { downlink3gUpperBound: 10, downlink4gUpperBound: 5 } }),
+      validateThresholds({ connection: { midUpperBound: 10, highUpperBound: 5 } }),
     ).toThrow(
-      /connection\.downlink3gUpperBound \(10\) must be less than connection\.downlink4gUpperBound \(5\)/,
+      /connection\.midUpperBound \(10\) must be less than connection\.highUpperBound \(5\)/,
     );
   });
 
@@ -167,8 +165,8 @@ describe('validateThresholds', () => {
   });
 
   it('throws on negative connection threshold', () => {
-    expect(() => validateThresholds({ connection: { downlink2gUpperBound: -0.5 } })).toThrow(
-      /connection\.downlink2gUpperBound must be positive/,
+    expect(() => validateThresholds({ connection: { lowUpperBound: -0.5 } })).toThrow(
+      /connection\.lowUpperBound must be positive/,
     );
   });
 

packages/types/src/classify.ts

@@ -39,19 +39,19 @@ export function classifyConnection(
   downlink?: number,
   thresholds?: Partial<import('./thresholds.js').ConnectionThresholds>,
 ): ConnectionTier {
-  const { downlink2gUpperBound, downlink3gUpperBound, downlink4gUpperBound } = {
+  const { lowUpperBound, midUpperBound, highUpperBound } = {
     ...DEFAULT_CONNECTION_THRESHOLDS,
     ...thresholds,
   };
 
   if (effectiveType === 'slow-2g' || effectiveType === '2g') return '2g';
   if (effectiveType === '3g') return '3g';
-  if (effectiveType === '4g' && downlink != null && downlink < downlink4gUpperBound) return '4g';
+  if (effectiveType === '4g' && downlink != null && downlink < highUpperBound) return '4g';
   if (effectiveType === '4g') return 'high';
   if (downlink != null) {
-    if (downlink < downlink2gUpperBound) return '2g';
-    if (downlink < downlink3gUpperBound) return '3g';
-    if (downlink < downlink4gUpperBound) return '4g';
+    if (downlink < lowUpperBound) return '2g';
+    if (downlink < midUpperBound) return '3g';
+    if (downlink < highUpperBound) return '4g';
     return 'high';
   }
   return '4g';

packages/types/src/thresholds.ts

@@ -9,9 +9,9 @@ export interface MemoryThresholds {
 }
 
 export interface ConnectionThresholds {
-  downlink2gUpperBound: number;
-  downlink3gUpperBound: number;
-  downlink4gUpperBound: number;
+  lowUpperBound: number;
+  midUpperBound: number;
+  highUpperBound: number;
 }
 
 export interface GpuThresholds {
@@ -37,9 +37,9 @@ export const DEFAULT_MEMORY_THRESHOLDS: MemoryThresholds = {
 };
 
 export const DEFAULT_CONNECTION_THRESHOLDS: ConnectionThresholds = {
-  downlink2gUpperBound: 0.5,
-  downlink3gUpperBound: 2,
-  downlink4gUpperBound: 5,
+  lowUpperBound: 0.5,
+  midUpperBound: 2,
+  highUpperBound: 5,
 };
 
 export const DEFAULT_GPU_THRESHOLDS: GpuThresholds = {

packages/types/src/validate.ts

@@ -31,19 +31,16 @@ export function validateThresholds(thresholds: TierThresholds): void {
 
   if (thresholds.connection) {
     const conn = { ...DEFAULT_CONNECTION_THRESHOLDS, ...thresholds.connection };
-    if (conn.downlink2gUpperBound <= 0)
-      errors.push('connection.downlink2gUpperBound must be positive');
-    if (conn.downlink3gUpperBound <= 0)
-      errors.push('connection.downlink3gUpperBound must be positive');
-    if (conn.downlink4gUpperBound <= 0)
-      errors.push('connection.downlink4gUpperBound must be positive');
-    if (conn.downlink2gUpperBound >= conn.downlink3gUpperBound)
+    if (conn.lowUpperBound <= 0) errors.push('connection.lowUpperBound must be positive');
+    if (conn.midUpperBound <= 0) errors.push('connection.midUpperBound must be positive');
+    if (conn.highUpperBound <= 0) errors.push('connection.highUpperBound must be positive');
+    if (conn.lowUpperBound >= conn.midUpperBound)
       errors.push(
-        `connection.downlink2gUpperBound (${conn.downlink2gUpperBound}) must be less than connection.downlink3gUpperBound (${conn.downlink3gUpperBound})`,
+        `connection.lowUpperBound (${conn.lowUpperBound}) must be less than connection.midUpperBound (${conn.midUpperBound})`,
       );
-    if (conn.downlink3gUpperBound >= conn.downlink4gUpperBound)
+    if (conn.midUpperBound >= conn.highUpperBound)
       errors.push(
-        `connection.downlink3gUpperBound (${conn.downlink3gUpperBound}) must be less than connection.downlink4gUpperBound (${conn.downlink4gUpperBound})`,
+        `connection.midUpperBound (${conn.midUpperBound}) must be less than connection.highUpperBound (${conn.highUpperBound})`,
       );
   }