@mentra/engine 0.1.0-dev.0

package/src/services/asg/mediaProcessingQueue.ts

@@ -0,0 +1,371 @@
+/**
+ * Media Processing Queue
+ *
+ * Decouples media processing (HDR merge, color correction, stabilization, camera roll save)
+ * from the download pipeline. Downloads push items here; processing runs independently.
+ */
+
+import * as RNFS from "@dr.pogodin/react-native-fs"
+import CrustModule from "@mentra/crust"
+
+import {asgCameraApi} from "./asgCameraApi"
+import {localStorageService} from "./localStorageService"
+import {INVALID_DOWNLOADED_MEDIA, validateDownloadedMediaFile} from "./galleryMediaValidation"
+import {reportInvalidGalleryMedia} from "./GalleryMediaIntegrityReportService"
+import {useGallerySyncStore} from "../../stores/gallerySync"
+import {BgTimer} from "../../utils/timers"
+import {MediaLibraryPermissions} from "../../utils/permissions/MediaLibraryPermissions"
+
+const TAG = "[MediaProcessingQueue]"
+
+export interface ProcessingItem {
+  /** Unique ID — capture_id (v2) or file name (v1) */
+  id: string
+  type: "photo" | "video"
+  /** Path to the primary downloaded file */
+  primaryPath: string
+  /** HDR bracket paths (v2 only) */
+  bracketPaths?: string[]
+  /** IMU sidecar path for video stabilization */
+  sidecarPath?: string
+  /** Thumbnail base64 data */
+  thumbnailData?: string
+  /** Capture directory for saving thumbnail */
+  captureDir?: string
+  /** Original capture timestamp */
+  timestamp?: number
+  /** Total file size */
+  totalSize: number
+  /** Video duration in ms */
+  duration?: number
+  /** Glasses model */
+  glassesModel?: string
+  /** Whether to process (lens/color/stabilization) */
+  shouldProcess: boolean
+  /** Whether to auto-save to camera roll */
+  shouldAutoSave: boolean
+  /** Pre-downloaded thumbnail path (v1 legacy sync) */
+  thumbnailPath?: string
+  /** File names to delete from glasses after processing completes */
+  deleteFromGlasses?: string[]
+}
+
+class MediaProcessingQueue {
+  private queue: ProcessingItem[] = []
+  private isRunning = false
+  private aborted = false
+  private generation = 0 // C2: incremented on reset() to invalidate stale processLoop()
+
+  /** Add an item to the processing queue. Starts processing if not already running. */
+  enqueue(item: ProcessingItem): void {
+    this.queue.push(item)
+    console.log(`${TAG} Enqueued ${item.id} (${item.type}), queue size: ${this.queue.length}`)
+
+    // Only mark as processing if we'll actually process this item
+    if (item.shouldProcess) {
+      const store = useGallerySyncStore.getState()
+      store.onFileProcessing(item.id)
+    }
+
+    if (!this.isRunning) {
+      this.processLoop()
+    }
+  }
+
+  /** Cancel all pending processing. */
+  abort(): void {
+    this.aborted = true
+    this.queue = []
+    console.log(`${TAG} Aborted`)
+  }
+
+  /** Reset state for a new sync session. */
+  reset(): void {
+    this.queue = []
+    this.isRunning = false
+    this.aborted = false
+    this.generation++ // C2: invalidate any running processLoop
+  }
+
+  /** Returns true if there are items queued or currently processing. */
+  get hasPending(): boolean {
+    return this.queue.length > 0 || this.isRunning
+  }
+
+  /** Returns a promise that resolves when the queue is fully drained, or rejects on timeout. */
+  waitUntilDrained(timeoutMs: number = 600000): Promise<void> {
+    if (!this.hasPending) return Promise.resolve()
+    return new Promise((resolve, reject) => {
+      const deadline = Date.now() + timeoutMs
+      const check = () => {
+        if (!this.hasPending || this.aborted) {
+          resolve()
+        } else if (Date.now() >= deadline) {
+          console.error(`${TAG} waitUntilDrained timed out after ${timeoutMs}ms, aborting queue`)
+          this.abort()
+          reject(new Error(`Processing queue timed out after ${timeoutMs / 1000}s`))
+        } else {
+          BgTimer.setTimeout(check, 200)
+        }
+      }
+      check()
+    })
+  }
+
+  /** Process items one at a time. */
+  private async processLoop(): Promise<void> {
+    if (this.isRunning) return
+    this.isRunning = true
+    const myGeneration = this.generation // C2: capture generation to detect reset()
+
+    while (this.queue.length > 0 && !this.aborted && this.generation === myGeneration) {
+      const item = this.queue.shift()!
+      let processFailed = false
+      try {
+        await this.processItem(item)
+      } catch (error) {
+        console.error(`${TAG} Error processing ${item.id}:`, error)
+        processFailed = true
+      }
+
+      // Exit if generation changed (reset was called during processing)
+      if (this.generation !== myGeneration) break
+
+      const store = useGallerySyncStore.getState()
+      if (!processFailed) {
+        // Success: increment processedFiles and remove from processingFiles set.
+        store.onFileProcessed(item.id)
+      } else {
+        // Failure: processItem already called onFileFailed. Calling onFileProcessed
+        // here would double-count the item (counted as both failed AND processed).
+        // Still clear the processingFiles entry so the UI doesn't show it as in-progress.
+        const current = store.processingFiles
+        if (current.has(item.id)) {
+          const newSet = new Set(current)
+          newSet.delete(item.id)
+          useGallerySyncStore.setState({processingFiles: newSet})
+        }
+      }
+    }
+
+    // Only clear isRunning if this loop owns the current generation
+    if (this.generation === myGeneration) {
+      this.isRunning = false
+    }
+  }
+
+  /** Process a single item through the full pipeline. */
+  private async processItem(item: ProcessingItem): Promise<void> {
+    const startTime = Date.now()
+    let filePathToSave = item.primaryPath
+
+    // 1. HDR merge (photos with brackets only)
+    if (item.shouldProcess && item.type === "photo" && item.bracketPaths && item.bracketPaths.length >= 3) {
+      try {
+        const underPath = item.bracketPaths.find((p) => p.includes("ev-2")) || item.bracketPaths[0]
+        const normalPath = item.bracketPaths.find((p) => p.includes("ev0")) || item.bracketPaths[1]
+        const overPath = item.bracketPaths.find((p) => p.includes("ev2") && !p.includes("ev-2")) || item.bracketPaths[2]
+
+        const hdrPath = item.primaryPath + ".hdr.jpg"
+        const hdrResult = await CrustModule.mergeHdrBrackets(underPath, normalPath, overPath, hdrPath)
+        if (hdrResult.success && hdrResult.outputPath) {
+          filePathToSave = hdrResult.outputPath
+          console.log(`${TAG} HDR merged ${item.id} in ${hdrResult.processingTimeMs}ms`)
+        }
+      } catch (hdrError) {
+        console.warn(`${TAG} HDR merge error for ${item.id}, continuing:`, hdrError)
+      }
+    }
+
+    // 2. Image processing (lens + color correction)
+    if (item.shouldProcess && item.type === "photo") {
+      try {
+        const processedPath = filePathToSave + ".processed.jpg"
+        const result = await CrustModule.processGalleryImage(filePathToSave, processedPath, {
+          lensCorrection: true,
+          colorCorrection: true,
+        })
+        if (result.success && result.outputPath) {
+          filePathToSave = result.outputPath
+          console.log(`${TAG} 🎨 Processed ${item.id} in ${result.processingTimeMs}ms`)
+        }
+      } catch (procError) {
+        console.warn(`${TAG} Processing error for ${item.id}, using original:`, procError)
+      }
+    }
+
+    // 3. Video stabilization + color correction
+    if (item.shouldProcess && item.type === "video" && item.sidecarPath) {
+      try {
+        const stabilizedPath = item.primaryPath + ".stabilized.mp4"
+        const result = await CrustModule.stabilizeVideo(item.primaryPath, item.sidecarPath, stabilizedPath)
+        if (result.success && result.outputPath) {
+          filePathToSave = result.outputPath
+          console.log(`${TAG} 📹 Stabilized ${item.id} in ${result.processingTimeMs}ms`)
+        }
+      } catch (stabError) {
+        console.warn(`${TAG} Stabilization error for ${item.id}, using original:`, stabError)
+      }
+    }
+
+    // 4. Save thumbnail to disk (or use pre-downloaded thumbnail from v1 sync)
+    let localThumbnailPath: string | undefined = item.thumbnailPath
+    if (item.thumbnailData && item.captureDir) {
+      try {
+        const thumbPath = `${item.captureDir}/.thumb.jpg`
+        const base64Data = item.thumbnailData.startsWith("data:")
+          ? item.thumbnailData.split(",")[1]
+          : item.thumbnailData
+        await RNFS.writeFile(thumbPath, base64Data, "base64")
+        localThumbnailPath = thumbPath
+      } catch (thumbError) {
+        console.warn(`${TAG} Failed to save thumbnail for ${item.id}:`, thumbError)
+      }
+    }
+
+    // 5. Validate local file before persisting metadata or deleting from glasses
+    try {
+      await validateDownloadedMediaFile({
+        path: filePathToSave,
+        name: item.id,
+        mediaKind: item.type,
+      })
+    } catch (validationError: any) {
+      const reason =
+        validationError?.message?.includes(INVALID_DOWNLOADED_MEDIA) ?
+          validationError.message
+        : `${INVALID_DOWNLOADED_MEDIA}: ${item.id}`
+      console.error(`${TAG} Validation failed for ${item.id}: ${reason}`)
+      reportInvalidGalleryMedia({
+        name: item.id,
+        path: filePathToSave,
+        mediaKind: item.type,
+        stage: "processing_validation",
+        reason,
+        expectedSize: item.totalSize,
+        duration: item.duration,
+        glassesModel: item.glassesModel,
+      })
+      const store = useGallerySyncStore.getState()
+      store.onFileFailed(item.id, reason)
+      await RNFS.unlink(filePathToSave).catch(() => {})
+      for (const intermediate of [
+        item.primaryPath + ".hdr.jpg",
+        item.primaryPath + ".processed.jpg",
+        item.primaryPath + ".stabilized.mp4",
+      ]) {
+        if (intermediate !== filePathToSave) {
+          await RNFS.unlink(intermediate).catch(() => {})
+        }
+      }
+      throw new Error(reason)
+    }
+
+    // 6. Save to camera roll
+    if (item.shouldAutoSave) {
+      const success = await MediaLibraryPermissions.saveToLibrary(filePathToSave, item.timestamp)
+      if (success) {
+        console.log(`${TAG} ✅ Saved to camera roll: ${item.id}`)
+      } else {
+        console.warn(`${TAG} ❌ Failed to save to camera roll: ${item.id}`)
+        // D1: Surface camera roll save failures to the UI
+        const store = useGallerySyncStore.getState()
+        store.onFileFailed(item.id, "camera roll save failed")
+      }
+    }
+
+    // 7. Save metadata
+    const isVideo = item.type === "video"
+    const downloadedFile = localStorageService.convertToDownloadedFile(
+      {
+        name: item.id,
+        url: "",
+        download: "",
+        size: item.totalSize,
+        modified: item.timestamp || Date.now(),
+        is_video: isVideo,
+        thumbnail_data: item.thumbnailData,
+        duration: item.duration,
+        filePath: filePathToSave,
+        glassesModel: item.glassesModel,
+      },
+      filePathToSave,
+      localThumbnailPath,
+      item.glassesModel,
+    )
+    try {
+      await localStorageService.saveDownloadedFile(downloadedFile)
+    } catch (metadataError) {
+      // D2: Clean up orphaned file if metadata save fails, then re-throw
+      console.error(`${TAG} Metadata save failed for ${item.id}, cleaning up file:`, metadataError)
+      await RNFS.unlink(filePathToSave).catch(() => {})
+      throw metadataError
+    }
+
+    // S4: Clean up intermediate processing files
+    const intermediates = [
+      item.primaryPath + ".hdr.jpg",
+      item.primaryPath + ".processed.jpg",
+      item.primaryPath + ".stabilized.mp4",
+    ]
+    for (const intermediate of intermediates) {
+      if (intermediate !== filePathToSave) {
+        RNFS.unlink(intermediate).catch(() => {}) // fire-and-forget
+      }
+    }
+
+    // 8. Update file in sync queue with local paths for gallery display
+    const store = useGallerySyncStore.getState()
+    const localFileUrl = filePathToSave.startsWith("file://") ? filePathToSave : `file://${filePathToSave}`
+    const localThumbUrl = localThumbnailPath
+      ? localThumbnailPath.startsWith("file://")
+        ? localThumbnailPath
+        : `file://${localThumbnailPath}`
+      : undefined
+    store.updateFileInQueue(item.id, {
+      name: item.id,
+      url: localFileUrl,
+      download: localFileUrl,
+      size: item.totalSize,
+      modified: item.timestamp || Date.now(),
+      is_video: isVideo,
+      filePath: filePathToSave,
+      mime_type: isVideo ? "video/mp4" : "image/jpeg",
+      thumbnail_data: item.thumbnailData,
+      thumbnailPath: localThumbUrl,
+      duration: item.duration,
+    })
+
+    // 9. Delete from glasses now that processing is complete — but only if the
+    // local file actually exists and has data. If the download was truncated or
+    // processing failed silently, we must not destroy the only good copy.
+    if (item.deleteFromGlasses && item.deleteFromGlasses.length > 0) {
+      try {
+        const localFileExists = await RNFS.exists(filePathToSave)
+        if (!localFileExists) {
+          console.error(`${TAG} Skipping glasses deletion for ${item.id}: local file missing at ${filePathToSave}`)
+        } else {
+          const localStat = await RNFS.stat(filePathToSave)
+          if (localStat.size === 0) {
+            console.error(`${TAG} Skipping glasses deletion for ${item.id}: local file is 0 bytes`)
+          } else if (item.totalSize > 0 && localStat.size < item.totalSize * 0.5) {
+            // If local file is less than 50% of expected size, something went wrong
+            console.error(
+              `${TAG} Skipping glasses deletion for ${item.id}: local file ${localStat.size} bytes is much smaller than expected ${item.totalSize} bytes`,
+            )
+          } else {
+            await asgCameraApi.deleteFilesFromServer(item.deleteFromGlasses)
+            console.log(`${TAG} 🗑️ Deleted ${item.deleteFromGlasses.join(", ")} from glasses`)
+          }
+        }
+      } catch (deleteError) {
+        console.warn(`${TAG} Delete from glasses failed for ${item.id} (non-fatal):`, deleteError)
+      }
+    }
+
+    const elapsed = Date.now() - startTime
+    console.log(`${TAG} ✅ Finished ${item.id} in ${elapsed}ms`)
+  }
+}
+
+export const mediaProcessingQueue = new MediaProcessingQueue()

package/src/services/asgOtaVersionUrl.ts

@@ -0,0 +1,41 @@
+import {SETTINGS, useSettingsStore} from "../stores/settings"
+
+const OTA_VERSION_URL_PROD = "https://ota.mentraglass.com/prod_live_version.json"
+
+function isLegacyAsgOtaStartBuild(glassesBuildNumber?: string | null): boolean {
+  const buildNumber = Number.parseInt(glassesBuildNumber ?? "", 10)
+  // ASG builds before 39 ignore ota_start.ota_version_url, so compare against
+  // the URL they will actually use.
+  return Number.isFinite(buildNumber) && buildNumber < 39
+}
+
+function getOtaVersionUrlDevOverride(): string | null {
+  // Super mode only: a wrong OTA manifest can brick glasses, so a saved
+  // override is inert unless super mode is currently enabled.
+  if (!useSettingsStore.getState().getSetting(SETTINGS.super_mode.key)) {
+    return null
+  }
+  const value = useSettingsStore.getState().getSetting(SETTINGS.ota_version_url.key)
+  const trimmed = typeof value === "string" ? value.trim() : ""
+  return trimmed || null
+}
+
+export function getAsgOtaVersionUrl(glassesUrl?: string | null, glassesBuildNumber?: string | null): string {
+  const deviceUrl = glassesUrl?.trim()
+  if (isLegacyAsgOtaStartBuild(glassesBuildNumber)) {
+    // Legacy glasses ignore ota_start.ota_version_url and install from their
+    // compiled default, so the developer override does not apply to them either.
+    return deviceUrl || OTA_VERSION_URL_PROD
+  }
+
+  const devOverrideUrl = getOtaVersionUrlDevOverride()
+  if (devOverrideUrl) {
+    return devOverrideUrl
+  }
+
+  const envUrl = process.env.EXPO_PUBLIC_ASG_OTA_VERSION_URL?.trim()
+  if (envUrl) {
+    return envUrl
+  }
+  return deviceUrl || OTA_VERSION_URL_PROD
+}

package/src/services/blobPaths.ts

@@ -0,0 +1,86 @@
+/**
+ * Pure path helper for BlobStore. No React Native / Expo imports, so it's
+ * unit-testable in isolation (see blobPaths.test.ts).
+ */
+
+/** Filesystem-safe path segment. Strips traversal + unsafe chars; never empty. */
+export function sanitizeSegment(s: string): string {
+  const cleaned = (s || "").replace(/[^A-Za-z0-9._-]/g, "_")
+  if (cleaned === "" || cleaned === "." || cleaned === "..") return "_"
+  return cleaned.slice(0, 120)
+}
+
+/**
+ * Filesystem-safe display name for a shared blob, guaranteed to carry an
+ * extension. The on-disk blob name is a generated machine id (with a
+ * mime-derived extension since withDiskExt; legacy blobs may lack it), so the
+ * OS share sheet (which keys off the file path, not any metadata) would
+ * otherwise emit a machine-named file — breaking "open with"/preview on the
+ * receiving side. Derives the extension from the mimeType when the stored name
+ * lacks one.
+ */
+export function shareFileName(meta: {name?: string; fileName: string; mimeType: string}): string {
+  const raw = (meta.name || meta.fileName).trim()
+  // Replace path separators + characters illegal on common filesystems (keep
+  // spaces, hyphens, dots, etc. — they're valid and keep names readable).
+  // eslint-disable-next-line no-control-regex
+  let safe = raw.replace(/[/\\<>:"|?*\x00-\x1f]/g, "_").trim()
+  if (!safe) safe = meta.fileName
+  // Split base + extension: use an extension already on the name, else derive
+  // one from the mimeType.
+  const dot = safe.lastIndexOf(".")
+  const hasExt = dot > 0 && dot < safe.length - 1
+  let base = hasExt ? safe.slice(0, dot) : safe
+  const ext = hasExt ? safe.slice(dot + 1) : extForMime(meta.mimeType)
+  const suffix = ext ? `.${ext}` : ""
+  // Bound the total length: common filesystems reject names over ~255 bytes, so
+  // a huge app-provided name would make the share's file copy throw. Truncate
+  // the base while preserving the extension (mirrors sanitizeSegment's ceiling).
+  const MAX_LEN = 120
+  if (base.length + suffix.length > MAX_LEN) {
+    base = base.slice(0, Math.max(1, MAX_LEN - suffix.length))
+  }
+  return base + suffix
+}
+
+/**
+ * On-disk name for a stored blob: the generated id plus a mime-derived
+ * extension when one is known. iOS AVPlayer resolves a local file's format
+ * from its path extension (not content sniffing), so an extension-less WAV is
+ * unplayable through `session.speaker.play` even though the bytes are valid.
+ * Leaves a name that already has an extension untouched.
+ */
+export function withDiskExt(fileName: string, mimeType: string): string {
+  if (fileName.includes(".")) return fileName
+  const ext = extForMime(mimeType)
+  return ext ? `${fileName}.${ext}` : fileName
+}
+
+/** Best-effort file extension (no dot) for a MIME type. Inverse of inferMime in BlobStore. */
+export function extForMime(mime: string): string | undefined {
+  const m = (mime || "").split(";")[0].trim().toLowerCase()
+  const map: Record<string, string> = {
+    "application/pdf": "pdf",
+    "application/epub+zip": "epub",
+    "application/zip": "zip",
+    "application/json": "json",
+    "text/plain": "txt",
+    "text/csv": "csv",
+    "text/html": "html",
+    "video/mp4": "mp4",
+    "video/quicktime": "mov",
+    "video/webm": "webm",
+    "audio/mpeg": "mp3",
+    "audio/mp4": "m4a",
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "audio/wave": "wav",
+    "audio/ogg": "ogg",
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+    "image/svg+xml": "svg",
+  }
+  return map[m]
+}

package/src/services/cloudStreamApi.ts

@@ -0,0 +1,154 @@
+/**
+ * Managed-stream provisioning over the cloud-v2 runtime (cloud-client REST):
+ *
+ *   POST   /api/camera/stream      -> provision (Cloudflare live input)
+ *   GET    /api/camera/stream/:id  -> provider's ingest status
+ *   DELETE /api/camera/stream/:id  -> teardown
+ *
+ * Drop-in replacement for the legacy `v2StreamApi` (which hit the v1 cloud's
+ * /api/v2/client/streams/managed on backend_url): same exported shapes, so
+ * PhoneStreamCoordinator is unchanged apart from the import. Local miniapps
+ * use ONLY this path — no legacy V1 transport.
+ *
+ * Errors are tagged with stage "provision"/"status"/"teardown" and transport
+ * "cloud-rest" so a miniapp sees exactly where and on which leg it broke.
+ */
+
+import {cloudClientService as cloudClient} from "./CloudClientService"
+
+/**
+ * Restream destination. The full stream key is part of the URL — Cloudflare
+ * appends nothing on the publish side. `name` is a human label that surfaces
+ * in Cloudflare's dashboard but doesn't affect routing.
+ */
+export interface RestreamDestination {
+  url: string
+  name?: string
+}
+
+/** Caller-facing shape: either a bare URL string or the full object. */
+export type RestreamDestinationInput = string | RestreamDestination
+
+export interface ProvisionResult {
+  liveInputId: string
+  rtmpUrl: string
+  srtUrl?: string
+  hlsUrl: string
+  dashUrl: string
+  webrtcUrl?: string
+  webrtcPublishUrl?: string
+}
+
+export interface CloudflareStatus {
+  isConnected: boolean
+  state?: string | null
+  connectedAt?: string
+  lastSeenAt?: string
+  reason?: string
+}
+
+export type StreamApiStage = "provision" | "status" | "teardown"
+
+export class StreamApiError extends Error {
+  readonly transport = "cloud-rest" as const
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly stage: StreamApiStage,
+  ) {
+    super(message)
+    this.name = "StreamApiError"
+  }
+}
+
+/** The cloud-v2 runtime's ManagedStream wire shape (open records, see protocol). */
+interface ManagedStreamWire {
+  streamId: string
+  ingest: {
+    url?: string
+    streamKey?: string
+    rtmpUrl?: string
+    srtUrl?: string
+    webrtcPublishUrl?: string
+  }
+  playback: {
+    hls?: string
+    dash?: string
+    webrtc?: string
+  }
+}
+
+/**
+ * Provision a managed stream on the cloud-v2 runtime. Returns ready-to-publish
+ * ingest URLs (credentials embedded) plus the playback URLs.
+ */
+export async function provisionManagedStream(
+  restreamDestinations?: RestreamDestinationInput[],
+): Promise<ProvisionResult> {
+  let wire: ManagedStreamWire
+  try {
+    wire = (await cloudClient.startManagedStream(
+      restreamDestinations && restreamDestinations.length > 0 ? {restreamDestinations} : {},
+    )) as ManagedStreamWire
+  } catch (err) {
+    throw new StreamApiError(
+      "STREAM_PROVISION_FAILED",
+      err instanceof Error ? err.message : String(err),
+      "provision",
+    )
+  }
+
+  const ingest = wire.ingest ?? {}
+  const playback = wire.playback ?? {}
+  const rtmpUrl = ingest.rtmpUrl ?? (ingest.url && ingest.streamKey ? `${ingest.url}${ingest.streamKey}` : "")
+  if (!playback.hls || !playback.dash) {
+    throw new StreamApiError(
+      "STREAM_PROVISION_INCOMPLETE",
+      `runtime returned no playback URLs for stream ${wire.streamId}`,
+      "provision",
+    )
+  }
+
+  return {
+    liveInputId: wire.streamId,
+    rtmpUrl,
+    srtUrl: ingest.srtUrl,
+    hlsUrl: playback.hls,
+    dashUrl: playback.dash,
+    webrtcUrl: playback.webrtc,
+    webrtcPublishUrl: ingest.webrtcPublishUrl,
+  }
+}
+
+/** The provider's view of the ingest: is the device's push arriving? */
+export async function getManagedStreamStatus(liveInputId: string): Promise<CloudflareStatus> {
+  try {
+    const s = await cloudClient.getManagedStreamStatus(liveInputId)
+    return {
+      isConnected: s.isConnected,
+      state: s.state,
+      connectedAt: s.connectedAt,
+      lastSeenAt: s.lastSeenAt,
+      reason: s.reason,
+    }
+  } catch (err) {
+    throw new StreamApiError(
+      "STREAM_STATUS_FAILED",
+      err instanceof Error ? err.message : String(err),
+      "status",
+    )
+  }
+}
+
+/** Tear down the provider stream. */
+export async function teardownManagedStream(liveInputId: string): Promise<void> {
+  try {
+    await cloudClient.stopManagedStream(liveInputId)
+  } catch (err) {
+    throw new StreamApiError(
+      "STREAM_TEARDOWN_FAILED",
+      err instanceof Error ? err.message : String(err),
+      "teardown",
+    )
+  }
+}

package/src/services/gallerySyncClock.ts

@@ -0,0 +1,39 @@
+/**
+ * Clock skew detection for gallery sync (phone vs glasses).
+ * Phone pushes time to glasses only when skew is detected during sync.
+ */
+
+export const CLOCK_SKEW_TOLERANCE_MS = 60_000
+
+export type ClockSkewReason = "watermark_ahead_of_glasses" | "wall_clock_drift" | ""
+
+export interface ClockSkewResult {
+  skewed: boolean
+  reason: ClockSkewReason
+}
+
+export function detectClockSkew(
+  phoneNow: number,
+  glassesServerTime: number,
+  lastSyncTime: number,
+  toleranceMs: number = CLOCK_SKEW_TOLERANCE_MS,
+): ClockSkewResult {
+  if (lastSyncTime > glassesServerTime + toleranceMs) {
+    return {skewed: true, reason: "watermark_ahead_of_glasses"}
+  }
+  if (Math.abs(phoneNow - glassesServerTime) > toleranceMs) {
+    return {skewed: true, reason: "wall_clock_drift"}
+  }
+  return {skewed: false, reason: ""}
+}
+
+export function isSyncManifestEmpty(syncData: {
+  api_version?: number
+  captures?: unknown[]
+  changed_files?: unknown[]
+}): boolean {
+  if (syncData.api_version === 2 && syncData.captures && syncData.captures.length > 0) {
+    return false
+  }
+  return !syncData.changed_files || syncData.changed_files.length === 0
+}