@justair/justair-library 7.5.0 → 7.6.0-alpha.2ec581a

package/dist/constants/deviceTypes.d.ts

@@ -5,6 +5,7 @@ export const DEVICE_TYPES: Readonly<{
 }>;
 export const DEVICE_TYPE_VALUES: readonly ("monitor" | "sample-site" | "linked-device")[];
 export function isAqiCapableDeviceType(deviceType: any): boolean;
+export const AQI_CAPABLE_DEVICE_TYPES: readonly ("monitor" | "sample-site" | "linked-device")[];
 /**
  * The device-type vocabulary as a type, so consumers get autocomplete and a
  * compile error on a mis-cased value like "sampleSite" — the exact bug the

package/dist/constants/deviceTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deviceTypes.d.ts","sourceRoot":"","sources":["../../src/constants/deviceTypes.js"],"names":[],"mappings":"AA0BA;;;;GAIG;AAEH,0FAA6E;AAiBtE,iEAEoC;;;;;;yBAZ9B,CAAA,OAAO,YAAY,EAAC,MAAM,OAAO,YAAY,CAAC"}
+{"version":3,"file":"deviceTypes.d.ts","sourceRoot":"","sources":["../../src/constants/deviceTypes.js"],"names":[],"mappings":"AA0BA;;;;GAIG;AAEH,0FAA6E;AAiBtE,iEAEoC;AAiB3C,gGAEE;;;;;;yBA/BW,CAAA,OAAO,YAAY,EAAC,MAAM,OAAO,YAAY,CAAC"}

package/dist/index.d.ts

@@ -106,7 +106,10 @@ import { getAlertWeight } from "./constants/alertLevels.js";
 import { DEVICE_TYPES } from "./constants/deviceTypes.js";
 import { DEVICE_TYPE_VALUES } from "./constants/deviceTypes.js";
 import { isAqiCapableDeviceType } from "./constants/deviceTypes.js";
+import { AQI_CAPABLE_DEVICE_TYPES } from "./constants/deviceTypes.js";
 import { projectSubscribedMonitors } from "./utils/subscribedDevices.js";
+import { resolveSubscribedMonitorIdsByUser } from "./utils/subscribedDevices.js";
+import { VISIBLE_SITE_MONITOR_FILTER } from "./utils/subscribedDevices.js";
 import { SUBSCRIBED_DEVICES_ERRORS } from "./utils/subscribedDevices.js";
 import { splitName } from "./utils/splitName.js";
 import { DEFAULT_QUIET_HOURS } from "./utils/quietHours.js";
@@ -118,5 +121,5 @@ import { validateQuietHours } from "./utils/quietHours.js";
 import { getZoneMinutes } from "./utils/quietHours.js";
 import { isInQuietWindow } from "./utils/quietHours.js";
 import { resolveQuietHours } from "./utils/quietHours.js";
-export { Database, adminSchema, Admin, configurationsSchema, Configurations, measurementsSchema, Measurements, monitorRequestsSchema, MonitorRequests, monitorsSchema, Monitors, organizationsSchema, Organizations, usersSchema, Users, COOKIE_CONSENT_CATEGORIES, COOKIE_CONSENT_VALUES, validateCookieConsent, eventsSchema, Events, lightMonitorSchema, LightMonitors, monitorSuppliersSchema, MonitorSuppliers, contextsSchema, Contexts, parametersSchema, Parameters, announcementSchema, Announcements, jobsSchema, Jobs, apiKeySchema, ApiKey, UsageMetrics, usageMetricsSchema, Audit, auditSchema, EventsAudit, eventsAuditSchema, MonitorAudit, monitorAuditSchema, parametersEnum, deploymentTypesEnum, AlertsAudit, Alerts, alertsSchema, alertsAuditSchema, Features, featuresSchema, dataCompletenessSchema, DataCompleteness, networkMetricsSchema, NetworkMetrics, rateOfChangeSchema, RateOfChange, changeStreamCheckpointsSchema, ChangeStreamCheckpoints, sitesSchema, Sites, sampleSitesSchema, SampleSites, sampleSiteAuditSchema, SampleSiteAudit, sampleParametersEnum, samplesSchema, Samples, samplesAuditSchema, SamplesAudit, sampleParameterReferenceConcentrations, passwordResetTokenSchema, PasswordResetToken, monitorEpisodesSchema, MonitorEpisode, userNotificationsSchema, UserNotification, AqiAlertNotification, DeviceOfflineNotification, WeeklyDigestNotification, AccountNotification, NOTIFICATION_KINDS, NOTIFICATION_CHANNELS, DELIVERY_STATUSES, DATA_DOWNLOAD_TYPES, dataDownloadSchema, DataDownloads, AqiDataDownload, SampleDataDownload, DATA_DOWNLOAD_MAX_RANGE_DAYS, DATA_DOWNLOAD_ERRORS, validateDataDownloadDateOrder, validateDataDownloadMaxDateRange, validateDataDownloadEmail, normalizeDataDownloadEmail, validateDataDownloadTimezone, normalizeDataDownloadTimezone, PARAMETERS, HEAVY_METALS, ALERT_LEVEL_WEIGHTS, getAlertWeight, DEVICE_TYPES, DEVICE_TYPE_VALUES, isAqiCapableDeviceType, projectSubscribedMonitors, SUBSCRIBED_DEVICES_ERRORS, splitName, DEFAULT_QUIET_HOURS, DEFAULT_TIMEZONE, QUIET_HOURS_ERRORS, isValidTimeString, isValidIANATimezone, validateQuietHours, getZoneMinutes, isInQuietWindow, resolveQuietHours };
+export { Database, adminSchema, Admin, configurationsSchema, Configurations, measurementsSchema, Measurements, monitorRequestsSchema, MonitorRequests, monitorsSchema, Monitors, organizationsSchema, Organizations, usersSchema, Users, COOKIE_CONSENT_CATEGORIES, COOKIE_CONSENT_VALUES, validateCookieConsent, eventsSchema, Events, lightMonitorSchema, LightMonitors, monitorSuppliersSchema, MonitorSuppliers, contextsSchema, Contexts, parametersSchema, Parameters, announcementSchema, Announcements, jobsSchema, Jobs, apiKeySchema, ApiKey, UsageMetrics, usageMetricsSchema, Audit, auditSchema, EventsAudit, eventsAuditSchema, MonitorAudit, monitorAuditSchema, parametersEnum, deploymentTypesEnum, AlertsAudit, Alerts, alertsSchema, alertsAuditSchema, Features, featuresSchema, dataCompletenessSchema, DataCompleteness, networkMetricsSchema, NetworkMetrics, rateOfChangeSchema, RateOfChange, changeStreamCheckpointsSchema, ChangeStreamCheckpoints, sitesSchema, Sites, sampleSitesSchema, SampleSites, sampleSiteAuditSchema, SampleSiteAudit, sampleParametersEnum, samplesSchema, Samples, samplesAuditSchema, SamplesAudit, sampleParameterReferenceConcentrations, passwordResetTokenSchema, PasswordResetToken, monitorEpisodesSchema, MonitorEpisode, userNotificationsSchema, UserNotification, AqiAlertNotification, DeviceOfflineNotification, WeeklyDigestNotification, AccountNotification, NOTIFICATION_KINDS, NOTIFICATION_CHANNELS, DELIVERY_STATUSES, DATA_DOWNLOAD_TYPES, dataDownloadSchema, DataDownloads, AqiDataDownload, SampleDataDownload, DATA_DOWNLOAD_MAX_RANGE_DAYS, DATA_DOWNLOAD_ERRORS, validateDataDownloadDateOrder, validateDataDownloadMaxDateRange, validateDataDownloadEmail, normalizeDataDownloadEmail, validateDataDownloadTimezone, normalizeDataDownloadTimezone, PARAMETERS, HEAVY_METALS, ALERT_LEVEL_WEIGHTS, getAlertWeight, DEVICE_TYPES, DEVICE_TYPE_VALUES, isAqiCapableDeviceType, AQI_CAPABLE_DEVICE_TYPES, projectSubscribedMonitors, resolveSubscribedMonitorIdsByUser, VISIBLE_SITE_MONITOR_FILTER, SUBSCRIBED_DEVICES_ERRORS, splitName, DEFAULT_QUIET_HOURS, DEFAULT_TIMEZONE, QUIET_HOURS_ERRORS, isValidTimeString, isValidIANATimezone, validateQuietHours, getZoneMinutes, isInQuietWindow, resolveQuietHours };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AA6JA;;;iBAEC;yBA7FwB,oBAAoB;qBADxB,gBAAgB;4BAjEF,mBAAmB;sBAAnB,mBAAmB;qCAI/C,4BAA4B;+BAA5B,4BAA4B;mCAM5B,0BAA0B;6BAA1B,0BAA0B;sCAI1B,6BAA6B;gCAA7B,6BAA6B;+BAQ7B,sBAAsB;yBAAtB,sBAAsB;oCACsB,2BAA2B;8BAA3B,2BAA2B;4BAcvE,mBAAmB;sBAAnB,mBAAmB;0CAAnB,mBAAmB;sCAAnB,mBAAmB;sCAAnB,mBAAmB;6BAMnB,oBAAoB;uBAApB,oBAAoB;mCAnBuB,2BAA2B;8BAA3B,2BAA2B;uCAItE,8BAA8B;iCAA9B,8BAA8B;+BACI,sBAAsB;yBAAtB,sBAAsB;iCAClB,wBAAwB;2BAAxB,wBAAwB;mCAcnB,2BAA2B;8BAA3B,2BAA2B;2BAC5C,kBAAkB;qBAAlB,kBAAkB;6BACd,oBAAoB;uBAApB,oBAAoB;6BACR,0BAA0B;mCAA1B,0BAA0B;sBArCpE,0BAA0B;4BAA1B,0BAA0B;4BAiC1B,oBAAoB;kCAApB,oBAAoB;6BArBpB,sBAAsB;mCAAtB,sBAAsB;+BAAtB,sBAAsB;oCAAtB,sBAAsB;4BA+BtB,oBAAoB;uBAApB,oBAAoB;6BAApB,oBAAoB;kCAApB,oBAAoB;yBACc,sBAAsB;+BAAtB,sBAAsB;uCAIxD,8BAA8B;iCAA9B,8BAA8B;qCACgB,4BAA4B;+BAA5B,4BAA4B;mCAChC,0BAA0B;6BAA1B,0BAA0B;8CAIpE,qCAAqC;wCAArC,qCAAqC;4BA4CT,mBAAmB;sBAAnB,mBAAmB;kCAS/C,yBAAyB;4BAAzB,yBAAyB;sCAAzB,yBAAyB;gCAAzB,yBAAyB;qCAAzB,yBAAyB;8BASzB,qBAAqB;wBAArB,qBAAqB;mCAArB,qBAAqB;6BAArB,qBAAqB;uDAArB,qBAAqB;yCACiC,gCAAgC;mCAAhC,gCAAgC;sCAhDtF,6BAA6B;+BAA7B,6BAA6B;wCAW7B,+BAA+B;iCAA/B,+BAA+B;qCAA/B,+BAA+B;0CAA/B,+BAA+B;yCAA/B,+BAA+B;oCAA/B,+BAA+B;mCAA/B,+BAA+B;sCAA/B,+BAA+B;kCAA/B,+BAA+B;oCApBF,8BAA8B;mCA+D3D,2BAA2B;8BAA3B,2BAA2B;gCAA3B,2BAA2B;mCAA3B,2BAA2B;+DAsB3B,mCAAmC;qCAAnC,mCAAmC;mEAAnC,mCAAmC;yEAAnC,mCAAmC;mEAAnC,mCAAmC;qEAAnC,mCAAmC;yEAAnC,mCAAmC;2EAAnC,mCAAmC;2BAxFD,2BAA2B;6BAA3B,2BAA2B;oCAChB,4BAA4B;+BAA5B,4BAA4B;6BAOzE,4BAA4B;mCAA5B,4BAA4B;uCAA5B,4BAA4B;0CA8B5B,8BAA8B;0CAA9B,8BAA8B;0BAdX,sBAAsB;oCASzC,uBAAuB;iCA/BG,0BAA0B;mCA+BpD,uBAAuB;kCAAvB,uBAAuB;oCACM,qBAAqB;mCADlD,uBAAuB;+BAAvB,uBAAuB;gCAAvB,uBAAuB;kCAAvB,uBAAuB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AAyKA;;;iBAEC;yBAtGwB,oBAAoB;qBADxB,gBAAgB;4BApEF,mBAAmB;sBAAnB,mBAAmB;qCAI/C,4BAA4B;+BAA5B,4BAA4B;mCAM5B,0BAA0B;6BAA1B,0BAA0B;sCAI1B,6BAA6B;gCAA7B,6BAA6B;+BAQ7B,sBAAsB;yBAAtB,sBAAsB;oCACsB,2BAA2B;8BAA3B,2BAA2B;4BAcvE,mBAAmB;sBAAnB,mBAAmB;0CAAnB,mBAAmB;sCAAnB,mBAAmB;sCAAnB,mBAAmB;6BAMnB,oBAAoB;uBAApB,oBAAoB;mCAnBuB,2BAA2B;8BAA3B,2BAA2B;uCAItE,8BAA8B;iCAA9B,8BAA8B;+BACI,sBAAsB;yBAAtB,sBAAsB;iCAClB,wBAAwB;2BAAxB,wBAAwB;mCAcnB,2BAA2B;8BAA3B,2BAA2B;2BAC5C,kBAAkB;qBAAlB,kBAAkB;6BACd,oBAAoB;uBAApB,oBAAoB;6BACR,0BAA0B;mCAA1B,0BAA0B;sBArCpE,0BAA0B;4BAA1B,0BAA0B;4BAiC1B,oBAAoB;kCAApB,oBAAoB;6BArBpB,sBAAsB;mCAAtB,sBAAsB;+BAAtB,sBAAsB;oCAAtB,sBAAsB;4BA+BtB,oBAAoB;uBAApB,oBAAoB;6BAApB,oBAAoB;kCAApB,oBAAoB;yBACc,sBAAsB;+BAAtB,sBAAsB;uCAIxD,8BAA8B;iCAA9B,8BAA8B;qCAI9B,4BAA4B;+BAA5B,4BAA4B;mCACc,0BAA0B;6BAA1B,0BAA0B;8CAIpE,qCAAqC;wCAArC,qCAAqC;4BAkDT,mBAAmB;sBAAnB,mBAAmB;kCAS/C,yBAAyB;4BAAzB,yBAAyB;sCAAzB,yBAAyB;gCAAzB,yBAAyB;qCAAzB,yBAAyB;8BASzB,qBAAqB;wBAArB,qBAAqB;mCAArB,qBAAqB;6BAArB,qBAAqB;uDAArB,qBAAqB;yCAIrB,gCAAgC;mCAAhC,gCAAgC;sCArDhC,6BAA6B;+BAA7B,6BAA6B;wCAW7B,+BAA+B;iCAA/B,+BAA+B;qCAA/B,+BAA+B;0CAA/B,+BAA+B;yCAA/B,+BAA+B;oCAA/B,+BAA+B;mCAA/B,+BAA+B;sCAA/B,+BAA+B;kCAA/B,+BAA+B;oCArBF,8BAA8B;mCAqE3D,2BAA2B;8BAA3B,2BAA2B;gCAA3B,2BAA2B;mCAA3B,2BAA2B;+DAsB3B,mCAAmC;qCAAnC,mCAAmC;mEAAnC,mCAAmC;yEAAnC,mCAAmC;mEAAnC,mCAAmC;qEAAnC,mCAAmC;yEAAnC,mCAAmC;2EAAnC,mCAAmC;2BAjGD,2BAA2B;6BAA3B,2BAA2B;oCAI7D,4BAA4B;+BAA5B,4BAA4B;6BAQ5B,4BAA4B;mCAA5B,4BAA4B;uCAA5B,4BAA4B;yCAA5B,4BAA4B;0CAgC5B,8BAA8B;kDAA9B,8BAA8B;4CAA9B,8BAA8B;0CAA9B,8BAA8B;0BAhBX,sBAAsB;oCASzC,uBAAuB;iCAhCG,0BAA0B;mCAgCpD,uBAAuB;kCAAvB,uBAAuB;oCACM,qBAAqB;mCADlD,uBAAuB;+BAAvB,uBAAuB;gCAAvB,uBAAuB;kCAAvB,uBAAuB"}

package/dist/models/users.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/models/users.js"],"names":[],"mappings":"AAyFA,8BAgGE;AAiCF,wBAAmD;AAjNnD,iDAA4D;AAC5D,6CAAmD;AAUnD,4DAsBC"}
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/models/users.js"],"names":[],"mappings":"AA6FA,8BA0GE;AAiCF,wBAAmD;AA/NnD,iDAA4D;AAC5D,6CAAmD;AAUnD,4DA0BC"}

package/dist/utils/subscribedDevices.d.ts

@@ -3,6 +3,15 @@ export const SUBSCRIBED_DEVICES_ERRORS: Readonly<{
     RESOLVER_RETURNED_NON_ARRAY: "resolver_returned_non_array";
     RESOLVER_RETURNED_NESTED_ARRAYS: "resolver_returned_nested_arrays";
     RESOLVER_RETURNED_DOCUMENTS: "resolver_returned_documents";
+    MISSING_COHORT_SITE_RESOLVER: "missing_cohort_site_resolver";
+    COHORT_RESOLVER_RETURNED_NON_MAP: "cohort_resolver_returned_non_map";
+    COHORT_USER_MISSING_ID: "cohort_user_missing_id";
+}>;
+export const VISIBLE_SITE_MONITOR_FILTER: Readonly<{
+    isPrivate: Readonly<{
+        $ne: true;
+    }>;
+    isActive: true;
 }>;
 export function projectSubscribedMonitors(subscribedDevices?: Array<{
     deviceId: import("mongoose").Types.ObjectId;
@@ -10,4 +19,13 @@ export function projectSubscribedMonitors(subscribedDevices?: Array<{
 }>, { resolveSiteMonitorIds }?: {
     resolveSiteMonitorIds?: (siteIds: import("mongoose").Types.ObjectId[]) => Promise<Array<import("mongoose").Types.ObjectId | null | undefined>>;
 }): Promise<import("mongoose").Types.ObjectId[]>;
+export function resolveSubscribedMonitorIdsByUser(users?: Array<{
+    _id: any;
+    subscribedDevices?: Array<{
+        deviceId: import("mongoose").Types.ObjectId;
+        deviceType: import("../constants/deviceTypes.js").DeviceType;
+    }>;
+}>, { resolveVisibleSiteMonitors }?: {
+    resolveVisibleSiteMonitors?: (siteIds: import("mongoose").Types.ObjectId[]) => Promise<Map<string, import("mongoose").Types.ObjectId[]>>;
+}): Promise<Map<string, import("mongoose").Types.ObjectId[]>>;
 //# sourceMappingURL=subscribedDevices.d.ts.map

package/dist/utils/subscribedDevices.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscribedDevices.d.ts","sourceRoot":"","sources":["../../src/utils/subscribedDevices.js"],"names":[],"mappings":"AAqFA;;;;;GAKG;AA4II,8DANI,KAAK,CAAC;IAAE,QAAQ,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC;IAC1D,UAAU,EAAE,OAAO,6BAA6B,EAAE,UAAU,CAAA;CAAE,CAAC,8BACzD;IAAE,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,KAC7E,OAAO,CAAC,KAAK,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAA;CAAE,GAC9D,OAAO,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CA0BxD"}
+{"version":3,"file":"subscribedDevices.d.ts","sourceRoot":"","sources":["../../src/utils/subscribedDevices.js"],"names":[],"mappings":"AA0FA;;;;;;;;GASG;AA+CH;;;;;GAGG;AA6LI,8DANI,KAAK,CAAC;IAAE,QAAQ,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC;IAC1D,UAAU,EAAE,OAAO,6BAA6B,EAAE,UAAU,CAAA;CAAE,CAAC,8BACzD;IAAE,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,KAC7E,OAAO,CAAC,KAAK,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAA;CAAE,GAC9D,OAAO,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CA0BxD;AA0EM,0DAPI,KAAK,CAAC;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,iBAAiB,CAAC,EAAE,KAAK,CAAC;QAClD,QAAQ,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC;QAC5C,UAAU,EAAE,OAAO,6BAA6B,EAAE,UAAU,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,mCAC5D;IAAE,0BAA0B,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,KAClF,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAA;CAAE,GACnD,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAmErE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justair/justair-library",
-  "version": "7.5.0",
+  "version": "7.6.0-alpha.2ec581a",
   "description": "JustAir Internal Library",
   "main": "src/index.js",
   "type": "module",

package/src/constants/deviceTypes.js

@@ -50,3 +50,22 @@ export const DEVICE_TYPE_VALUES = Object.freeze(Object.values(DEVICE_TYPES));
 export const isAqiCapableDeviceType = (deviceType) =>
   deviceType === DEVICE_TYPES.MONITOR ||
   deviceType === DEVICE_TYPES.LINKED_DEVICE;
+
+// The same predicate in the shape a Mongo query wants, so a cohort read can
+// leave out rows that could never alert instead of loading and discarding
+// them:
+//
+//   { "subscribedDevices.deviceType": { $in: AQI_CAPABLE_DEVICE_TYPES } }
+//
+// Derived from isAqiCapableDeviceType's own answer rather than hand-listed, so
+// the two cannot disagree if a fourth device type ever arrives. Frozen for the
+// same reason DEVICE_TYPE_VALUES is: every importer in a process shares this
+// instance, and one `.push()` would silently widen the audience for all of
+// them.
+//
+// Carries the same asymmetry the predicate does: `linked-device` being in this
+// list is necessary and NOT sufficient — a Site only actually alerts when it
+// links at least one monitor, which no query on deviceType can tell you.
+export const AQI_CAPABLE_DEVICE_TYPES = Object.freeze(
+  DEVICE_TYPE_VALUES.filter(isAqiCapableDeviceType),
+);

package/src/constants/tests/deviceTypes.test.js

@@ -8,12 +8,14 @@ import {
   DEVICE_TYPES,
   DEVICE_TYPE_VALUES,
   isAqiCapableDeviceType,
+  AQI_CAPABLE_DEVICE_TYPES,
 } from '../deviceTypes.js';
 
 test('barrel exports the device-type constants', () => {
   expect(barrel.DEVICE_TYPES).toBe(DEVICE_TYPES);
   expect(barrel.DEVICE_TYPE_VALUES).toBe(DEVICE_TYPE_VALUES);
   expect(barrel.isAqiCapableDeviceType).toBe(isAqiCapableDeviceType);
+  expect(barrel.AQI_CAPABLE_DEVICE_TYPES).toBe(AQI_CAPABLE_DEVICE_TYPES);
 });
 
 test('DEVICE_TYPES values match the strings the devices API emits', () => {
@@ -51,3 +53,23 @@ describe('isAqiCapableDeviceType', () => {
     expect(isAqiCapableDeviceType('')).toBe(false);
   });
 });
+
+describe('AQI_CAPABLE_DEVICE_TYPES', () => {
+  test('is the $in form of isAqiCapableDeviceType, in vocabulary order', () => {
+    expect(AQI_CAPABLE_DEVICE_TYPES).toEqual(['monitor', 'linked-device']);
+  });
+
+  test('agrees with the predicate for every device type', () => {
+    // Derived from the predicate rather than hand-listed, so this pins that
+    // the derivation stays wired up if a fourth device type is added.
+    DEVICE_TYPE_VALUES.forEach((deviceType) => {
+      expect(AQI_CAPABLE_DEVICE_TYPES.includes(deviceType)).toBe(
+        isAqiCapableDeviceType(deviceType),
+      );
+    });
+  });
+
+  test('is frozen — every importer shares this instance', () => {
+    expect(Object.isFrozen(AQI_CAPABLE_DEVICE_TYPES)).toBe(true);
+  });
+});

package/src/index.js

@@ -57,7 +57,10 @@ import {
   DataCompleteness,
   dataCompletenessSchema,
 } from "./models/dataCompleteness.js";
-import { NetworkMetrics, networkMetricsSchema } from "./models/networkMetrics.js";
+import {
+  NetworkMetrics,
+  networkMetricsSchema,
+} from "./models/networkMetrics.js";
 import { RateOfChange, rateOfChangeSchema } from "./models/rateOfChange.js";
 import {
   ChangeStreamCheckpoints,
@@ -66,13 +69,17 @@ import {
 import Database from "./config/db.js"; // Import the new Database class
 import CustomLogger from "./config/logger.js";
 import { PARAMETERS, HEAVY_METALS } from "./constants/pollutants.js";
-import { ALERT_LEVEL_WEIGHTS, getAlertWeight } from "./constants/alertLevels.js";
+import {
+  ALERT_LEVEL_WEIGHTS,
+  getAlertWeight,
+} from "./constants/alertLevels.js";
 import { DEFAULT_TIMEZONE } from "./constants/timezones.js";
 import { DATA_DOWNLOAD_TYPES } from "./constants/dataDownloads.js";
 import {
   DEVICE_TYPES,
   DEVICE_TYPE_VALUES,
   isAqiCapableDeviceType,
+  AQI_CAPABLE_DEVICE_TYPES,
 } from "./constants/deviceTypes.js";
 import {
   monitorEpisodesSchema,
@@ -102,6 +109,8 @@ import {
 import { isValidIANATimezone } from "./utils/timezone.js";
 import {
   projectSubscribedMonitors,
+  resolveSubscribedMonitorIdsByUser,
+  VISIBLE_SITE_MONITOR_FILTER,
   SUBSCRIBED_DEVICES_ERRORS,
 } from "./utils/subscribedDevices.js";
 
@@ -125,7 +134,10 @@ import {
   SamplesAudit,
   sampleParameterReferenceConcentrations,
 } from "./models/samples.js";
-import { passwordResetTokenSchema, PasswordResetToken } from "./models/passwordResetToken.js";
+import {
+  passwordResetTokenSchema,
+  PasswordResetToken,
+} from "./models/passwordResetToken.js";
 import {
   dataDownloadSchema,
   DataDownloads,
@@ -272,13 +284,34 @@ export {
   DEVICE_TYPES,
   DEVICE_TYPE_VALUES,
   isAqiCapableDeviceType,
-  // subscribedDevices → subscribedMonitors projection (JA-3110 / JA-3335).
-  // Every consumer that writes a subscription recomputes the AQI audience with
-  // this instead of re-implementing the per-device-type rule.
-  // SUBSCRIBED_DEVICES_ERRORS is the stable `err.code` vocabulary for the
-  // errors projectSubscribedMonitors throws; consumers branch on it rather
-  // than on message wording.
+  // The query form of isAqiCapableDeviceType, for narrowing a Users read to
+  // rows that could actually alert:
+  //   { "subscribedDevices.deviceType": { $in: AQI_CAPABLE_DEVICE_TYPES } }
+  AQI_CAPABLE_DEVICE_TYPES,
+  // subscribedDevices → monitor ids, resolved at READ time (JA-3110 / JA-3335).
+  // Users.subscribedDevices is the source of truth; Users.subscribedMonitors is
+  // being retired rather than kept in step with it. Nothing should store this
+  // result — see the module header for the five bugs a stored copy caused.
+  //
+  // Both resolvers are only correct for users whose subscribedDevices has been
+  // backfilled from subscribedMonitors — read the PRECONDITION block in the
+  // module header before pointing a service at either of them.
+  //
+  //   resolveSubscribedMonitorIdsByUser — the batch form. One Sites lookup for
+  //                              a whole cohort. What alert runs, org pages and
+  //                              session responses should call.
+  //   projectSubscribedMonitors — the single-user rule the batch form is built
+  //                              on. Named after the field being retired; it
+  //                              gets renamed when that field is dropped.
+  //   VISIBLE_SITE_MONITOR_FILTER — the privacy predicate every consumer must
+  //                              apply when turning a Site into monitor ids.
+  //                              Sites.monitorIds is unfiltered; reading it
+  //                              straight through leaks private monitors.
+  //   SUBSCRIBED_DEVICES_ERRORS — stable `err.code` vocabulary; consumers
+  //                              branch on it, never on message wording.
   projectSubscribedMonitors,
+  resolveSubscribedMonitorIdsByUser,
+  VISIBLE_SITE_MONITOR_FILTER,
   SUBSCRIBED_DEVICES_ERRORS,
   // Utilities
   splitName,

package/src/models/users.js

@@ -15,11 +15,15 @@ const cookieConsentSchemaDefinition = COOKIE_CONSENT_CATEGORIES.reduce(
     definition[category] = { type: String, enum: COOKIE_CONSENT_VALUES };
     return definition;
   },
-  {}
+  {},
 );
 
 const validateCookieConsent = (consent) => {
-  if (typeof consent !== "object" || consent === null || Array.isArray(consent)) {
+  if (
+    typeof consent !== "object" ||
+    consent === null ||
+    Array.isArray(consent)
+  ) {
     return "cookie_consent must be an object";
   }
 
@@ -34,7 +38,7 @@ const validateCookieConsent = (consent) => {
     }
     if (!COOKIE_CONSENT_VALUES.includes(value)) {
       return `Invalid value for ${category}: must be one of ${COOKIE_CONSENT_VALUES.join(
-        ", "
+        ", ",
       )}`;
     }
   }
@@ -84,7 +88,7 @@ const subscribedDeviceSchema = mongoose.Schema(
     // writing (and/or pass `{ runValidators: true }` to the update).
     deviceType: { type: String, enum: DEVICE_TYPE_VALUES, required: true },
   },
-  { _id: false }
+  { _id: false },
 );
 
 const usersSchema = mongoose.Schema(
@@ -99,21 +103,31 @@ const usersSchema = mongoose.Schema(
     organizations: [{ type: mongoose.Types.ObjectId, ref: "Organizations" }],
     alertPhone: String,
     alertCount: { type: Number, default: 0 },
+    // BEING RETIRED (JA-3110 / JA-3335). This was a denormalized copy of the
+    // AQI-alert audience, rewritten on every subscribe and unsubscribe. Do not
+    // write it from new code and do not keep it in step with anything: the
+    // audience is now RESOLVED AT READ TIME from subscribedDevices below, and
+    // the field is dropped once every consumer has moved off it. Five distinct
+    // silent-failure bugs traced back to maintaining this copy; they are
+    // enumerated in the header of src/utils/subscribedDevices.js.
+    //
+    // It is still read (and still the correct thing to read) for any user
+    // whose subscribedDevices has not been backfilled yet — the same header's
+    // PRECONDITION block has the ordering.
     subscribedMonitors: [{ type: mongoose.Types.ObjectId, ref: "Monitors" }],
-    // Subscribed devices (JA-3110 / JA-3335) — the source of truth for what the
+    // Subscribed devices (JA-3110 / JA-3335) — the SOURCE OF TRUTH for what the
     // user has added to "My Monitors", across all three device types.
     //
-    // subscribedMonitors above is its derived AQI-alert projection (monitor ids
-    // only). The two must be written together on every subscribe and
-    // unsubscribe path, using `projectSubscribedMonitors` rather than a
-    // per-consumer reimplementation. It is deliberately not a schema validator:
-    // the projection needs a Site lookup, which the schema has no business
-    // doing.
+    // The monitor ids this implies are derived on read, never stored:
+    // `resolveSubscribedMonitorIdsByUser` for a cohort,
+    // `projectSubscribedMonitors` for one user, both exported from
+    // src/index.js. Deliberately not a schema validator — the derivation needs
+    // a Site lookup, which the schema has no business doing.
     //
     // Everything else — the per-device-type rule, the backfill PRECONDITION,
-    // the STALENESS gap, and why the field is split at all — is specified once,
-    // in the header of src/utils/subscribedDevices.js. Read it there; it is
-    // deliberately not summarised here.
+    // the privacy obligation, and why the field is split at all — is specified
+    // once, in the header of src/utils/subscribedDevices.js. Read it there; it
+    // is deliberately not summarised here.
     subscribedDevices: [subscribedDeviceSchema],
     currentAlertMode: {
       type: String,
@@ -182,7 +196,7 @@ const usersSchema = mongoose.Schema(
   },
   {
     timestamps: true,
-  }
+  },
 );
 
 // Cross-field quiet-hours rules (both-or-neither, start ≠ end) delegated to

package/src/utils/subscribedDevices.js

@@ -1,15 +1,6 @@
-// Subscribed devices (JA-3110 / JA-3335): the shared projection from
-// Users.subscribedDevices (source of truth, all three device types) to
-// Users.subscribedMonitors (monitor ids only, the AQI-alert audience).
-//
-// Single source of truth for every consumer that writes a subscription —
-// JustAirUserService recomputes on subscribe/unsubscribe, and any backfill or
-// repair script uses the same function. Pure: no DB, no logger, no clock. The
-// one thing it cannot know on its own is which monitors a Site links, so that
-// lookup is injected as `resolveSiteMonitorIds`.
-//
-// The rule, per JA-3110 AC "user will receive AQI notifications if the site
-// has an AQI":
+// Subscribed devices (JA-3110 / JA-3335): resolving Users.subscribedDevices —
+// the source of truth for what a user follows, across all three device types —
+// down to the flat monitor ids that make up their AQI-alert audience.
 //
 //   monitor        → contributes its own deviceId
 //   linked-device  → contributes the monitorIds of its Site (none if the Site
@@ -18,65 +9,79 @@
 //   sample-site    → contributes nothing; no live AQI, so it can never trigger
 //                    an AQI alert
 //
-// Recompute-whole, not delta: callers pass the complete post-change
-// subscribedDevices array and overwrite subscribedMonitors with the result.
-// That makes unsubscribe fall out for free — a Site's monitors disappear from
-// the projection only when no other subscribed device still contributes them —
-// and makes the function idempotent, so a repair run over existing users is
-// safe to repeat.
+// Pure: no DB, no logger, no clock. The one thing this module cannot know on
+// its own is which monitors a Site links, so that lookup is injected.
+//
+// ---------------------------------------------------------------------------
+// THIS IS A READ-TIME RESOLUTION, NOT A STORED PROJECTION
+// ---------------------------------------------------------------------------
+// `Users.subscribedMonitors` used to be a denormalized copy of this result,
+// written on every subscribe and unsubscribe. It is being removed
+// (JA-3110 "Retire subscribedMonitors"), and this module is what replaces it:
+// consumers resolve the audience when they need it and store nothing.
+//
+// That decision came out of the JA-3110 review, where five separate
+// silent-failure bugs all traced back to keeping a stored copy in step with
+// the source of truth:
+//
+//   * a legacy id with no subscribedDevices row being dropped when a Site that
+//     linked the same monitor was unfollowed
+//   * "half-migrated" users — a stored copy holding ids the source of truth
+//     did not — passing a migration gate that checked presence, not content
+//   * unsubscribe computing a removal set from a snapshot, so a concurrent
+//     subscribe lost its contribution
+//   * a hard-deleted Site leaving its monitors in the stored copy forever
+//   * a Site gaining or losing a monitor never reaching its existing followers
+//
+// None of those exist here. There is no snapshot to go stale, nothing to
+// reproject when a Site changes, and unsubscribe is a plain `$pull` of one
+// subscribedDevices entry. If you find yourself reintroducing a stored copy of
+// this result, you are reintroducing all five.
+//
+// ---------------------------------------------------------------------------
+// PRECONDITION: THE BACKFILL LANDS BEFORE ANY CONSUMER SWITCHES OVER
+// ---------------------------------------------------------------------------
+// Resolving at read time is only CORRECT for a user whose `subscribedDevices`
+// has already been backfilled from `subscribedMonitors`. A user who predates
+// the field carries a full `subscribedMonitors` and no `subscribedDevices` key
+// at all on a `.lean()` read — real state, pinned in
+// `src/models/tests/users.test.js`. Call `resolveSubscribedMonitorIdsByUser`
+// on that user and you get `[]` back: their AQI alerts stop, and nothing
+// anywhere errors.
+//
+// So the ordering is not negotiable. Per environment: backfill
+// `subscribedDevices` from `subscribedMonitors` FIRST, verify it, and only
+// then point that environment's consumers at this module. Until the backfill
+// has run there, consumers keep reading `subscribedMonitors`. Dropping the
+// field is the last step of the JA-3110 plan (see "JA-3110 — Retire
+// subscribedMonitors" in JustAirService `TODOS.md`), never the first.
+//
+// This module cannot detect the un-backfilled case for you — an empty
+// `subscribedDevices` and "follows nothing" are the same value — which is
+// exactly why the ordering has to be an operational guarantee rather than a
+// runtime check.
 //
 // ---------------------------------------------------------------------------
-// PRECONDITION — do not overwrite subscribedMonitors before the backfill
+// PRIVACY IS THE CALLER'S JOB, AND IT IS NOT OPTIONAL
 // ---------------------------------------------------------------------------
-// Every user who existed before this field shipped has a populated
-// subscribedMonitors and an empty or absent subscribedDevices (pinned by the
-// "reads pre-backfill users cleanly" case in models/tests/users.test.js). For
-// such a user this function correctly returns a projection of *nothing they
-// have migrated yet* — so a consumer that overwrites subscribedMonitors with
-// it on the user's next subscribe silently drops every monitor they were
-// already subscribed to, and their AQI alerts stop with no error anywhere.
-//
-// Callers MUST therefore do one of these, per user, and the ordering is not
-// optional:
-//   1. Backfill subscribedDevices from subscribedMonitors first (one
-//      { deviceId, deviceType: "monitor" } entry per existing id), then
-//      overwrite freely. This is the target state.
-//   2. Until that backfill has run for the user, union the projection with the
-//      existing subscribedMonitors instead of overwriting — AND write the
-//      per-user backfill in the same update, one
-//      { deviceId, deviceType: "monitor" } entry per id already in
-//      subscribedMonitors, alongside the device being subscribed. Both halves
-//      are required. Unioning without backfilling leaves a user who looks
-//      migrated (subscribedDevices is non-empty) but is not, so the obvious
-//      "has this user been backfilled?" check answers yes and the next
-//      unsubscribe overwrites subscribedMonitors with a projection missing
-//      every monitor they had before. A half-migrated user must never exist.
-//
-//      This path is also SUBSCRIBE-ONLY. A union can only ever add ids, so
-//      using it for an unsubscribe makes the removal a silent no-op. There is
-//      deliberately no third option: an unsubscribe on a user who predates
-//      subscribedDevices MUST be preceded by the backfill, and only then
-//      overwrite. Removing a subscription is not correct any other way.
-//
-// This module deliberately does NOT offer a `union: true` flag. A blanket
-// union is correct for subscribe and silently wrong for unsubscribe — it would
-// make removal a no-op — so the choice belongs at the call site, which knows
-// which operation it is performing. The backfill itself is consumer-side
-// (JustAirUserService owns the write path) and is not shipped in this library;
-// it needs its own ticket under JA-3110 before any consumer moves to
-// overwrite-always.
+// A Site's `monitorIds` is a raw membership list with no visibility filtering.
+// Reading it straight through enrols a Site's followers in alerts for any
+// private monitor it links — a real leak, not a theoretical one, because the
+// notification service filters monitors on `monitorState`/`isActive` and not on
+// `isPrivate`.
+//
+// So the injected resolver must return only VISIBLE monitors, which is why it
+// is named `resolveVisibleSiteMonitors` and why VISIBLE_SITE_MONITOR_FILTER
+// exists below: three repos need the same predicate, and `$ne: true` (rather
+// than `false`) is the half that is easy to get wrong on documents written
+// before `isPrivate` existed.
 //
 // ---------------------------------------------------------------------------
-// STALENESS — this is a write-path projection only
+// NAMING
 // ---------------------------------------------------------------------------
-// The result is only as current as the last time a caller ran it. Nothing here
-// watches Sites: if a Site gains or loses a monitor after a user subscribed to
-// it, that user's subscribedMonitors stays as it was and their AQI audience is
-// wrong — a monitor added to a Site never alerts its existing subscribers, and
-// a removed one keeps alerting them, in both cases silently. Any code that
-// mutates Sites.monitorIds is therefore responsible for reprojecting the
-// affected subscribers. That reprojection is not implemented anywhere yet and
-// needs a follow-up ticket under JA-3110.
+// `projectSubscribedMonitors` is named after the field being retired. It is
+// kept under that name while consumers migrate; renaming it to something that
+// does not reference a dead field belongs in the step that drops the field.
 
 import { DEVICE_TYPES } from "../constants/deviceTypes.js";
 
@@ -88,6 +93,60 @@ export const SUBSCRIBED_DEVICES_ERRORS = Object.freeze({
   RESOLVER_RETURNED_NON_ARRAY: "resolver_returned_non_array",
   RESOLVER_RETURNED_NESTED_ARRAYS: "resolver_returned_nested_arrays",
   RESOLVER_RETURNED_DOCUMENTS: "resolver_returned_documents",
+  // resolveSubscribedMonitorIdsByUser only
+  MISSING_COHORT_SITE_RESOLVER: "missing_cohort_site_resolver",
+  COHORT_RESOLVER_RETURNED_NON_MAP: "cohort_resolver_returned_non_map",
+  COHORT_USER_MISSING_ID: "cohort_user_missing_id",
+});
+
+// The predicate that makes a Site's monitor visible to its followers. Frozen
+// and exported because JustAirService, JustAirUserService and
+// JustAirNotificationService all need the same one, and a fourth hand-written
+// copy is how one of them quietly starts leaking private monitors.
+//
+// `isPrivate: { $ne: true }` rather than `{ $eq: false }`: the field has a
+// schema default but that only governs writes made through mongoose, so
+// documents written before it existed have no key at all and would vanish
+// under an exact match. Same rule the public-map path uses.
+//
+// Spread it into the Monitors query the resolver is built from:
+//
+//   const monitors = await Monitors.find(
+//     { _id: { $in: siteMonitorIds }, ...VISIBLE_SITE_MONITOR_FILTER },
+//     "_id",
+//   ).lean();
+//
+// `isActive: true` is an EXACT match, and that asymmetry with the `$ne` above
+// is DELIBERATE — do not "fix" it to `{ $ne: false }`. The two clauses answer
+// different questions. `isPrivate` is a privacy gate: a monitor with no
+// `isPrivate` key was never marked private, so excluding it would hide a
+// monitor its followers are entitled to see. `isActive` is an eligibility
+// gate: a monitor only earns a place in an alert audience by positively
+// asserting it is active. A document with no `isActive` key has made no such
+// assertion, and the safe reading of "we don't know" is to leave it out rather
+// than alert on it.
+//
+// So the failure modes are not symmetric and should not be made symmetric.
+// Over-including here means alerting people about a monitor nobody confirmed
+// is live; under-including means one unconfirmed monitor is missing from an
+// audience until someone sets the flag. This predicate takes the second.
+//
+// `monitorState: "Deployed"` is deliberately NOT here. That is an
+// alerting-eligibility rule, not a visibility rule, and it belongs to the
+// notification service alone — the org admin page and the session response
+// must still show a follower the monitors they follow while those monitors sit
+// in a non-Deployed state. Do not consolidate the two filters; keep
+// JustAirNotificationService's own `monitorState` predicate where it is.
+//
+// Frozen at every level, not just the top. `Object.freeze` is shallow, so a
+// top-level-only freeze still lets a consumer write
+// `VISIBLE_SITE_MONITOR_FILTER.isPrivate.$ne = false` — and because every
+// consumer spreads THIS instance, that one write flips the privacy predicate
+// for the whole process. `isPrivate` is the only nested object here; freeze it
+// too, and freeze any operator object a future clause introduces.
+export const VISIBLE_SITE_MONITOR_FILTER = Object.freeze({
+  isPrivate: Object.freeze({ $ne: true }),
+  isActive: true,
 });
 
 // Dedupe by string form, keep the caller's ObjectId instances. Two equal
@@ -148,7 +207,7 @@ const validateResolvedSiteMonitorIds = (resolved) => {
 
   if (!Array.isArray(resolved)) {
     const error = new TypeError(
-      "resolveSiteMonitorIds must resolve to an array of monitor ids"
+      "resolveSiteMonitorIds must resolve to an array of monitor ids",
     );
     error.code = SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_NON_ARRAY;
     throw error;
@@ -160,7 +219,7 @@ const validateResolvedSiteMonitorIds = (resolved) => {
   // silently works, two throws a CastError at write time, far from the cause.
   if (resolved.some(Array.isArray)) {
     const error = new TypeError(
-      "resolveSiteMonitorIds must resolve to a flat array of monitor ids"
+      "resolveSiteMonitorIds must resolve to a flat array of monitor ids",
     );
     error.code = SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_NESTED_ARRAYS;
     throw error;
@@ -176,11 +235,11 @@ const validateResolvedSiteMonitorIds = (resolved) => {
   // (`Sites.find(..., "monitorIds -_id").lean()`) carries none.
   if (
     resolved.some(
-      (id) => isPlainObject(id) && typeof id.toHexString !== "function"
+      (id) => isPlainObject(id) && typeof id.toHexString !== "function",
     )
   ) {
     const error = new TypeError(
-      "resolveSiteMonitorIds must resolve to monitor ids, not Site documents"
+      "resolveSiteMonitorIds must resolve to monitor ids, not Site documents",
     );
     error.code = SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_DOCUMENTS;
     throw error;
@@ -189,10 +248,42 @@ const validateResolvedSiteMonitorIds = (resolved) => {
   return resolved;
 };
 
-// Returns the monitor ids that should be stored in Users.subscribedMonitors for
-// the given subscribedDevices array. Order is deterministic — direct `monitor`
-// subscriptions in array order, then Site-derived ids in resolver order, first
-// occurrence wins — but carries no meaning; treat the result as a set.
+// The cohort resolver's return, checked the same way and for the same reason:
+// it is consumer-supplied, and every bad shape below would otherwise resolve to
+// an empty audience rather than an error — a user silently stops getting
+// alerts, which is the one outcome this module exists to prevent.
+//
+// Keys are re-derived with String() rather than trusted. A consumer who builds
+// `new Map([[site._id, ids]])` with raw ObjectId keys produces a Map that looks
+// correct, passes every type check, and misses on every `.get(String(id))`
+// because two equal ObjectIds are different object identities. Normalising is
+// forgiving in precisely the place where strictness would fail silently.
+const validateResolvedSiteMonitorMap = (resolved) => {
+  if (resolved === null || resolved === undefined) {
+    return new Map();
+  }
+
+  if (!(resolved instanceof Map)) {
+    const error = new TypeError(
+      "resolveVisibleSiteMonitors must resolve to a Map of site id to monitor ids",
+    );
+    error.code = SUBSCRIBED_DEVICES_ERRORS.COHORT_RESOLVER_RETURNED_NON_MAP;
+    throw error;
+  }
+
+  return new Map(
+    [...resolved.entries()].map(([siteId, monitorIds]) => [
+      String(siteId),
+      validateResolvedSiteMonitorIds(monitorIds),
+    ]),
+  );
+};
+
+// Resolves one user's subscribedDevices array down to the flat monitor ids
+// that make up their AQI-alert audience. Order is deterministic — direct
+// `monitor` subscriptions in array order, then Site-derived ids in resolver
+// order, first occurrence wins — but carries no meaning; treat the result as a
+// set. This is a value to use, not a value to persist (see below).
 //
 // `subscribedDevices` tolerates undefined/null: a user row written before this
 // field existed has no key at all on a `.lean()` read (pinned in
@@ -201,10 +292,21 @@ const validateResolvedSiteMonitorIds = (resolved) => {
 //
 // `resolveSiteMonitorIds(siteIds)` is called at most once, with every
 // linked-device id at a time, and must resolve to the flat union of those
-// Sites' monitorIds — the ids themselves, not the Site documents:
+// Sites' VISIBLE monitorIds — the ids themselves, not the Site documents.
+// `Sites.monitorIds` is a raw membership list, so it goes through
+// VISIBLE_SITE_MONITOR_FILTER before it becomes an alert audience; handing
+// back `site.monitorIds` untouched is the leak the privacy note above
+// describes:
 //
 //   const sites = await Sites.find({ _id: { $in: siteIds } }, "monitorIds").lean();
-//   return sites.flatMap((site) => site.monitorIds ?? []);
+//   const monitors = await Monitors.find(
+//     {
+//       _id: { $in: sites.flatMap((site) => site.monitorIds ?? []) },
+//       ...VISIBLE_SITE_MONITOR_FILTER,
+//     },
+//     "_id",
+//   ).lean();
+//   return monitors.map((monitor) => monitor._id);
 //
 // Returning the documents is the easy mistake, so it is rejected rather than
 // merely documented: the return is validated and a document-shaped entry
@@ -219,8 +321,14 @@ const validateResolvedSiteMonitorIds = (resolved) => {
 // Site has no array — and they are filtered out here rather than trusted to
 // the caller.
 //
-// Read the PRECONDITION and STALENESS notes at the top of this file before
-// writing the result to Users.subscribedMonitors.
+// Do NOT store this result. Read the "THIS IS A READ-TIME RESOLUTION" note at
+// the top of this file — a stored copy is where all five JA-3110 bugs came
+// from. Its privacy obligation applies here too: the ids this returns are only
+// as safe to alert on as the resolver that produced them.
+//
+// For a whole cohort of users, prefer resolveSubscribedMonitorIdsByUser
+// below — it does the Sites lookup once for the batch instead of once per
+// user.
 /**
  * @param {Array<{ deviceId: import("mongoose").Types.ObjectId,
  *   deviceType: import("../constants/deviceTypes.js").DeviceType }>} [subscribedDevices]
@@ -230,7 +338,7 @@ const validateResolvedSiteMonitorIds = (resolved) => {
  */
 export const projectSubscribedMonitors = async (
   subscribedDevices,
-  { resolveSiteMonitorIds } = {}
+  { resolveSiteMonitorIds } = {},
 ) => {
   const entries = (subscribedDevices ?? []).filter(isPlainObject);
   const direct = directMonitorIds(entries);
@@ -242,14 +350,153 @@ export const projectSubscribedMonitors = async (
 
   if (typeof resolveSiteMonitorIds !== "function") {
     const error = new TypeError(
-      "projectSubscribedMonitors requires resolveSiteMonitorIds when a linked-device is subscribed"
+      "projectSubscribedMonitors requires resolveSiteMonitorIds when a linked-device is subscribed",
     );
     error.code = SUBSCRIBED_DEVICES_ERRORS.MISSING_SITE_RESOLVER;
     throw error;
   }
 
   const siteMonitorIds = validateResolvedSiteMonitorIds(
-    await resolveSiteMonitorIds(siteIds)
+    await resolveSiteMonitorIds(siteIds),
   );
   return dedupeById([...direct, ...siteMonitorIds]);
 };
+
+// ---------------------------------------------------------------------------
+// Cohort-scoped resolution
+// ---------------------------------------------------------------------------
+// The batch form of the above, and the one every read-time consumer should
+// reach for: an alert run, an org admin page, a session response. Resolves a
+// whole list of users with ONE Sites lookup covering every Site anyone in the
+// cohort follows, rather than one lookup per user.
+//
+// That distinction is the difference between a constant-cost alert run and an
+// N+1 across the entire user base, which is the shape this codebase keeps
+// re-learning. The lookup is not performed at all when nobody in the cohort
+// follows a linked-device.
+//
+//   resolveVisibleSiteMonitors(siteIds) -> Map<string siteId, ObjectId[]>
+//
+// The resolver is keyed per Site rather than returning a flat union, because
+// each user needs their own Sites' monitors, not the cohort's. It must return
+// only VISIBLE monitors — see the privacy note at the top of this file, and
+// build it from VISIBLE_SITE_MONITOR_FILTER:
+//
+//   const sites = await Sites.find(
+//     { _id: { $in: siteIds } }, "monitorIds",
+//   ).lean();
+//   const monitors = await Monitors.find(
+//     {
+//       _id: { $in: sites.flatMap((s) => s.monitorIds ?? []) },
+//       ...VISIBLE_SITE_MONITOR_FILTER,
+//     },
+//     "_id",
+//   ).lean();
+//   const visible = new Set(monitors.map((m) => String(m._id)));
+//   return new Map(sites.map((s) => [
+//     String(s._id),
+//     (s.monitorIds ?? []).filter((id) => visible.has(String(id))),
+//   ]));
+//
+// A Site id the resolver omits resolves to no monitors for that user rather
+// than throwing — a followed Site that has since been deleted is an ordinary
+// state, not an error. What that user is left holding (an entry that resolves
+// to nothing, so their alerts stop) is the subscription-identity question
+// tracked in TODOS, and is deliberately not papered over here.
+//
+// Users are keyed by `String(user._id)`, so callers look up with the same.
+// Anything in the cohort that is not a user object carrying an `_id` — a
+// missing `_id`, a `null` slot, a bare id string — throws COHORT_USER_MISSING_ID
+// rather than being skipped. Skipping would silently remove a real person from
+// an alert audience, which is the failure mode this whole module exists to
+// avoid, and a caller cannot tell a dropped entry apart from one that resolved
+// to nothing.
+//
+// Consumers can shrink the cohort by pushing the AQI-capability predicate into
+// the Users query, so rows that can never alert are not loaded at all.
+// AQI_CAPABLE_DEVICE_TYPES is the query form of isAqiCapableDeviceType and is
+// exported from constants/deviceTypes.js (and the root barrel) for exactly
+// this:
+//
+//   import { AQI_CAPABLE_DEVICE_TYPES } from "@justair/justair-library";
+//
+//   { "subscribedDevices.deviceType": { $in: AQI_CAPABLE_DEVICE_TYPES } }
+//
+// There is no index on `subscribedDevices.deviceType` (only on
+// `subscribedDevices.deviceId`), so this narrows the documents returned rather
+// than the documents scanned — still worth it on a cohort query that is already
+// scanning, not worth building a JS-side filter for.
+/**
+ * @param {Array<{ _id: any, subscribedDevices?: Array<{
+ *   deviceId: import("mongoose").Types.ObjectId,
+ *   deviceType: import("../constants/deviceTypes.js").DeviceType }> }>} [users]
+ * @param {{ resolveVisibleSiteMonitors?: (siteIds: import("mongoose").Types.ObjectId[]) =>
+ *   Promise<Map<string, import("mongoose").Types.ObjectId[]>> }} [options]
+ * @returns {Promise<Map<string, import("mongoose").Types.ObjectId[]>>}
+ */
+export const resolveSubscribedMonitorIdsByUser = async (
+  users,
+  { resolveVisibleSiteMonitors } = {},
+) => {
+  const cohort = users ?? [];
+
+  // Every entry must be a user object carrying an _id, and anything else
+  // throws rather than being filtered out. A `null` slot used to be dropped by
+  // an isPlainObject filter and then never appear in the returned Map, which
+  // is the same silent removal from an alert audience that the missing-_id
+  // check below already rejects — a caller cannot tell "that user follows
+  // nothing" apart from "that user was quietly discarded". One rule for both:
+  // if the cohort contains something that is not a resolvable user, say so.
+  const invalid = cohort.some(
+    (user) =>
+      !isPlainObject(user) || user._id === null || user._id === undefined,
+  );
+  if (invalid) {
+    const error = new TypeError(
+      "resolveSubscribedMonitorIdsByUser requires every cohort entry to be a user object carrying an _id",
+    );
+    error.code = SUBSCRIBED_DEVICES_ERRORS.COHORT_USER_MISSING_ID;
+    throw error;
+  }
+
+  // Every Site anyone in the cohort follows, deduped across users — the point
+  // of the batch form. Two users following the same Site cost one entry.
+  const siteIds = dedupeById(
+    cohort.flatMap((user) =>
+      linkedSiteIds((user.subscribedDevices ?? []).filter(isPlainObject)),
+    ),
+  );
+
+  let monitorIdsBySite = new Map();
+  if (siteIds.length > 0) {
+    if (typeof resolveVisibleSiteMonitors !== "function") {
+      const error = new TypeError(
+        "resolveSubscribedMonitorIdsByUser requires resolveVisibleSiteMonitors when anyone in the cohort follows a linked-device",
+      );
+      error.code = SUBSCRIBED_DEVICES_ERRORS.MISSING_COHORT_SITE_RESOLVER;
+      throw error;
+    }
+    monitorIdsBySite = validateResolvedSiteMonitorMap(
+      await resolveVisibleSiteMonitors(siteIds),
+    );
+  }
+
+  // Synchronous and Map-backed, so the per-user projections below issue no
+  // further lookups no matter how large the cohort is. Per-entry validation
+  // (arrays, not nested arrays, ids rather than documents) is inherited from
+  // projectSubscribedMonitors rather than duplicated.
+  const resolveSiteMonitorIds = (ids) =>
+    ids.flatMap((id) => monitorIdsBySite.get(String(id)) ?? []);
+
+  const resolved = await Promise.all(
+    cohort.map((user) =>
+      projectSubscribedMonitors(user.subscribedDevices, {
+        resolveSiteMonitorIds,
+      }),
+    ),
+  );
+
+  return new Map(
+    cohort.map((user, index) => [String(user._id), resolved[index]]),
+  );
+};

package/src/utils/tests/subscribedDevices.test.js

@@ -6,6 +6,8 @@ import {
 } from '../../constants/deviceTypes.js';
 import {
   projectSubscribedMonitors,
+  resolveSubscribedMonitorIdsByUser,
+  VISIBLE_SITE_MONITOR_FILTER,
   SUBSCRIBED_DEVICES_ERRORS,
 } from '../subscribedDevices.js';
 
@@ -413,3 +415,285 @@ describe('isAqiCapableDeviceType agrees with the projection', () => {
     expect(projected.length > 0).toBe(isAqiCapableDeviceType(deviceType));
   });
 });
+
+// ---------------------------------------------------------------------------
+// resolveSubscribedMonitorIdsByUser — the cohort form
+// ---------------------------------------------------------------------------
+// The batch form exists for exactly two reasons, and both are asserted here
+// rather than just described: it must issue ONE Sites lookup for a whole
+// cohort (never one per user), and each user must get THEIR OWN Sites'
+// monitors, not the cohort's union. Get the second wrong and every follower of
+// any Site is enrolled in every other Site's alerts — a bug that looks like
+// working code on a one-user fixture.
+
+// Records what the cohort resolver was asked for, so the tests can assert the
+// call shape and not just the result.
+const recordingSiteMap = (byId) => {
+  const calls = [];
+  const resolve = async (siteIds) => {
+    calls.push(siteIds);
+    return new Map(siteIds.map((id) => [String(id), byId[String(id)] ?? []]));
+  };
+  return { resolve, calls };
+};
+
+const user = (subscribedDevices) => ({ _id: oid(), subscribedDevices });
+
+describe('resolveSubscribedMonitorIdsByUser', () => {
+  test('keys the result by String(user._id)', async () => {
+    const u = user([]);
+
+    const result = await resolveSubscribedMonitorIdsByUser([u]);
+
+    expect([...result.keys()]).toEqual([String(u._id)]);
+  });
+
+  test('a monitor-only cohort never touches the Sites resolver', async () => {
+    // The cheap path: a consumer whose users follow no Sites pays no lookup.
+    const { resolve, calls } = recordingSiteMap({});
+    const [m1, m2] = [oid(), oid()];
+    const [u1, u2] = [
+      user([{ deviceId: m1, deviceType: 'monitor' }]),
+      user([{ deviceId: m2, deviceType: 'monitor' }]),
+    ];
+
+    const result = await resolveSubscribedMonitorIdsByUser([u1, u2], {
+      resolveVisibleSiteMonitors: resolve,
+    });
+
+    expect(calls).toEqual([]);
+    expect(result.get(String(u1._id))).toEqual([m1]);
+    expect(result.get(String(u2._id))).toEqual([m2]);
+  });
+
+  test('issues exactly ONE resolver call for the whole cohort, deduped', async () => {
+    // Two users following the same Site must cost one entry, not two — this is
+    // the entire point of the batch form.
+    const [siteA, siteB] = [oid(), oid()];
+    const { resolve, calls } = recordingSiteMap({
+      [siteA]: [oid()],
+      [siteB]: [oid()],
+    });
+
+    await resolveSubscribedMonitorIdsByUser(
+      [
+        user([{ deviceId: siteA, deviceType: 'linked-device' }]),
+        user([{ deviceId: siteA, deviceType: 'linked-device' }]),
+        user([{ deviceId: siteB, deviceType: 'linked-device' }]),
+      ],
+      { resolveVisibleSiteMonitors: resolve },
+    );
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].map(String).sort()).toEqual(
+      [String(siteA), String(siteB)].sort(),
+    );
+  });
+
+  test('each user gets only THEIR sites monitors, never the cohort union', async () => {
+    const [siteA, siteB] = [oid(), oid()];
+    const [a1, b1] = [oid(), oid()];
+    const { resolve } = recordingSiteMap({ [siteA]: [a1], [siteB]: [b1] });
+    const [ua, ub] = [
+      user([{ deviceId: siteA, deviceType: 'linked-device' }]),
+      user([{ deviceId: siteB, deviceType: 'linked-device' }]),
+    ];
+
+    const result = await resolveSubscribedMonitorIdsByUser([ua, ub], {
+      resolveVisibleSiteMonitors: resolve,
+    });
+
+    expect(result.get(String(ua._id))).toEqual([a1]);
+    expect(result.get(String(ub._id))).toEqual([b1]);
+  });
+
+  test('dedupes a monitor followed both directly and through a Site', async () => {
+    const siteId = oid();
+    const shared = oid();
+    const { resolve } = recordingSiteMap({ [siteId]: [shared] });
+    const u = user([
+      { deviceId: shared, deviceType: 'monitor' },
+      { deviceId: siteId, deviceType: 'linked-device' },
+    ]);
+
+    const result = await resolveSubscribedMonitorIdsByUser([u], {
+      resolveVisibleSiteMonitors: resolve,
+    });
+
+    expect(result.get(String(u._id))).toEqual([shared]);
+  });
+
+  test('a sample-site follower resolves to no monitors', async () => {
+    const u = user([{ deviceId: oid(), deviceType: 'sample-site' }]);
+
+    const result = await resolveSubscribedMonitorIdsByUser([u]);
+
+    expect(result.get(String(u._id))).toEqual([]);
+  });
+
+  test('a Site the resolver omits resolves to nothing, not an error', async () => {
+    // A followed Site that has since been hard-deleted. Their alerts stopping
+    // is the subscription-identity question, not a crash in the resolver.
+    const deletedSite = oid();
+    const { resolve } = recordingSiteMap({});
+    const u = user([{ deviceId: deletedSite, deviceType: 'linked-device' }]);
+
+    const result = await resolveSubscribedMonitorIdsByUser([u], {
+      resolveVisibleSiteMonitors: resolve,
+    });
+
+    expect(result.get(String(u._id))).toEqual([]);
+  });
+
+  test('normalises ObjectId keys in the returned Map', async () => {
+    // The silent-miss trap: `new Map([[site._id, ids]])` type-checks, looks
+    // correct, and misses every lookup because two equal ObjectIds are
+    // different object identities. Forgiven here rather than failing quietly.
+    const siteId = oid();
+    const monitorId = oid();
+    const u = user([{ deviceId: siteId, deviceType: 'linked-device' }]);
+
+    const result = await resolveSubscribedMonitorIdsByUser([u], {
+      resolveVisibleSiteMonitors: async () => new Map([[siteId, [monitorId]]]),
+    });
+
+    expect(result.get(String(u._id))).toEqual([monitorId]);
+  });
+
+  test('tolerates a user with no subscribedDevices key at all', async () => {
+    const u = { _id: oid() };
+
+    const result = await resolveSubscribedMonitorIdsByUser([u]);
+
+    expect(result.get(String(u._id))).toEqual([]);
+  });
+
+  test('an empty or nullish cohort resolves to an empty Map', async () => {
+    expect(await resolveSubscribedMonitorIdsByUser([])).toEqual(new Map());
+    expect(await resolveSubscribedMonitorIdsByUser(undefined)).toEqual(new Map());
+  });
+});
+
+describe('resolveSubscribedMonitorIdsByUser — rejects what would otherwise fail silently', () => {
+  test('throws MISSING_COHORT_SITE_RESOLVER when anyone follows a linked-device', async () => {
+    await expect(
+      resolveSubscribedMonitorIdsByUser([
+        user([{ deviceId: oid(), deviceType: 'linked-device' }]),
+      ]),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.MISSING_COHORT_SITE_RESOLVER,
+    });
+  });
+
+  test('does NOT require a resolver when nobody follows a linked-device', async () => {
+    const monitorId = oid();
+    const u = user([{ deviceId: monitorId, deviceType: 'monitor' }]);
+
+    const result = await resolveSubscribedMonitorIdsByUser([u]);
+
+    expect(result.get(String(u._id))).toEqual([monitorId]);
+  });
+
+  test('throws COHORT_RESOLVER_RETURNED_NON_MAP for an array of entries', async () => {
+    // The natural mistake: returning `[[siteId, ids]]` instead of a Map.
+    const siteId = oid();
+
+    await expect(
+      resolveSubscribedMonitorIdsByUser(
+        [user([{ deviceId: siteId, deviceType: 'linked-device' }])],
+        { resolveVisibleSiteMonitors: async () => [[String(siteId), [oid()]]] },
+      ),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.COHORT_RESOLVER_RETURNED_NON_MAP,
+    });
+  });
+
+  test('a nullish resolver return is an empty audience, not a throw', async () => {
+    const u = user([{ deviceId: oid(), deviceType: 'linked-device' }]);
+
+    const result = await resolveSubscribedMonitorIdsByUser([u], {
+      resolveVisibleSiteMonitors: async () => null,
+    });
+
+    expect(result.get(String(u._id))).toEqual([]);
+  });
+
+  test('inherits the per-value guard: Site documents in a value are rejected', async () => {
+    // Same failure projectSubscribedMonitors guards against, reached through
+    // the Map. Left unchecked each doc casts to its own _id and Site ids land
+    // in the alert audience.
+    const siteId = oid();
+
+    await expect(
+      resolveSubscribedMonitorIdsByUser(
+        [user([{ deviceId: siteId, deviceType: 'linked-device' }])],
+        {
+          resolveVisibleSiteMonitors: async () =>
+            new Map([[String(siteId), [{ _id: oid(), monitorIds: [] }]]]),
+        },
+      ),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_DOCUMENTS,
+    });
+  });
+
+  test('throws COHORT_USER_MISSING_ID rather than silently dropping the user', async () => {
+    // Skipping would remove a real person from an alert audience with no error
+    // anywhere — the exact failure mode this module exists to prevent.
+    await expect(
+      resolveSubscribedMonitorIdsByUser([{ subscribedDevices: [] }]),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.COHORT_USER_MISSING_ID,
+    });
+  });
+
+  test.each([
+    ['a null slot', null],
+    ['an undefined slot', undefined],
+    ['a bare id string', 'deadbeefdeadbeefdeadbeef'],
+    ['an array', []],
+  ])('throws COHORT_USER_MISSING_ID for %s in the cohort', async (_label, entry) => {
+    // A non-object entry used to be filtered out and then simply never appear
+    // in the returned Map — the same silent removal the missing-_id case above
+    // rejects, and indistinguishable to the caller from "follows nothing".
+    await expect(
+      resolveSubscribedMonitorIdsByUser([user([]), entry]),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.COHORT_USER_MISSING_ID,
+    });
+  });
+});
+
+describe('VISIBLE_SITE_MONITOR_FILTER', () => {
+  test('privacy uses $ne, eligibility uses an exact match — deliberately', () => {
+    // The asymmetry is the point, and this test exists to stop it being
+    // "fixed". isPrivate is a privacy gate: $ne keeps a monitor that was never
+    // marked private, which its followers are entitled to see. isActive is an
+    // eligibility gate: a monitor earns a place in an alert audience only by
+    // positively asserting it is active, so a document that has made no such
+    // assertion stays out. Confirmed product decision — flipping either half
+    // is a behaviour change, not a cleanup.
+    expect(VISIBLE_SITE_MONITOR_FILTER).toEqual({
+      isPrivate: { $ne: true },
+      isActive: true,
+    });
+  });
+
+  test('is frozen all the way down — one consumer must not change it for the rest', () => {
+    // Object.freeze is shallow, so the top-level assertion alone would pass
+    // while `FILTER.isPrivate.$ne = false` still silently flipped the privacy
+    // predicate for every consumer that spreads this instance.
+    expect(Object.isFrozen(VISIBLE_SITE_MONITOR_FILTER)).toBe(true);
+    expect(Object.isFrozen(VISIBLE_SITE_MONITOR_FILTER.isPrivate)).toBe(true);
+  });
+
+  test('a nested write is rejected rather than shared with every consumer', () => {
+    // ES modules are strict, so a write to a frozen property throws rather
+    // than failing silently.
+    expect(() => {
+      VISIBLE_SITE_MONITOR_FILTER.isPrivate.$ne = false;
+    }).toThrow(TypeError);
+
+    expect(VISIBLE_SITE_MONITOR_FILTER.isPrivate.$ne).toBe(true);
+  });
+});

package/src/utils/tests/subscribedDevicesBarrel.test.js

@@ -9,18 +9,23 @@
 // deliberate contract change, not a test fix.
 import {
   projectSubscribedMonitors,
+  resolveSubscribedMonitorIdsByUser,
+  VISIBLE_SITE_MONITOR_FILTER,
   SUBSCRIBED_DEVICES_ERRORS,
 } from '../subscribedDevices.js';
 import {
   DEVICE_TYPES,
   DEVICE_TYPE_VALUES,
   isAqiCapableDeviceType,
+  AQI_CAPABLE_DEVICE_TYPES,
 } from '../../constants/deviceTypes.js';
 
 test('barrel re-exports the subscribedDevices surface unchanged (identity, not copies)', async () => {
   const barrel = await import('../../index.js');
 
   expect(barrel.projectSubscribedMonitors).toBe(projectSubscribedMonitors);
+  expect(barrel.resolveSubscribedMonitorIdsByUser).toBe(resolveSubscribedMonitorIdsByUser);
+  expect(barrel.VISIBLE_SITE_MONITOR_FILTER).toBe(VISIBLE_SITE_MONITOR_FILTER);
   expect(barrel.SUBSCRIBED_DEVICES_ERRORS).toBe(SUBSCRIBED_DEVICES_ERRORS);
 });
 
@@ -35,4 +40,5 @@ test('barrel re-exports the device-type vocabulary unchanged (identity, not copi
   expect(barrel.DEVICE_TYPES).toBe(DEVICE_TYPES);
   expect(barrel.DEVICE_TYPE_VALUES).toBe(DEVICE_TYPE_VALUES);
   expect(barrel.isAqiCapableDeviceType).toBe(isAqiCapableDeviceType);
+  expect(barrel.AQI_CAPABLE_DEVICE_TYPES).toBe(AQI_CAPABLE_DEVICE_TYPES);
 });