@mentra/engine 3.4.0-dev.1207 → 3.4.0-dev.1209

package/build/services/fleet/fleetEvents.d.ts

@@ -15,9 +15,14 @@
  * the engine restores miniapps while the account it collects for may still be being resolved, and those launches are
  * that account's. The reporter discards them when the account changes. Photo stages are not kept.
  *
+ * Phase 12 adds a miniapp's own events (`telemetry`, from `session.telemetry.capture`, attributed by the runtime to the
+ * package whose bridge sent it), its crashes, install attempts, and the glasses' pairing and connection changes. None of
+ * these is kept while nothing listens: with no run collecting (Fleet not installed on the phone's Core, nobody signed
+ * in) they are dropped, and telemetry dropped this way is not counted.
+ *
  * This module imports nothing at run time, so the hot paths that import it carry no Fleet weight.
  */
-import type { FleetRecord } from "@mentra/cloud-protocol";
+import type { FleetConnectionEventPayload, FleetLaunchFailureReason, FleetMiniappCrashPayload, FleetMiniappInstallPayload, FleetRecord } from "@mentra/cloud-protocol";
 /** A miniapp start the engine attempted, and how it went. */
 export type FleetLaunchEvent = Extract<FleetRecord, {
     kind: "miniapp_launch";
@@ -36,9 +41,25 @@ export interface UndeliveredLaunch {
     event: FleetLaunchEvent;
     observedAt: number;
 }
+/** A miniapp's own event as the bridge delivered it: unchecked, the collector applies the limits. */
+export interface FleetTelemetryEvent {
+    packageName: string;
+    versionName?: string;
+    event: unknown;
+    properties: unknown;
+}
+/** A crash: the collector adds the miniapp's execution session. */
+export type FleetCrashEvent = Omit<FleetMiniappCrashPayload, "executionSessionId">;
+export type FleetInstallEvent = FleetMiniappInstallPayload;
+/** A pairing or connection change: the collector adds the glasses, their model and the Mentra App's version. */
+export type FleetConnectionEvent = Pick<FleetConnectionEventPayload, "event" | "category" | "reconnectMs">;
 export interface FleetEventListener {
     launch?: (event: FleetLaunchEvent) => void;
     photo?: (event: FleetPhotoEvent) => void;
+    telemetry?: (event: FleetTelemetryEvent) => void;
+    crash?: (event: FleetCrashEvent) => void;
+    install?: (event: FleetInstallEvent) => void;
+    connection?: (event: FleetConnectionEvent) => void;
 }
 export declare const fleetEvents: {
     /** Listens for events until the returned function is called. */
@@ -50,13 +71,28 @@ export declare const fleetEvents: {
      * same miniapp is under way, which reports it. Never throws.
      */
     launchUnlessClaimed(event: FleetLaunchEvent): void;
-    /** A start of `packageName` that reports its own launch is under way, until the returned function is called. */
-    claimLaunch(packageName: string): () => void;
+    /**
+     * A start of `packageName` that reports its own launch is under way, until the returned function is called. That
+     * function returns why a spawn the start held back failed, for the start's own report, or undefined.
+     */
+    claimLaunch(packageName: string): () => FleetLaunchFailureReason | undefined;
     /** The launches heard while nothing listened, oldest first; they are forgotten here. */
     takeUndeliveredLaunches(): UndeliveredLaunch[];
     /** Forgets the launches heard while nothing listened: they are no one's to report now. */
     discardUndeliveredLaunches(): void;
     /** A photo operation reached a stage. Never throws. */
     photo(event: FleetPhotoEvent): void;
+    /** A miniapp captured one of its own events. Never throws. */
+    telemetry(event: FleetTelemetryEvent): void;
+    /** A miniapp crashed. Never throws. */
+    crash(event: FleetCrashEvent): void;
+    /** An install, update or removal of a miniapp was attempted. Never throws. */
+    install(event: FleetInstallEvent): void;
+    /** The person asked the glasses to disconnect (or forgot or unpaired them): the next disconnect is theirs. */
+    userDisconnect(): void;
+    /** When the person last asked the glasses to disconnect (epoch ms), or 0. */
+    lastUserDisconnect(): number;
+    /** The glasses' pairing or connection changed. Never throws. */
+    connection(event: FleetConnectionEvent): void;
 };
 //# sourceMappingURL=fleetEvents.d.ts.map

package/build/services/fleet/fleetEvents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fleetEvents.d.ts","sourceRoot":"","sources":["../../../src/services/fleet/fleetEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,wBAAwB,CAAA;AAEvD,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,WAAW,EAAE;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;AAExF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,GAAG,OAAO,CAAC,WAAW,EAAE;IAAC,IAAI,EAAE,iBAAiB,CAAA;CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;AAEhH,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,gBAAgB,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAA;IAC1C,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;CACzC;AA8BD,eAAO,MAAM,WAAW;IACtB,gEAAgE;wBAC5C,kBAAkB,GAAG,MAAM,IAAI;IAOnD,mDAAmD;kBACrC,gBAAgB,GAAG,IAAI;IAIrC;;;OAGG;+BACwB,gBAAgB,GAAG,IAAI;IAKlD,gHAAgH;6BACvF,MAAM,GAAG,MAAM,IAAI;IAY5C,wFAAwF;+BAC7D,iBAAiB,EAAE;IAI9C,0FAA0F;kCAC5D,IAAI;IAIlC,uDAAuD;iBAC1C,eAAe,GAAG,IAAI;CAUpC,CAAA"}
+{"version":3,"file":"fleetEvents.d.ts","sourceRoot":"","sources":["../../../src/services/fleet/fleetEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EACV,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,0BAA0B,EAC1B,WAAW,EACZ,MAAM,wBAAwB,CAAA;AAE/B,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,WAAW,EAAE;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;AAExF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,GAAG,OAAO,CAAC,WAAW,EAAE;IAAC,IAAI,EAAE,iBAAiB,CAAA;CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;AAEhH,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,gBAAgB,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,qGAAqG;AACrG,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,OAAO,CAAA;IACd,UAAU,EAAE,OAAO,CAAA;CACpB;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,wBAAwB,EAAE,oBAAoB,CAAC,CAAA;AAClF,MAAM,MAAM,iBAAiB,GAAG,0BAA0B,CAAA;AAC1D,gHAAgH;AAChH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,2BAA2B,EAAE,OAAO,GAAG,UAAU,GAAG,aAAa,CAAC,CAAA;AAE1G,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAA;IAC1C,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAA;IAChD,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;IAC5C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;CACnD;AAoCD,eAAO,MAAM,WAAW;IACtB,gEAAgE;wBAC5C,kBAAkB,GAAG,MAAM,IAAI;IAOnD,mDAAmD;kBACrC,gBAAgB,GAAG,IAAI;IAIrC;;;OAGG;+BACwB,gBAAgB,GAAG,IAAI;IAYlD;;;OAGG;6BACsB,MAAM,GAAG,MAAM,wBAAwB,GAAG,SAAS;IAgB5E,wFAAwF;+BAC7D,iBAAiB,EAAE;IAI9C,0FAA0F;kCAC5D,IAAI;IAIlC,uDAAuD;iBAC1C,eAAe,GAAG,IAAI;IAInC,8DAA8D;qBAC7C,mBAAmB,GAAG,IAAI;IAI3C,uCAAuC;iBAC1B,eAAe,GAAG,IAAI;IAInC,8EAA8E;mBAC/D,iBAAiB,GAAG,IAAI;IAIvC,8GAA8G;sBAC5F,IAAI;IAItB,6EAA6E;0BACvD,MAAM;IAI5B,gEAAgE;sBAC9C,oBAAoB,GAAG,IAAI;CAG9C,CAAA"}

package/build/services/fleet/fleetEvents.js

@@ -1,6 +1,7 @@
 /** More launches than this before the collector starts are not one boot's restores; the oldest go first. */
 const MAX_UNDELIVERED_LAUNCHES = 32;
 const listeners = new Set();
+let lastUserDisconnectAt = 0;
 const undelivered = [];
 /** Starts under way that report their own launch, by package. */
 const claims = new Map();
@@ -41,23 +42,37 @@ export const fleetEvents = {
      * same miniapp is under way, which reports it. Never throws.
      */
     launchUnlessClaimed(event) {
-        if ((claims.get(event.packageName) ?? 0) > 0)
+        const held = claims.get(event.packageName);
+        if (!held) {
+            deliverLaunch(event);
             return;
-        deliverLaunch(event);
+        }
+        // The start reports this attempt as its own, so it keeps the reason the spawn failed for.
+        const reason = event.failureReason;
+        if (reason === undefined)
+            return;
+        for (const claim of held)
+            if (claim.failureReason === undefined || claim.failureReason === "unknown")
+                claim.failureReason = reason;
     },
-    /** A start of `packageName` that reports its own launch is under way, until the returned function is called. */
+    /**
+     * A start of `packageName` that reports its own launch is under way, until the returned function is called. That
+     * function returns why a spawn the start held back failed, for the start's own report, or undefined.
+     */
     claimLaunch(packageName) {
-        claims.set(packageName, (claims.get(packageName) ?? 0) + 1);
+        const claim = {};
+        const held = claims.get(packageName) ?? new Set();
+        held.add(claim);
+        claims.set(packageName, held);
         let released = false;
         return () => {
-            if (released)
-                return;
-            released = true;
-            const left = (claims.get(packageName) ?? 1) - 1;
-            if (left > 0)
-                claims.set(packageName, left);
-            else
-                claims.delete(packageName);
+            if (!released) {
+                released = true;
+                held.delete(claim);
+                if (held.size === 0 && claims.get(packageName) === held)
+                    claims.delete(packageName);
+            }
+            return claim.failureReason;
         };
     },
     /** The launches heard while nothing listened, oldest first; they are forgotten here. */
@@ -70,16 +85,45 @@ export const fleetEvents = {
     },
     /** A photo operation reached a stage. Never throws. */
     photo(event) {
-        if (listeners.size === 0)
-            return;
-        for (const listener of [...listeners]) {
-            try {
-                listener.photo?.(event);
-            }
-            catch (error) {
-                warnListenerFailed(error);
-            }
-        }
+        deliver("photo", event);
+    },
+    /** A miniapp captured one of its own events. Never throws. */
+    telemetry(event) {
+        deliver("telemetry", event);
+    },
+    /** A miniapp crashed. Never throws. */
+    crash(event) {
+        deliver("crash", event);
+    },
+    /** An install, update or removal of a miniapp was attempted. Never throws. */
+    install(event) {
+        deliver("install", event);
+    },
+    /** The person asked the glasses to disconnect (or forgot or unpaired them): the next disconnect is theirs. */
+    userDisconnect() {
+        lastUserDisconnectAt = Date.now();
+    },
+    /** When the person last asked the glasses to disconnect (epoch ms), or 0. */
+    lastUserDisconnect() {
+        return lastUserDisconnectAt;
+    },
+    /** The glasses' pairing or connection changed. Never throws. */
+    connection(event) {
+        deliver("connection", event);
     },
 };
+/** Hands `event` to every listener of `kind`; with none, it is dropped. */
+function deliver(kind, event) {
+    if (listeners.size === 0)
+        return;
+    for (const listener of [...listeners]) {
+        try {
+            ;
+            listener[kind]?.(event);
+        }
+        catch (error) {
+            warnListenerFailed(error);
+        }
+    }
+}
 //# sourceMappingURL=fleetEvents.js.map

package/build/services/fleet/fleetEvents.js.map

@@ -1 +1 @@
-{"version":3,"file":"fleetEvents.js","sourceRoot":"","sources":["../../../src/services/fleet/fleetEvents.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The seam between the engine's lifecycle hooks and the Fleet reporter.\n *\n * Hooks in the miniapp, photo and pairing paths call `fleetEvents.launch` and `fleetEvents.photo`. With a reporter\n * running, the collector hears the event on the caller's own stack, so a listener must be cheap, and an emit never\n * throws into the caller: a listener that fails is logged by name and skipped. A hook can therefore never break or\n * slow the path it sits in.\n *\n * Every start of a miniapp is one launch. The apps store's `start` reports its own, and claims the miniapp while it\n * runs (`claimLaunch`); every other path that starts one (the launcher, for restores, miniapps started by other\n * miniapps and screens opened directly; built-ins restored running) reports through `launchUnlessClaimed`, so a spawn\n * a `start` causes elsewhere is not a second launch.\n *\n * A launch heard while nothing listens is kept, with the time it happened, for the collector to take when it starts:\n * the engine restores miniapps while the account it collects for may still be being resolved, and those launches are\n * that account's. The reporter discards them when the account changes. Photo stages are not kept.\n *\n * This module imports nothing at run time, so the hot paths that import it carry no Fleet weight.\n */\nimport type {FleetRecord} from \"@mentra/cloud-protocol\"\n\n/** A miniapp start the engine attempted, and how it went. */\nexport type FleetLaunchEvent = Extract<FleetRecord, {kind: \"miniapp_launch\"}>[\"payload\"]\n\n/**\n * One stage of a photo operation. `operationId` is the managed photo request ID, shared by every stage of the one\n * photo. `failedStage` is the last stage the operation reached before it failed.\n */\nexport type FleetPhotoEvent = {operationId: string} & Extract<FleetRecord, {kind: \"photo_operation\"}>[\"payload\"]\n\n/** A launch heard while nothing listened, and when it happened (epoch milliseconds). */\nexport interface UndeliveredLaunch {\n  event: FleetLaunchEvent\n  observedAt: number\n}\n\nexport interface FleetEventListener {\n  launch?: (event: FleetLaunchEvent) => void\n  photo?: (event: FleetPhotoEvent) => void\n}\n\n/** More launches than this before the collector starts are not one boot's restores; the oldest go first. */\nconst MAX_UNDELIVERED_LAUNCHES = 32\n\nconst listeners = new Set<FleetEventListener>()\nconst undelivered: UndeliveredLaunch[] = []\n/** Starts under way that report their own launch, by package. */\nconst claims = new Map<string, number>()\n\nfunction warnListenerFailed(error: unknown): void {\n  // The event is left out of the warning: it names a package or an operation.\n  console.warn(\"fleetEvents: a listener failed:\", error instanceof Error ? error.message : \"unknown error\")\n}\n\nfunction deliverLaunch(event: FleetLaunchEvent): void {\n  if (listeners.size === 0) {\n    undelivered.push({event, observedAt: Date.now()})\n    if (undelivered.length > MAX_UNDELIVERED_LAUNCHES) undelivered.shift()\n    return\n  }\n  for (const listener of [...listeners]) {\n    try {\n      listener.launch?.(event)\n    } catch (error) {\n      warnListenerFailed(error)\n    }\n  }\n}\n\nexport const fleetEvents = {\n  /** Listens for events until the returned function is called. */\n  subscribe(listener: FleetEventListener): () => void {\n    listeners.add(listener)\n    return () => {\n      listeners.delete(listener)\n    }\n  },\n\n  /** A miniapp start was attempted. Never throws. */\n  launch(event: FleetLaunchEvent): void {\n    deliverLaunch(event)\n  },\n\n  /**\n   * A miniapp start was attempted somewhere other than the apps store's `start`: reported unless a `start` of the\n   * same miniapp is under way, which reports it. Never throws.\n   */\n  launchUnlessClaimed(event: FleetLaunchEvent): void {\n    if ((claims.get(event.packageName) ?? 0) > 0) return\n    deliverLaunch(event)\n  },\n\n  /** A start of `packageName` that reports its own launch is under way, until the returned function is called. */\n  claimLaunch(packageName: string): () => void {\n    claims.set(packageName, (claims.get(packageName) ?? 0) + 1)\n    let released = false\n    return () => {\n      if (released) return\n      released = true\n      const left = (claims.get(packageName) ?? 1) - 1\n      if (left > 0) claims.set(packageName, left)\n      else claims.delete(packageName)\n    }\n  },\n\n  /** The launches heard while nothing listened, oldest first; they are forgotten here. */\n  takeUndeliveredLaunches(): UndeliveredLaunch[] {\n    return undelivered.splice(0)\n  },\n\n  /** Forgets the launches heard while nothing listened: they are no one's to report now. */\n  discardUndeliveredLaunches(): void {\n    undelivered.length = 0\n  },\n\n  /** A photo operation reached a stage. Never throws. */\n  photo(event: FleetPhotoEvent): void {\n    if (listeners.size === 0) return\n    for (const listener of [...listeners]) {\n      try {\n        listener.photo?.(event)\n      } catch (error) {\n        warnListenerFailed(error)\n      }\n    }\n  },\n}\n"]}
+{"version":3,"file":"fleetEvents.js","sourceRoot":"","sources":["../../../src/services/fleet/fleetEvents.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The seam between the engine's lifecycle hooks and the Fleet reporter.\n *\n * Hooks in the miniapp, photo and pairing paths call `fleetEvents.launch` and `fleetEvents.photo`. With a reporter\n * running, the collector hears the event on the caller's own stack, so a listener must be cheap, and an emit never\n * throws into the caller: a listener that fails is logged by name and skipped. A hook can therefore never break or\n * slow the path it sits in.\n *\n * Every start of a miniapp is one launch. The apps store's `start` reports its own, and claims the miniapp while it\n * runs (`claimLaunch`); every other path that starts one (the launcher, for restores, miniapps started by other\n * miniapps and screens opened directly; built-ins restored running) reports through `launchUnlessClaimed`, so a spawn\n * a `start` causes elsewhere is not a second launch.\n *\n * A launch heard while nothing listens is kept, with the time it happened, for the collector to take when it starts:\n * the engine restores miniapps while the account it collects for may still be being resolved, and those launches are\n * that account's. The reporter discards them when the account changes. Photo stages are not kept.\n *\n * Phase 12 adds a miniapp's own events (`telemetry`, from `session.telemetry.capture`, attributed by the runtime to the\n * package whose bridge sent it), its crashes, install attempts, and the glasses' pairing and connection changes. None of\n * these is kept while nothing listens: with no run collecting (Fleet not installed on the phone's Core, nobody signed\n * in) they are dropped, and telemetry dropped this way is not counted.\n *\n * This module imports nothing at run time, so the hot paths that import it carry no Fleet weight.\n */\nimport type {\n  FleetConnectionEventPayload,\n  FleetLaunchFailureReason,\n  FleetMiniappCrashPayload,\n  FleetMiniappInstallPayload,\n  FleetRecord,\n} from \"@mentra/cloud-protocol\"\n\n/** A miniapp start the engine attempted, and how it went. */\nexport type FleetLaunchEvent = Extract<FleetRecord, {kind: \"miniapp_launch\"}>[\"payload\"]\n\n/**\n * One stage of a photo operation. `operationId` is the managed photo request ID, shared by every stage of the one\n * photo. `failedStage` is the last stage the operation reached before it failed.\n */\nexport type FleetPhotoEvent = {operationId: string} & Extract<FleetRecord, {kind: \"photo_operation\"}>[\"payload\"]\n\n/** A launch heard while nothing listened, and when it happened (epoch milliseconds). */\nexport interface UndeliveredLaunch {\n  event: FleetLaunchEvent\n  observedAt: number\n}\n\n/** A miniapp's own event as the bridge delivered it: unchecked, the collector applies the limits. */\nexport interface FleetTelemetryEvent {\n  packageName: string\n  versionName?: string\n  event: unknown\n  properties: unknown\n}\n\n/** A crash: the collector adds the miniapp's execution session. */\nexport type FleetCrashEvent = Omit<FleetMiniappCrashPayload, \"executionSessionId\">\nexport type FleetInstallEvent = FleetMiniappInstallPayload\n/** A pairing or connection change: the collector adds the glasses, their model and the Mentra App's version. */\nexport type FleetConnectionEvent = Pick<FleetConnectionEventPayload, \"event\" | \"category\" | \"reconnectMs\">\n\nexport interface FleetEventListener {\n  launch?: (event: FleetLaunchEvent) => void\n  photo?: (event: FleetPhotoEvent) => void\n  telemetry?: (event: FleetTelemetryEvent) => void\n  crash?: (event: FleetCrashEvent) => void\n  install?: (event: FleetInstallEvent) => void\n  connection?: (event: FleetConnectionEvent) => void\n}\n\n/** More launches than this before the collector starts are not one boot's restores; the oldest go first. */\nconst MAX_UNDELIVERED_LAUNCHES = 32\n\nconst listeners = new Set<FleetEventListener>()\nlet lastUserDisconnectAt = 0\nconst undelivered: UndeliveredLaunch[] = []\n/** A start under way that reports its own launch: why a spawn it held back failed, if one did. */\ninterface LaunchClaim {\n  failureReason?: FleetLaunchFailureReason\n}\n\n/** Starts under way that report their own launch, by package. */\nconst claims = new Map<string, Set<LaunchClaim>>()\n\nfunction warnListenerFailed(error: unknown): void {\n  // The event is left out of the warning: it names a package or an operation.\n  console.warn(\"fleetEvents: a listener failed:\", error instanceof Error ? error.message : \"unknown error\")\n}\n\nfunction deliverLaunch(event: FleetLaunchEvent): void {\n  if (listeners.size === 0) {\n    undelivered.push({event, observedAt: Date.now()})\n    if (undelivered.length > MAX_UNDELIVERED_LAUNCHES) undelivered.shift()\n    return\n  }\n  for (const listener of [...listeners]) {\n    try {\n      listener.launch?.(event)\n    } catch (error) {\n      warnListenerFailed(error)\n    }\n  }\n}\n\nexport const fleetEvents = {\n  /** Listens for events until the returned function is called. */\n  subscribe(listener: FleetEventListener): () => void {\n    listeners.add(listener)\n    return () => {\n      listeners.delete(listener)\n    }\n  },\n\n  /** A miniapp start was attempted. Never throws. */\n  launch(event: FleetLaunchEvent): void {\n    deliverLaunch(event)\n  },\n\n  /**\n   * A miniapp start was attempted somewhere other than the apps store's `start`: reported unless a `start` of the\n   * same miniapp is under way, which reports it. Never throws.\n   */\n  launchUnlessClaimed(event: FleetLaunchEvent): void {\n    const held = claims.get(event.packageName)\n    if (!held) {\n      deliverLaunch(event)\n      return\n    }\n    // The start reports this attempt as its own, so it keeps the reason the spawn failed for.\n    const reason = event.failureReason\n    if (reason === undefined) return\n    for (const claim of held) if (claim.failureReason === undefined || claim.failureReason === \"unknown\") claim.failureReason = reason\n  },\n\n  /**\n   * A start of `packageName` that reports its own launch is under way, until the returned function is called. That\n   * function returns why a spawn the start held back failed, for the start's own report, or undefined.\n   */\n  claimLaunch(packageName: string): () => FleetLaunchFailureReason | undefined {\n    const claim: LaunchClaim = {}\n    const held = claims.get(packageName) ?? new Set<LaunchClaim>()\n    held.add(claim)\n    claims.set(packageName, held)\n    let released = false\n    return () => {\n      if (!released) {\n        released = true\n        held.delete(claim)\n        if (held.size === 0 && claims.get(packageName) === held) claims.delete(packageName)\n      }\n      return claim.failureReason\n    }\n  },\n\n  /** The launches heard while nothing listened, oldest first; they are forgotten here. */\n  takeUndeliveredLaunches(): UndeliveredLaunch[] {\n    return undelivered.splice(0)\n  },\n\n  /** Forgets the launches heard while nothing listened: they are no one's to report now. */\n  discardUndeliveredLaunches(): void {\n    undelivered.length = 0\n  },\n\n  /** A photo operation reached a stage. Never throws. */\n  photo(event: FleetPhotoEvent): void {\n    deliver(\"photo\", event)\n  },\n\n  /** A miniapp captured one of its own events. Never throws. */\n  telemetry(event: FleetTelemetryEvent): void {\n    deliver(\"telemetry\", event)\n  },\n\n  /** A miniapp crashed. Never throws. */\n  crash(event: FleetCrashEvent): void {\n    deliver(\"crash\", event)\n  },\n\n  /** An install, update or removal of a miniapp was attempted. Never throws. */\n  install(event: FleetInstallEvent): void {\n    deliver(\"install\", event)\n  },\n\n  /** The person asked the glasses to disconnect (or forgot or unpaired them): the next disconnect is theirs. */\n  userDisconnect(): void {\n    lastUserDisconnectAt = Date.now()\n  },\n\n  /** When the person last asked the glasses to disconnect (epoch ms), or 0. */\n  lastUserDisconnect(): number {\n    return lastUserDisconnectAt\n  },\n\n  /** The glasses' pairing or connection changed. Never throws. */\n  connection(event: FleetConnectionEvent): void {\n    deliver(\"connection\", event)\n  },\n}\n\n/** Hands `event` to every listener of `kind`; with none, it is dropped. */\nfunction deliver<K extends \"photo\" | \"telemetry\" | \"crash\" | \"install\" | \"connection\">(kind: K, event: Parameters<NonNullable<FleetEventListener[K]>>[0]): void {\n  if (listeners.size === 0) return\n  for (const listener of [...listeners]) {\n    try {\n      ;(listener[kind] as ((value: typeof event) => void) | undefined)?.(event)\n    } catch (error) {\n      warnListenerFailed(error)\n    }\n  }\n}\n"]}

package/build/services/fleet/fleetQueue.d.ts

@@ -13,6 +13,13 @@
  *   sequence and the oldest and newest record keys.
  * - `l:<partition>` holds the losses not yet reported: `{dropped, expired, from, to, updatedAt}`.
  * - `n:<partition>` holds the collector-session sequence counters, as `[collectorSessionId, next][]`.
+ * - `t:<partition>` holds the miniapp telemetry lost and not yet reported, per package (`FleetTelemetryLosses`).
+ *
+ * Telemetry (Phase 12) has a share of the queue: a `telemetry_event`'s record ID starts with `tel.`, so its key says
+ * what it is. Telemetry takes at most 2,000 of the 10,000 places. When that share or the queue is full, the oldest
+ * telemetry record gives way, and a record of any other kind never does to telemetry: an arriving record that finds
+ * the queue full evicts the oldest telemetry before anything else. Telemetry that is evicted, expires, or that MFM
+ * rejects is counted per package under `t:`, never as a coverage gap, and the reporter sends it as `telemetry_loss`.
  *
  * MMKV can list keys only by listing all of them, so the first call for a partition in a process scans the store
  * once, repairs the index if a crash left it behind, and keeps the partition's ordered record keys in memory.
@@ -48,6 +55,21 @@ export interface FleetLosses {
     /** The latest `observedAt` among the lost records, or null if none had a readable one. */
     to: string | null;
 }
+/** The telemetry the queue (or the Mentra App's limits) lost, per package, since the last `takeTelemetryLosses`. */
+export interface FleetTelemetryLosses {
+    packages: Record<string, {
+        overLimit: number;
+        evicted: number;
+        expired: number;
+        rejected: number;
+    }>;
+    from: string | null;
+    to: string | null;
+}
+export type FleetTelemetryLossKind = "overLimit" | "evicted" | "expired" | "rejected";
+/** A telemetry record's ID starts with this, so the queue tells telemetry from the rest by its key. */
+export declare const TELEMETRY_RECORD_PREFIX = "tel.";
+export declare const isTelemetryRecordId: (recordId: string) => boolean;
 /** A partition is one account on one Core. */
 export interface FleetQueue {
     /** Adds a record. Drops the oldest beyond 10,000 and counts the drop. Never throws: a record that cannot be stored is counted as dropped. */
@@ -80,6 +102,10 @@ export interface FleetQueue {
      * an idle reporter does not wake to sweep). `now` defaults to the queue's clock.
      */
     sweepExpired(now?: number): void;
+    /** Counts `count` of `packageName`'s telemetry as lost, as of `at` (epoch ms). Never throws. */
+    noteTelemetryLoss(partition: string, packageName: string, kind: FleetTelemetryLossKind, count: number, at?: number): void;
+    /** The telemetry lost since the last call, per package, and resets the counters; `null` when nothing was lost. */
+    takeTelemetryLosses(partition: string, now: number): FleetTelemetryLosses | null;
     /** Forgets everything held for the partition: records, losses and sequence counters. */
     clearPartition(partition: string): void;
     size(partition: string): number;

package/build/services/fleet/fleetQueue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fleetQueue.d.ts","sourceRoot":"","sources":["../../../src/services/fleet/fleetQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAe,KAAK,WAAW,EAAC,MAAM,wBAAwB,CAAA;AAKrE,wGAAwG;AACxG,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IAC1C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,UAAU,IAAI,MAAM,EAAE,CAAA;CACvB;AAED,mGAAmG;AACnG,MAAM,WAAW,WAAW;IAC1B,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAA;IACf,4FAA4F;IAC5F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,0FAA0F;IAC1F,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;CAClB;AAED,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,6IAA6I;IAC7I,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IACrD;;;;;;OAMG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CAAA;IACjF,+EAA+E;IAC/E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IACpD;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAAA;IACvD;;;;;;;;;;OAUG;IACH,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,wFAAwF;IACxF,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;IAC/B,0FAA0F;IAC1F,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAAA;CACpE;AAED,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAWD,oGAAoG;AACpG,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAI1E;AAwbD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,kBAAkB,EAAE,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAGxG"}
+{"version":3,"file":"fleetQueue.d.ts","sourceRoot":"","sources":["../../../src/services/fleet/fleetQueue.ts"],"names":[],"mappings":"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"}

package/build/services/fleet/fleetQueue.js

@@ -13,6 +13,13 @@
  *   sequence and the oldest and newest record keys.
  * - `l:<partition>` holds the losses not yet reported: `{dropped, expired, from, to, updatedAt}`.
  * - `n:<partition>` holds the collector-session sequence counters, as `[collectorSessionId, next][]`.
+ * - `t:<partition>` holds the miniapp telemetry lost and not yet reported, per package (`FleetTelemetryLosses`).
+ *
+ * Telemetry (Phase 12) has a share of the queue: a `telemetry_event`'s record ID starts with `tel.`, so its key says
+ * what it is. Telemetry takes at most 2,000 of the 10,000 places. When that share or the queue is full, the oldest
+ * telemetry record gives way, and a record of any other kind never does to telemetry: an arriving record that finds
+ * the queue full evicts the oldest telemetry before anything else. Telemetry that is evicted, expires, or that MFM
+ * rejects is counted per package under `t:`, never as a coverage gap, and the reporter sends it as `telemetry_loss`.
  *
  * MMKV can list keys only by listing all of them, so the first call for a partition in a process scans the store
  * once, repairs the index if a crash left it behind, and keeps the partition's ordered record keys in memory.
@@ -29,10 +36,13 @@
  * `sweepExpired` is how the 7-day bound still holds for it: one scan finds every partition, expires its old
  * records and removes what an empty partition no longer needs.
  */
-import { FLEET_LIMITS } from "@mentra/cloud-protocol";
+import { FLEET_LIMITS, FLEET_TELEMETRY_LIMITS } from "@mentra/cloud-protocol";
 import { normalizeCoreUrl } from "./coreUrl";
 import { getFleetStore } from "./fleetStorage";
 import { sha256HexOfText, utf8ByteLength } from "./utf8";
+/** A telemetry record's ID starts with this, so the queue tells telemetry from the rest by its key. */
+export const TELEMETRY_RECORD_PREFIX = "tel.";
+export const isTelemetryRecordId = (recordId) => recordId.startsWith(TELEMETRY_RECORD_PREFIX);
 const SEQUENCE_WIDTH = 16;
 const MAX_TRACKED_COLLECTOR_SESSIONS = 16;
 const EMPTY_LOSSES = { dropped: 0, expired: 0, from: null, to: null, updatedAt: 0 };
@@ -47,6 +57,7 @@ const recordPrefix = (partition) => `q:${partition}:`;
 const indexKey = (partition) => `i:${partition}`;
 const lossKey = (partition) => `l:${partition}`;
 const sequenceKey = (partition) => `n:${partition}`;
+const telemetryLossKey = (partition) => `t:${partition}`;
 function recordKey(partition, sequence, recordId) {
     return `${recordPrefix(partition)}${String(sequence).padStart(SEQUENCE_WIDTH, "0")}:${recordId}`;
 }
@@ -120,7 +131,7 @@ function groupByPartition(keys) {
     const entry = (partition) => {
         let existing = found.get(partition);
         if (!existing) {
-            existing = { records: [], hasIndex: false, hasLosses: false, hasSequences: false };
+            existing = { records: [], hasIndex: false, hasLosses: false, hasTelemetryLosses: false, hasSequences: false };
             found.set(partition, existing);
         }
         return existing;
@@ -137,6 +148,8 @@ function groupByPartition(keys) {
             entry(key.slice(2)).hasLosses = true;
         else if (key.startsWith("n:"))
             entry(key.slice(2)).hasSequences = true;
+        else if (key.startsWith("t:"))
+            entry(key.slice(2)).hasTelemetryLosses = true;
     }
     return found;
 }
@@ -256,14 +269,35 @@ function buildQueue(store, options) {
     }
     /** Discards records that cannot be read, counting them as dropped. */
     function discardUnreadable(partition, state, unreadable) {
-        noteLosses(partition, "dropped", unreadable.map(() => undefined));
+        // An unreadable telemetry record names no miniapp to count it for, and is never a coverage gap.
+        noteLosses(partition, "dropped", unreadable.filter((key) => !isTelemetryKey(partition, key)).map(() => undefined));
         const gone = new Set(unreadable);
         for (const key of unreadable)
             removeKey(key);
         state.keys = state.keys.filter((key) => !gone.has(key));
         persistIndex(partition, state);
     }
+    const idOffsetOf = (partition) => recordPrefix(partition).length + SEQUENCE_WIDTH + 1;
+    const isTelemetryKey = (partition, key) => isTelemetryRecordId(key.slice(idOffsetOf(partition)));
+    /** Removes the telemetry record at `key`, counting it as `kind` for its package. */
+    function evictTelemetry(partition, state, key, kind, at = now()) {
+        const record = readEntry(key)?.record;
+        const packageName = record?.kind === "telemetry_event" ? record.payload.packageName : null;
+        if (packageName !== null)
+            noteTelemetryLoss(partition, packageName, kind, 1, at, record.observedAt);
+        state.keys.splice(state.keys.indexOf(key), 1);
+        removeKey(key);
+    }
+    /**
+     * Keeps the partition inside its places: telemetry inside its share, and the whole inside 10,000, the oldest
+     * telemetry going first. Only a queue full of other records drops the oldest record of all, as a coverage gap.
+     */
     function trimToCapacity(partition, state) {
+        const telemetry = state.keys.filter((key) => isTelemetryKey(partition, key));
+        while (telemetry.length > FLEET_TELEMETRY_LIMITS.queueShare)
+            evictTelemetry(partition, state, telemetry.shift(), "evicted");
+        while (state.keys.length > FLEET_LIMITS.phoneQueueMaxRecords && telemetry.length > 0)
+            evictTelemetry(partition, state, telemetry.shift(), "evicted");
         const excess = state.keys.length - FLEET_LIMITS.phoneQueueMaxRecords;
         if (excess <= 0)
             return;
@@ -271,6 +305,29 @@ function buildQueue(store, options) {
         noteLosses(partition, "dropped", observedAts);
         removeOldest(state, excess);
     }
+    function readTelemetryLosses(partition) {
+        const value = readJson(telemetryLossKey(partition));
+        return value && typeof value === "object" && value.packages && typeof value.packages === "object" ? value : null;
+    }
+    function noteTelemetryLoss(partition, packageName, kind, count, at = now(), observedAt) {
+        if (!(count > 0))
+            return;
+        try {
+            const stored = readTelemetryLosses(partition) ?? { packages: {}, from: null, to: null, updatedAt: at };
+            const entry = stored.packages[packageName] ?? { overLimit: 0, evicted: 0, expired: 0, rejected: 0 };
+            entry[kind] += count;
+            stored.packages[packageName] = entry;
+            const when = observedAt ?? new Date(at).toISOString();
+            stored.from = earlier(stored.from, when);
+            stored.to = later(stored.to, when);
+            stored.updatedAt = at;
+            store.set(telemetryLossKey(partition), JSON.stringify(stored));
+        }
+        catch (error) {
+            // Telemetry losses are best effort: a count that cannot be stored is lost with the events it counted.
+            warn("could not persist a telemetry loss count", error);
+        }
+    }
     function expire(partition, state, at) {
         const cutoff = at - FLEET_LIMITS.phoneQueueMaxAgeMs;
         const expired = [];
@@ -280,10 +337,18 @@ function buildQueue(store, options) {
         // a young record can sit ahead of older ones; those wait until it ages out, which only delays their expiry.
         for (; head < state.keys.length; head += 1) {
             const entry = readEntry(state.keys[head]);
-            if (entry === null)
-                unreadable.push(undefined);
-            else if (entry.enqueuedAt < cutoff)
-                expired.push(entry.record.observedAt);
+            if (entry === null) {
+                if (!isTelemetryKey(partition, state.keys[head]))
+                    unreadable.push(undefined);
+            }
+            else if (entry.enqueuedAt < cutoff) {
+                // Expired telemetry is counted per package, never as a coverage gap.
+                if (entry.record.kind === "telemetry_event") {
+                    noteTelemetryLoss(partition, entry.record.payload.packageName, "expired", 1, at, entry.record.observedAt);
+                }
+                else
+                    expired.push(entry.record.observedAt);
+            }
             else
                 break;
         }
@@ -309,6 +374,11 @@ function buildQueue(store, options) {
             if (losses === null || at - losses.updatedAt > FLEET_LIMITS.phoneQueueMaxAgeMs)
                 removeKey(lossKey(partition));
         }
+        if (found.hasTelemetryLosses) {
+            const losses = readTelemetryLosses(partition);
+            if (losses === null || at - losses.updatedAt > FLEET_LIMITS.phoneQueueMaxAgeMs)
+                removeKey(telemetryLossKey(partition));
+        }
     }
     function loadSequences(partition) {
         const cached = sequences.get(partition);
@@ -331,7 +401,11 @@ function buildQueue(store, options) {
             }
             catch (error) {
                 warn("could not store a record", error);
-                noteLosses(partition, "dropped", [record?.observedAt]);
+                // Telemetry that cannot be stored is its miniapp's loss, never a coverage gap.
+                if (record?.kind === "telemetry_event")
+                    noteTelemetryLoss(partition, record.payload.packageName, "evicted", 1, now(), record.observedAt);
+                else
+                    noteLosses(partition, "dropped", [record?.observedAt]);
                 return;
             }
             trimToCapacity(partition, state);
@@ -410,12 +484,24 @@ function buildQueue(store, options) {
                 warn("could not sweep expired records", error);
             }
         },
+        noteTelemetryLoss(partition, packageName, kind, count, at) {
+            noteTelemetryLoss(partition, packageName, kind, count, at);
+        },
+        takeTelemetryLosses(partition, at) {
+            expire(partition, load(partition), at);
+            const losses = readTelemetryLosses(partition);
+            if (losses === null || Object.keys(losses.packages).length === 0)
+                return null;
+            removeKey(telemetryLossKey(partition));
+            return { packages: losses.packages, from: losses.from, to: losses.to };
+        },
         clearPartition(partition) {
             const state = load(partition);
             for (const key of state.keys)
                 removeKey(key);
             removeKey(indexKey(partition));
             removeKey(lossKey(partition));
+            removeKey(telemetryLossKey(partition));
             removeKey(sequenceKey(partition));
             state.keys = [];
             state.nextSeq = 0;