@justair/justair-library 7.5.0 → 7.6.0-alpha.4ff5aae

package/dist/index.d.ts

@@ -107,6 +107,8 @@ import { DEVICE_TYPES } from "./constants/deviceTypes.js";
 import { DEVICE_TYPE_VALUES } from "./constants/deviceTypes.js";
 import { isAqiCapableDeviceType } from "./constants/deviceTypes.js";
 import { projectSubscribedMonitors } from "./utils/subscribedDevices.js";
+import { resolveMonitorIdsByUser } 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 +120,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, projectSubscribedMonitors, resolveMonitorIdsByUser, 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":"AA+JA;;;iBAEC;yBA/FwB,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;4BA8CT,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;sCAlDtF,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;mCAiE3D,2BAA2B;8BAA3B,2BAA2B;gCAA3B,2BAA2B;mCAA3B,2BAA2B;+DAsB3B,mCAAmC;qCAAnC,mCAAmC;mEAAnC,mCAAmC;yEAAnC,mCAAmC;mEAAnC,mCAAmC;qEAAnC,mCAAmC;yEAAnC,mCAAmC;2EAAnC,mCAAmC;2BA1FD,2BAA2B;6BAA3B,2BAA2B;oCAChB,4BAA4B;+BAA5B,4BAA4B;6BAOzE,4BAA4B;mCAA5B,4BAA4B;uCAA5B,4BAA4B;0CAgC5B,8BAA8B;wCAA9B,8BAA8B;4CAA9B,8BAA8B;0CAA9B,8BAA8B;0BAhBX,sBAAsB;oCASzC,uBAAuB;iCA/BG,0BAA0B;mCA+BpD,uBAAuB;kCAAvB,uBAAuB;oCACM,qBAAqB;mCADlD,uBAAuB;+BAAvB,uBAAuB;gCAAvB,uBAAuB;kCAAvB,uBAAuB"}

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: {
+        $ne: boolean;
+    };
+    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 resolveMonitorIdsByUser(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":"AAmEA;;;;;;;;GASG;AAyBH;;;;;GAGG;AAiLI,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;AAkEM,gDAPI,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,CA2DrE"}

package/package.json

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

package/src/index.js

@@ -102,6 +102,8 @@ import {
 import { isValidIANATimezone } from "./utils/timezone.js";
 import {
   projectSubscribedMonitors,
+  resolveMonitorIdsByUser,
+  VISIBLE_SITE_MONITOR_FILTER,
   SUBSCRIBED_DEVICES_ERRORS,
 } from "./utils/subscribedDevices.js";
 
@@ -272,13 +274,26 @@ 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.
+  // 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.
+  //
+  //   resolveMonitorIdsByUser  — 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,
+  resolveMonitorIdsByUser,
+  VISIBLE_SITE_MONITOR_FILTER,
   SUBSCRIBED_DEVICES_ERRORS,
   // Utilities
   splitName,

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,56 @@
 //   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 — 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 +70,38 @@ 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",
+  // resolveMonitorIdsByUser 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();
+//
+// `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.
+export const VISIBLE_SITE_MONITOR_FILTER = Object.freeze({
+  isPrivate: { $ne: true },
+  isActive: true,
 });
 
 // Dedupe by string form, keep the caller's ObjectId instances. Two equal
@@ -189,6 +203,38 @@ const validateResolvedSiteMonitorIds = (resolved) => {
   return resolved;
 };
 
+// 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),
+    ])
+  );
+};
+
+
 // 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
@@ -219,8 +265,13 @@ 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 resolveMonitorIdsByUser 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]
@@ -253,3 +304,126 @@ export const projectSubscribedMonitors = async (
   );
   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. A
+// user with no `_id` throws 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.
+//
+// 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:
+//
+//   { "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 resolveMonitorIdsByUser = async (
+  users,
+  { resolveVisibleSiteMonitors } = {}
+) => {
+  const cohort = (users ?? []).filter(isPlainObject);
+
+  const missing = cohort.find(
+    (user) => user._id === null || user._id === undefined
+  );
+  if (missing) {
+    const error = new TypeError(
+      "resolveMonitorIdsByUser requires every user to carry 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(
+        "resolveMonitorIdsByUser 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,
+  resolveMonitorIdsByUser,
+  VISIBLE_SITE_MONITOR_FILTER,
   SUBSCRIBED_DEVICES_ERRORS,
 } from '../subscribedDevices.js';
 
@@ -413,3 +415,251 @@ describe('isAqiCapableDeviceType agrees with the projection', () => {
     expect(projected.length > 0).toBe(isAqiCapableDeviceType(deviceType));
   });
 });
+
+// ---------------------------------------------------------------------------
+// resolveMonitorIdsByUser — 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('resolveMonitorIdsByUser', () => {
+  test('keys the result by String(user._id)', async () => {
+    const u = user([]);
+
+    const result = await resolveMonitorIdsByUser([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 resolveMonitorIdsByUser([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 resolveMonitorIdsByUser(
+      [
+        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 resolveMonitorIdsByUser([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 resolveMonitorIdsByUser([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 resolveMonitorIdsByUser([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 resolveMonitorIdsByUser([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 resolveMonitorIdsByUser([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 resolveMonitorIdsByUser([u]);
+
+    expect(result.get(String(u._id))).toEqual([]);
+  });
+
+  test('an empty or nullish cohort resolves to an empty Map', async () => {
+    expect(await resolveMonitorIdsByUser([])).toEqual(new Map());
+    expect(await resolveMonitorIdsByUser(undefined)).toEqual(new Map());
+  });
+});
+
+describe('resolveMonitorIdsByUser — rejects what would otherwise fail silently', () => {
+  test('throws MISSING_COHORT_SITE_RESOLVER when anyone follows a linked-device', async () => {
+    await expect(
+      resolveMonitorIdsByUser([
+        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 resolveMonitorIdsByUser([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(
+      resolveMonitorIdsByUser(
+        [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 resolveMonitorIdsByUser([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(
+      resolveMonitorIdsByUser(
+        [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(
+      resolveMonitorIdsByUser([{ subscribedDevices: [] }]),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.COHORT_USER_MISSING_ID,
+    });
+  });
+});
+
+describe('VISIBLE_SITE_MONITOR_FILTER', () => {
+  test('excludes private monitors with $ne: true, not an exact false match', () => {
+    // $ne matches both `false` and a MISSING key. Documents written before
+    // isPrivate existed carry no key, and an exact { isPrivate: false } match
+    // would drop them from every Site's audience.
+    expect(VISIBLE_SITE_MONITOR_FILTER).toEqual({
+      isPrivate: { $ne: true },
+      isActive: true,
+    });
+  });
+
+  test('is frozen — one consumer mutating it must not change it for the rest', () => {
+    expect(Object.isFrozen(VISIBLE_SITE_MONITOR_FILTER)).toBe(true);
+  });
+});

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

@@ -9,6 +9,8 @@
 // deliberate contract change, not a test fix.
 import {
   projectSubscribedMonitors,
+  resolveMonitorIdsByUser,
+  VISIBLE_SITE_MONITOR_FILTER,
   SUBSCRIBED_DEVICES_ERRORS,
 } from '../subscribedDevices.js';
 import {
@@ -21,6 +23,8 @@ test('barrel re-exports the subscribedDevices surface unchanged (identity, not c
   const barrel = await import('../../index.js');
 
   expect(barrel.projectSubscribedMonitors).toBe(projectSubscribedMonitors);
+  expect(barrel.resolveMonitorIdsByUser).toBe(resolveMonitorIdsByUser);
+  expect(barrel.VISIBLE_SITE_MONITOR_FILTER).toBe(VISIBLE_SITE_MONITOR_FILTER);
   expect(barrel.SUBSCRIBED_DEVICES_ERRORS).toBe(SUBSCRIBED_DEVICES_ERRORS);
 });