@glassly/engine 0.1.0-dev.0

package/build/services/SpeakerSegmentResolver.d.ts

@@ -0,0 +1,87 @@
+/**
+ * SpeakerSegmentResolver — pure per-segment speaker resolution logic.
+ *
+ * Joins on-device speaker-identification windows (native SpeakerIdEngine
+ * `speaker_detected` events) against transcription segments by time overlap.
+ *
+ * Design constraint (see notes/speaker-id-plan.md §3.3): provider diarization
+ * labels (Soniox "Speaker N") are NOT reliable — the same person can flicker
+ * across labels and one label can absorb two people. The label is never an
+ * identity and no label→profile map is kept; it is used only as a hint that
+ * the speaker MAY have changed:
+ *   1. Carry-forward: a segment with no overlapping ID window may inherit the
+ *      previous segment's resolution only if its label is unchanged and the
+ *      gap is small. A label change breaks carry-forward.
+ *   2. Conflict damping: if the resolved identity changes while the label did
+ *      NOT change, a stronger vote is required before switching — this absorbs
+ *      phone/cloud clock skew at turn boundaries without ever letting the
+ *      label veto strong embedding evidence.
+ * Segments without sufficient ID evidence carry no resolution — unknown is
+ * the honest default, never "whatever this label resolved to last time".
+ *
+ * Resolution is tri-state: an enrolled identity, a confident OTHER
+ * (`resolvedSpeakerId: null` — a voice that is affirmatively not enrolled;
+ * windows in the ambiguous similarity band never produce it), or null.
+ *
+ * Clock caveat accepted for v1: phone/cloud alignment is approximate
+ * (transport latency); overlap voting over ≥2 s windows absorbs it. Do not
+ * attempt sample-accurate alignment.
+ */
+export interface SpeakerIdWindow {
+    /** Matched profile id, or null when the voice matched no enrolled profile. */
+    profileId: string | null;
+    name: string | null;
+    /**
+     * For null-profile windows only: true when the similarity was clearly BELOW
+     * the enrolled voice (not merely below the match threshold) — affirmative
+     * evidence of a different person. Null-profile windows without this flag are
+     * ambiguous: they block carry-forward when dominant but assert nothing.
+     */
+    confidentOther?: boolean;
+    /** Epoch ms (native clock — same epoch as JS Date.now()). */
+    startMs: number;
+    endMs: number;
+}
+export interface SegmentInput {
+    /** Estimated epoch ms span of the spoken segment. */
+    startMs: number;
+    endMs: number;
+    /** Raw provider diarization label — hint only, never an identity. */
+    label?: string;
+}
+export interface SegmentResolution {
+    /**
+     * Matched enrolled profile id — or null for a confident OTHER: the segment
+     * was dominated by a voice that is affirmatively not any enrolled profile.
+     */
+    resolvedSpeakerId: string | null;
+    resolvedSpeakerName: string | null;
+}
+/** Windows older than this (vs. the resolver's newest timestamp) are dropped. */
+export declare const WINDOW_RETENTION_MS = 60000;
+/** Carry-forward dies when the gap since the previous segment exceeds this. */
+export declare const CARRY_FORWARD_MAX_GAP_MS = 5000;
+/** A winning vote needs at least this much absolute overlap. */
+export declare const MIN_WINNING_OVERLAP_MS = 250;
+export declare class SpeakerSegmentResolver {
+    private windows;
+    private last;
+    addWindow(window: SpeakerIdWindow): void;
+    /** Per audio session: drop all identification evidence and segment state. */
+    reset(): void;
+    /**
+     * Resolve one FINAL segment. Also advances the carry-forward state, so call
+     * exactly once per final segment, in delivery order.
+     */
+    resolve(segment: SegmentInput): SegmentResolution | null;
+    private resolveInner;
+    private voteCandidates;
+    /**
+     * No overlapping ID window (short interjection, window not flushed yet):
+     * inherit the previous segment's resolution only while the label is
+     * unchanged and the gap is small. A label change is the "speaker may have
+     * changed" hint — the segment stays unresolved.
+     */
+    private carryForward;
+}
+//# sourceMappingURL=SpeakerSegmentResolver.d.ts.map

package/build/services/SpeakerSegmentResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpeakerSegmentResolver.d.ts","sourceRoot":"","sources":["../../src/services/SpeakerSegmentResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,QAAS,CAAA;AACzC,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,OAAQ,CAAA;AAC7C,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAsBzC,qBAAa,sBAAsB;IACjC,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,IAAI,CAAgC;IAE5C,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAOxC,6EAA6E;IAC7E,KAAK,IAAI,IAAI;IAKb;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,iBAAiB,GAAG,IAAI;IAMxD,OAAO,CAAC,YAAY;IA8CpB,OAAO,CAAC,cAAc;IAkBtB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;CAMrB"}

package/build/services/SpeakerSegmentResolver.js

@@ -0,0 +1,137 @@
+/**
+ * SpeakerSegmentResolver — pure per-segment speaker resolution logic.
+ *
+ * Joins on-device speaker-identification windows (native SpeakerIdEngine
+ * `speaker_detected` events) against transcription segments by time overlap.
+ *
+ * Design constraint (see notes/speaker-id-plan.md §3.3): provider diarization
+ * labels (Soniox "Speaker N") are NOT reliable — the same person can flicker
+ * across labels and one label can absorb two people. The label is never an
+ * identity and no label→profile map is kept; it is used only as a hint that
+ * the speaker MAY have changed:
+ *   1. Carry-forward: a segment with no overlapping ID window may inherit the
+ *      previous segment's resolution only if its label is unchanged and the
+ *      gap is small. A label change breaks carry-forward.
+ *   2. Conflict damping: if the resolved identity changes while the label did
+ *      NOT change, a stronger vote is required before switching — this absorbs
+ *      phone/cloud clock skew at turn boundaries without ever letting the
+ *      label veto strong embedding evidence.
+ * Segments without sufficient ID evidence carry no resolution — unknown is
+ * the honest default, never "whatever this label resolved to last time".
+ *
+ * Resolution is tri-state: an enrolled identity, a confident OTHER
+ * (`resolvedSpeakerId: null` — a voice that is affirmatively not enrolled;
+ * windows in the ambiguous similarity band never produce it), or null.
+ *
+ * Clock caveat accepted for v1: phone/cloud alignment is approximate
+ * (transport latency); overlap voting over ≥2 s windows absorbs it. Do not
+ * attempt sample-accurate alignment.
+ */
+/** Windows older than this (vs. the resolver's newest timestamp) are dropped. */
+export const WINDOW_RETENTION_MS = 60_000;
+/** Carry-forward dies when the gap since the previous segment exceeds this. */
+export const CARRY_FORWARD_MAX_GAP_MS = 5_000;
+/** A winning vote needs at least this much absolute overlap. */
+export const MIN_WINNING_OVERLAP_MS = 250;
+/** Damping-comparison key: OTHER counts as its own identity, distinct from every profile. */
+function identityKey(res) {
+    return res.resolvedSpeakerId ?? "\0other";
+}
+export class SpeakerSegmentResolver {
+    windows = [];
+    last = null;
+    addWindow(window) {
+        if (!(window.endMs > window.startMs))
+            return;
+        this.windows.push(window);
+        const cutoff = window.endMs - WINDOW_RETENTION_MS;
+        this.windows = this.windows.filter((w) => w.endMs >= cutoff);
+    }
+    /** Per audio session: drop all identification evidence and segment state. */
+    reset() {
+        this.windows = [];
+        this.last = null;
+    }
+    /**
+     * Resolve one FINAL segment. Also advances the carry-forward state, so call
+     * exactly once per final segment, in delivery order.
+     */
+    resolve(segment) {
+        const resolution = this.resolveInner(segment);
+        this.last = { endMs: segment.endMs, label: segment.label, resolution };
+        return resolution;
+    }
+    resolveInner(segment) {
+        const candidates = this.voteCandidates(segment);
+        if (candidates.length === 0) {
+            return this.carryForward(segment);
+        }
+        candidates.sort((a, b) => b.overlapMs - a.overlapMs);
+        const winner = candidates[0];
+        const runnerUp = candidates[1];
+        // Too little overlap to mean anything (clock-skew sliver) — treat as no
+        // evidence rather than a confident unknown.
+        const minOverlap = Math.min(MIN_WINNING_OVERLAP_MS, Math.max(1, (segment.endMs - segment.startMs) * 0.3));
+        if (winner.overlapMs < minOverlap) {
+            return this.carryForward(segment);
+        }
+        // Ambiguous-voice-dominant segment: honest null (no carry-forward — a
+        // voice failed to match but wasn't clearly different either).
+        if (winner.kind === "unknown")
+            return null;
+        // Confident-other-dominant → an OTHER resolution (null id); a profile
+        // winner resolves to that identity. Both pass through conflict damping.
+        const proposed = winner.kind === "other"
+            ? { resolvedSpeakerId: null, resolvedSpeakerName: null }
+            : { resolvedSpeakerId: winner.profileId, resolvedSpeakerName: winner.name };
+        // Conflict damping: identity flip while the provider label did NOT change
+        // needs a stronger vote (≥2 agreeing windows, or a clear overlap majority)
+        // — otherwise keep the previous binding for this segment. A label change
+        // is the provider hinting the speaker may have changed, so the flip
+        // stands on normal evidence.
+        const prev = this.last?.resolution ?? null;
+        const labelUnchanged = this.last != null && this.last.label === segment.label;
+        const identityFlipped = prev != null && identityKey(prev) !== identityKey(proposed);
+        if (identityFlipped && labelUnchanged) {
+            const strongEnough = winner.windowCount >= 2 || (runnerUp === undefined ? true : winner.overlapMs >= runnerUp.overlapMs * 2);
+            if (!strongEnough)
+                return prev;
+        }
+        return proposed;
+    }
+    voteCandidates(segment) {
+        const byKey = new Map();
+        for (const w of this.windows) {
+            const overlap = Math.min(segment.endMs, w.endMs) - Math.max(segment.startMs, w.startMs);
+            if (overlap <= 0)
+                continue;
+            const kind = w.profileId != null ? "profile" : w.confidentOther ? "other" : "unknown";
+            const key = w.profileId ?? `\0${kind}`;
+            const existing = byKey.get(key);
+            if (existing) {
+                existing.overlapMs += overlap;
+                existing.windowCount += 1;
+            }
+            else {
+                byKey.set(key, { kind, profileId: w.profileId, name: w.name, overlapMs: overlap, windowCount: 1 });
+            }
+        }
+        return [...byKey.values()];
+    }
+    /**
+     * No overlapping ID window (short interjection, window not flushed yet):
+     * inherit the previous segment's resolution only while the label is
+     * unchanged and the gap is small. A label change is the "speaker may have
+     * changed" hint — the segment stays unresolved.
+     */
+    carryForward(segment) {
+        if (!this.last?.resolution)
+            return null;
+        if (this.last.label !== segment.label)
+            return null;
+        if (segment.startMs - this.last.endMs > CARRY_FORWARD_MAX_GAP_MS)
+            return null;
+        return this.last.resolution;
+    }
+}
+//# sourceMappingURL=SpeakerSegmentResolver.js.map

package/build/services/SpeakerSegmentResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpeakerSegmentResolver.js","sourceRoot":"","sources":["../../src/services/SpeakerSegmentResolver.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * SpeakerSegmentResolver — pure per-segment speaker resolution logic.\n *\n * Joins on-device speaker-identification windows (native SpeakerIdEngine\n * `speaker_detected` events) against transcription segments by time overlap.\n *\n * Design constraint (see notes/speaker-id-plan.md §3.3): provider diarization\n * labels (Soniox \"Speaker N\") are NOT reliable — the same person can flicker\n * across labels and one label can absorb two people. The label is never an\n * identity and no label→profile map is kept; it is used only as a hint that\n * the speaker MAY have changed:\n *   1. Carry-forward: a segment with no overlapping ID window may inherit the\n *      previous segment's resolution only if its label is unchanged and the\n *      gap is small. A label change breaks carry-forward.\n *   2. Conflict damping: if the resolved identity changes while the label did\n *      NOT change, a stronger vote is required before switching — this absorbs\n *      phone/cloud clock skew at turn boundaries without ever letting the\n *      label veto strong embedding evidence.\n * Segments without sufficient ID evidence carry no resolution — unknown is\n * the honest default, never \"whatever this label resolved to last time\".\n *\n * Resolution is tri-state: an enrolled identity, a confident OTHER\n * (`resolvedSpeakerId: null` — a voice that is affirmatively not enrolled;\n * windows in the ambiguous similarity band never produce it), or null.\n *\n * Clock caveat accepted for v1: phone/cloud alignment is approximate\n * (transport latency); overlap voting over ≥2 s windows absorbs it. Do not\n * attempt sample-accurate alignment.\n */\n\nexport interface SpeakerIdWindow {\n  /** Matched profile id, or null when the voice matched no enrolled profile. */\n  profileId: string | null\n  name: string | null\n  /**\n   * For null-profile windows only: true when the similarity was clearly BELOW\n   * the enrolled voice (not merely below the match threshold) — affirmative\n   * evidence of a different person. Null-profile windows without this flag are\n   * ambiguous: they block carry-forward when dominant but assert nothing.\n   */\n  confidentOther?: boolean\n  /** Epoch ms (native clock — same epoch as JS Date.now()). */\n  startMs: number\n  endMs: number\n}\n\nexport interface SegmentInput {\n  /** Estimated epoch ms span of the spoken segment. */\n  startMs: number\n  endMs: number\n  /** Raw provider diarization label — hint only, never an identity. */\n  label?: string\n}\n\nexport interface SegmentResolution {\n  /**\n   * Matched enrolled profile id — or null for a confident OTHER: the segment\n   * was dominated by a voice that is affirmatively not any enrolled profile.\n   */\n  resolvedSpeakerId: string | null\n  resolvedSpeakerName: string | null\n}\n\n/** Windows older than this (vs. the resolver's newest timestamp) are dropped. */\nexport const WINDOW_RETENTION_MS = 60_000\n/** Carry-forward dies when the gap since the previous segment exceeds this. */\nexport const CARRY_FORWARD_MAX_GAP_MS = 5_000\n/** A winning vote needs at least this much absolute overlap. */\nexport const MIN_WINNING_OVERLAP_MS = 250\n\ninterface Candidate {\n  /** \"profile\" = enrolled match; \"other\" = confident non-enrolled voice; \"unknown\" = ambiguous no-match. */\n  kind: \"profile\" | \"other\" | \"unknown\"\n  profileId: string | null\n  name: string | null\n  overlapMs: number\n  windowCount: number\n}\n\n/** Damping-comparison key: OTHER counts as its own identity, distinct from every profile. */\nfunction identityKey(res: SegmentResolution): string {\n  return res.resolvedSpeakerId ?? \"\\0other\"\n}\n\ninterface LastSegmentState {\n  endMs: number\n  label: string | undefined\n  resolution: SegmentResolution | null\n}\n\nexport class SpeakerSegmentResolver {\n  private windows: SpeakerIdWindow[] = []\n  private last: LastSegmentState | null = null\n\n  addWindow(window: SpeakerIdWindow): void {\n    if (!(window.endMs > window.startMs)) return\n    this.windows.push(window)\n    const cutoff = window.endMs - WINDOW_RETENTION_MS\n    this.windows = this.windows.filter((w) => w.endMs >= cutoff)\n  }\n\n  /** Per audio session: drop all identification evidence and segment state. */\n  reset(): void {\n    this.windows = []\n    this.last = null\n  }\n\n  /**\n   * Resolve one FINAL segment. Also advances the carry-forward state, so call\n   * exactly once per final segment, in delivery order.\n   */\n  resolve(segment: SegmentInput): SegmentResolution | null {\n    const resolution = this.resolveInner(segment)\n    this.last = {endMs: segment.endMs, label: segment.label, resolution}\n    return resolution\n  }\n\n  private resolveInner(segment: SegmentInput): SegmentResolution | null {\n    const candidates = this.voteCandidates(segment)\n\n    if (candidates.length === 0) {\n      return this.carryForward(segment)\n    }\n\n    candidates.sort((a, b) => b.overlapMs - a.overlapMs)\n    const winner = candidates[0]\n    const runnerUp = candidates[1]\n\n    // Too little overlap to mean anything (clock-skew sliver) — treat as no\n    // evidence rather than a confident unknown.\n    const minOverlap = Math.min(MIN_WINNING_OVERLAP_MS, Math.max(1, (segment.endMs - segment.startMs) * 0.3))\n    if (winner.overlapMs < minOverlap) {\n      return this.carryForward(segment)\n    }\n\n    // Ambiguous-voice-dominant segment: honest null (no carry-forward — a\n    // voice failed to match but wasn't clearly different either).\n    if (winner.kind === \"unknown\") return null\n\n    // Confident-other-dominant → an OTHER resolution (null id); a profile\n    // winner resolves to that identity. Both pass through conflict damping.\n    const proposed: SegmentResolution =\n      winner.kind === \"other\"\n        ? {resolvedSpeakerId: null, resolvedSpeakerName: null}\n        : {resolvedSpeakerId: winner.profileId, resolvedSpeakerName: winner.name}\n\n    // Conflict damping: identity flip while the provider label did NOT change\n    // needs a stronger vote (≥2 agreeing windows, or a clear overlap majority)\n    // — otherwise keep the previous binding for this segment. A label change\n    // is the provider hinting the speaker may have changed, so the flip\n    // stands on normal evidence.\n    const prev = this.last?.resolution ?? null\n    const labelUnchanged = this.last != null && this.last.label === segment.label\n    const identityFlipped = prev != null && identityKey(prev) !== identityKey(proposed)\n    if (identityFlipped && labelUnchanged) {\n      const strongEnough =\n        winner.windowCount >= 2 || (runnerUp === undefined ? true : winner.overlapMs >= runnerUp.overlapMs * 2)\n      if (!strongEnough) return prev\n    }\n\n    return proposed\n  }\n\n  private voteCandidates(segment: SegmentInput): Candidate[] {\n    const byKey = new Map<string, Candidate>()\n    for (const w of this.windows) {\n      const overlap = Math.min(segment.endMs, w.endMs) - Math.max(segment.startMs, w.startMs)\n      if (overlap <= 0) continue\n      const kind: Candidate[\"kind\"] = w.profileId != null ? \"profile\" : w.confidentOther ? \"other\" : \"unknown\"\n      const key = w.profileId ?? `\\0${kind}`\n      const existing = byKey.get(key)\n      if (existing) {\n        existing.overlapMs += overlap\n        existing.windowCount += 1\n      } else {\n        byKey.set(key, {kind, profileId: w.profileId, name: w.name, overlapMs: overlap, windowCount: 1})\n      }\n    }\n    return [...byKey.values()]\n  }\n\n  /**\n   * No overlapping ID window (short interjection, window not flushed yet):\n   * inherit the previous segment's resolution only while the label is\n   * unchanged and the gap is small. A label change is the \"speaker may have\n   * changed\" hint — the segment stays unresolved.\n   */\n  private carryForward(segment: SegmentInput): SegmentResolution | null {\n    if (!this.last?.resolution) return null\n    if (this.last.label !== segment.label) return null\n    if (segment.startMs - this.last.endMs > CARRY_FORWARD_MAX_GAP_MS) return null\n    return this.last.resolution\n  }\n}\n"]}

package/build/services/StreamLifecycleController.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Drives RTMP stream liveliness checks via a keep-alive heartbeat:
+ * `setActive(true)` starts the timer; each tick sends a keep-alive with a
+ * fresh ackId; `maxMissedAcks` consecutive timeouts fire `onTimeout`.
+ */
+export interface LifecycleLogger {
+    child(bindings: Record<string, unknown>): LifecycleLogger;
+    debug(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+interface StreamLifecycleCallbacks {
+    sendKeepAlive: (ackId: string) => Promise<void> | void;
+    onTimeout: () => Promise<void> | void;
+    onKeepAliveSent?: (ackId: string) => void;
+    onKeepAliveAcked?: (ackId: string, ageMs: number) => void;
+    onKeepAliveMissed?: (ackId: string, ageMs: number, missedCount: number) => void;
+}
+export interface StreamLifecycleOptions {
+    logger: LifecycleLogger;
+    streamId: string;
+    keepAliveIntervalMs: number;
+    ackTimeoutMs: number;
+    maxMissedAcks: number;
+    shouldSendKeepAlive?: () => boolean;
+    now?: () => number;
+}
+/**
+ * Drives RTMP stream liveliness checks. Activate to start the heartbeat;
+ * each tick sends a keep-alive with a fresh ackId and arms a timeout. When
+ * `maxMissedAcks` consecutive timeouts fire, `onTimeout` is invoked and the
+ * caller is expected to tear the stream down.
+ */
+export declare class StreamLifecycleController {
+    private readonly callbacks;
+    private keepAliveTimer?;
+    private pendingAcks;
+    private missedAcks;
+    private lastActivityMs;
+    private active;
+    private disposed;
+    private readonly logger;
+    private readonly streamId;
+    private readonly keepAliveIntervalMs;
+    private readonly ackTimeoutMs;
+    private readonly maxMissedAcks;
+    private readonly shouldSendKeepAlive?;
+    private readonly now;
+    constructor(options: StreamLifecycleOptions, callbacks: StreamLifecycleCallbacks);
+    setActive(active: boolean): void;
+    recordActivity(): void;
+    handleAck(ackId: string): void;
+    dispose(): void;
+    getLastActivityMs(): number;
+    private startTimer;
+    private stopTimer;
+    private tick;
+    private onAckTimeout;
+    private clearPendingAcks;
+    private createAckId;
+}
+export {};
+//# sourceMappingURL=StreamLifecycleController.d.ts.map

package/build/services/StreamLifecycleController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamLifecycleController.d.ts","sourceRoot":"","sources":["../../src/services/StreamLifecycleController.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,CAAA;IACzD,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAChC;AAED,UAAU,wBAAwB;IAChC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACtD,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACrC,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACzD,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAA;CAChF;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,eAAe,CAAA;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAA;IACnC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAOD;;;;;GAKG;AACH,qBAAa,yBAAyB;IAkBlC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAjB5B,OAAO,CAAC,cAAc,CAAC,CAAgC;IACvD,OAAO,CAAC,WAAW,CAAyC;IAC5D,OAAO,CAAC,UAAU,CAAI;IACtB,OAAO,CAAC,cAAc,CAAQ;IAC9B,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,QAAQ,CAAQ;IAExB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAe;IACpD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;gBAGhC,OAAO,EAAE,sBAAsB,EACd,SAAS,EAAE,wBAAwB;IAYtD,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAehC,cAAc,IAAI,IAAI;IAKtB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAgB9B,OAAO,IAAI,IAAI;IASf,iBAAiB,IAAI,MAAM;IAI3B,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,SAAS;YAQH,IAAI;IAyBlB,OAAO,CAAC,YAAY;IA8BpB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,WAAW;CAGpB"}

package/build/services/StreamLifecycleController.js

@@ -0,0 +1,148 @@
+/**
+ * Drives RTMP stream liveliness checks via a keep-alive heartbeat:
+ * `setActive(true)` starts the timer; each tick sends a keep-alive with a
+ * fresh ackId; `maxMissedAcks` consecutive timeouts fire `onTimeout`.
+ */
+/**
+ * Drives RTMP stream liveliness checks. Activate to start the heartbeat;
+ * each tick sends a keep-alive with a fresh ackId and arms a timeout. When
+ * `maxMissedAcks` consecutive timeouts fire, `onTimeout` is invoked and the
+ * caller is expected to tear the stream down.
+ */
+export class StreamLifecycleController {
+    callbacks;
+    keepAliveTimer;
+    pendingAcks = new Map();
+    missedAcks = 0;
+    lastActivityMs;
+    active = false;
+    disposed = false;
+    logger;
+    streamId;
+    keepAliveIntervalMs;
+    ackTimeoutMs;
+    maxMissedAcks;
+    shouldSendKeepAlive;
+    now;
+    constructor(options, callbacks) {
+        this.callbacks = callbacks;
+        this.logger = options.logger.child({ component: "StreamLifecycle" });
+        this.streamId = options.streamId;
+        this.keepAliveIntervalMs = options.keepAliveIntervalMs;
+        this.ackTimeoutMs = options.ackTimeoutMs;
+        this.maxMissedAcks = options.maxMissedAcks;
+        this.shouldSendKeepAlive = options.shouldSendKeepAlive;
+        this.now = options.now ?? (() => Date.now());
+        this.lastActivityMs = this.now();
+    }
+    setActive(active) {
+        if (this.disposed || this.active === active)
+            return;
+        this.logger.debug({ streamId: this.streamId, active }, "Updating lifecycle active state");
+        this.active = active;
+        if (active) {
+            this.startTimer();
+        }
+        else {
+            this.stopTimer();
+            this.clearPendingAcks();
+            this.missedAcks = 0;
+        }
+    }
+    recordActivity() {
+        this.lastActivityMs = this.now();
+        this.missedAcks = 0;
+    }
+    handleAck(ackId) {
+        if (this.disposed)
+            return;
+        const ackInfo = this.pendingAcks.get(ackId);
+        if (!ackInfo) {
+            this.logger.warn({ streamId: this.streamId, ackId }, "Received unknown keep-alive ACK");
+            return;
+        }
+        clearTimeout(ackInfo.timeout);
+        this.pendingAcks.delete(ackId);
+        this.recordActivity();
+        this.callbacks.onKeepAliveAcked?.(ackId, this.now() - ackInfo.sentAt);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.stopTimer();
+        this.clearPendingAcks();
+        this.logger.debug({ streamId: this.streamId }, "Lifecycle disposed");
+    }
+    getLastActivityMs() {
+        return this.lastActivityMs;
+    }
+    startTimer() {
+        if (this.keepAliveTimer)
+            return;
+        this.keepAliveTimer = setInterval(() => {
+            void this.tick();
+        }, this.keepAliveIntervalMs);
+        this.logger.debug({ streamId: this.streamId }, "Keep-alive timer started");
+    }
+    stopTimer() {
+        if (this.keepAliveTimer) {
+            clearInterval(this.keepAliveTimer);
+            this.keepAliveTimer = undefined;
+            this.logger.debug({ streamId: this.streamId }, "Keep-alive timer stopped");
+        }
+    }
+    async tick() {
+        if (this.disposed || !this.active)
+            return;
+        if (this.shouldSendKeepAlive && !this.shouldSendKeepAlive()) {
+            this.logger.warn({ streamId: this.streamId }, "Skipping keep-alive send because transport is unavailable");
+            return;
+        }
+        const ackId = this.createAckId();
+        const sentAt = this.now();
+        const timeout = setTimeout(() => {
+            this.onAckTimeout(ackId, sentAt);
+        }, this.ackTimeoutMs);
+        this.pendingAcks.set(ackId, { sentAt, timeout });
+        this.callbacks.onKeepAliveSent?.(ackId);
+        try {
+            await this.callbacks.sendKeepAlive(ackId);
+        }
+        catch (error) {
+            this.logger.error({ streamId: this.streamId, ackId, error }, "Error sending keep-alive");
+        }
+    }
+    onAckTimeout(ackId, sentAt) {
+        if (this.disposed)
+            return;
+        // Race guard: handleAck may have processed the ACK between the timeout
+        // being scheduled and this callback running. In that case the ackId is
+        // no longer pending — counting it as missed would falsely escalate.
+        if (!this.pendingAcks.has(ackId))
+            return;
+        this.pendingAcks.delete(ackId);
+        this.missedAcks += 1;
+        const ageMs = this.now() - sentAt;
+        this.logger.warn({ streamId: this.streamId, ackId, missedAcks: this.missedAcks, ageMs }, "Keep-alive ACK timeout");
+        this.callbacks.onKeepAliveMissed?.(ackId, ageMs, this.missedAcks);
+        if (this.missedAcks >= this.maxMissedAcks) {
+            this.logger.error({
+                streamId: this.streamId,
+                missedAcks: this.missedAcks,
+                maxMissedAcks: this.maxMissedAcks,
+            }, "Maximum missed ACKs reached; triggering timeout");
+            void this.callbacks.onTimeout();
+        }
+    }
+    clearPendingAcks() {
+        for (const { timeout } of this.pendingAcks.values()) {
+            clearTimeout(timeout);
+        }
+        this.pendingAcks.clear();
+    }
+    createAckId() {
+        return `a${this.now().toString(36).slice(-5)}`;
+    }
+}
+//# sourceMappingURL=StreamLifecycleController.js.map

package/build/services/StreamLifecycleController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamLifecycleController.js","sourceRoot":"","sources":["../../src/services/StreamLifecycleController.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Drives RTMP stream liveliness checks via a keep-alive heartbeat:\n * `setActive(true)` starts the timer; each tick sends a keep-alive with a\n * fresh ackId; `maxMissedAcks` consecutive timeouts fire `onTimeout`.\n */\n\nexport interface LifecycleLogger {\n  child(bindings: Record<string, unknown>): LifecycleLogger\n  debug(...args: unknown[]): void\n  warn(...args: unknown[]): void\n  error(...args: unknown[]): void\n}\n\ninterface StreamLifecycleCallbacks {\n  sendKeepAlive: (ackId: string) => Promise<void> | void\n  onTimeout: () => Promise<void> | void\n  onKeepAliveSent?: (ackId: string) => void\n  onKeepAliveAcked?: (ackId: string, ageMs: number) => void\n  onKeepAliveMissed?: (ackId: string, ageMs: number, missedCount: number) => void\n}\n\nexport interface StreamLifecycleOptions {\n  logger: LifecycleLogger\n  streamId: string\n  keepAliveIntervalMs: number\n  ackTimeoutMs: number\n  maxMissedAcks: number\n  shouldSendKeepAlive?: () => boolean\n  now?: () => number\n}\n\ninterface PendingAckInfo {\n  sentAt: number\n  timeout: ReturnType<typeof setTimeout>\n}\n\n/**\n * Drives RTMP stream liveliness checks. Activate to start the heartbeat;\n * each tick sends a keep-alive with a fresh ackId and arms a timeout. When\n * `maxMissedAcks` consecutive timeouts fire, `onTimeout` is invoked and the\n * caller is expected to tear the stream down.\n */\nexport class StreamLifecycleController {\n  private keepAliveTimer?: ReturnType<typeof setInterval>\n  private pendingAcks: Map<string, PendingAckInfo> = new Map()\n  private missedAcks = 0\n  private lastActivityMs: number\n  private active = false\n  private disposed = false\n\n  private readonly logger: LifecycleLogger\n  private readonly streamId: string\n  private readonly keepAliveIntervalMs: number\n  private readonly ackTimeoutMs: number\n  private readonly maxMissedAcks: number\n  private readonly shouldSendKeepAlive?: () => boolean\n  private readonly now: () => number\n\n  constructor(\n    options: StreamLifecycleOptions,\n    private readonly callbacks: StreamLifecycleCallbacks,\n  ) {\n    this.logger = options.logger.child({component: \"StreamLifecycle\"})\n    this.streamId = options.streamId\n    this.keepAliveIntervalMs = options.keepAliveIntervalMs\n    this.ackTimeoutMs = options.ackTimeoutMs\n    this.maxMissedAcks = options.maxMissedAcks\n    this.shouldSendKeepAlive = options.shouldSendKeepAlive\n    this.now = options.now ?? (() => Date.now())\n    this.lastActivityMs = this.now()\n  }\n\n  setActive(active: boolean): void {\n    if (this.disposed || this.active === active) return\n\n    this.logger.debug({streamId: this.streamId, active}, \"Updating lifecycle active state\")\n\n    this.active = active\n    if (active) {\n      this.startTimer()\n    } else {\n      this.stopTimer()\n      this.clearPendingAcks()\n      this.missedAcks = 0\n    }\n  }\n\n  recordActivity(): void {\n    this.lastActivityMs = this.now()\n    this.missedAcks = 0\n  }\n\n  handleAck(ackId: string): void {\n    if (this.disposed) return\n\n    const ackInfo = this.pendingAcks.get(ackId)\n    if (!ackInfo) {\n      this.logger.warn({streamId: this.streamId, ackId}, \"Received unknown keep-alive ACK\")\n      return\n    }\n\n    clearTimeout(ackInfo.timeout)\n    this.pendingAcks.delete(ackId)\n    this.recordActivity()\n\n    this.callbacks.onKeepAliveAcked?.(ackId, this.now() - ackInfo.sentAt)\n  }\n\n  dispose(): void {\n    if (this.disposed) return\n\n    this.disposed = true\n    this.stopTimer()\n    this.clearPendingAcks()\n    this.logger.debug({streamId: this.streamId}, \"Lifecycle disposed\")\n  }\n\n  getLastActivityMs(): number {\n    return this.lastActivityMs\n  }\n\n  private startTimer(): void {\n    if (this.keepAliveTimer) return\n    this.keepAliveTimer = setInterval(() => {\n      void this.tick()\n    }, this.keepAliveIntervalMs)\n    this.logger.debug({streamId: this.streamId}, \"Keep-alive timer started\")\n  }\n\n  private stopTimer(): void {\n    if (this.keepAliveTimer) {\n      clearInterval(this.keepAliveTimer)\n      this.keepAliveTimer = undefined\n      this.logger.debug({streamId: this.streamId}, \"Keep-alive timer stopped\")\n    }\n  }\n\n  private async tick(): Promise<void> {\n    if (this.disposed || !this.active) return\n\n    if (this.shouldSendKeepAlive && !this.shouldSendKeepAlive()) {\n      this.logger.warn({streamId: this.streamId}, \"Skipping keep-alive send because transport is unavailable\")\n      return\n    }\n\n    const ackId = this.createAckId()\n    const sentAt = this.now()\n\n    const timeout = setTimeout(() => {\n      this.onAckTimeout(ackId, sentAt)\n    }, this.ackTimeoutMs)\n\n    this.pendingAcks.set(ackId, {sentAt, timeout})\n    this.callbacks.onKeepAliveSent?.(ackId)\n\n    try {\n      await this.callbacks.sendKeepAlive(ackId)\n    } catch (error) {\n      this.logger.error({streamId: this.streamId, ackId, error}, \"Error sending keep-alive\")\n    }\n  }\n\n  private onAckTimeout(ackId: string, sentAt: number): void {\n    if (this.disposed) return\n\n    // Race guard: handleAck may have processed the ACK between the timeout\n    // being scheduled and this callback running. In that case the ackId is\n    // no longer pending — counting it as missed would falsely escalate.\n    if (!this.pendingAcks.has(ackId)) return\n\n    this.pendingAcks.delete(ackId)\n    this.missedAcks += 1\n    const ageMs = this.now() - sentAt\n\n    this.logger.warn({streamId: this.streamId, ackId, missedAcks: this.missedAcks, ageMs}, \"Keep-alive ACK timeout\")\n\n    this.callbacks.onKeepAliveMissed?.(ackId, ageMs, this.missedAcks)\n\n    if (this.missedAcks >= this.maxMissedAcks) {\n      this.logger.error(\n        {\n          streamId: this.streamId,\n          missedAcks: this.missedAcks,\n          maxMissedAcks: this.maxMissedAcks,\n        },\n        \"Maximum missed ACKs reached; triggering timeout\",\n      )\n\n      void this.callbacks.onTimeout()\n    }\n  }\n\n  private clearPendingAcks(): void {\n    for (const {timeout} of this.pendingAcks.values()) {\n      clearTimeout(timeout)\n    }\n    this.pendingAcks.clear()\n  }\n\n  private createAckId(): string {\n    return `a${this.now().toString(36).slice(-5)}`\n  }\n}\n"]}

package/build/services/SupportProfileSync.d.ts

@@ -0,0 +1,22 @@
+import type { SupportStateInput } from "@glassly/cloud-client";
+/**
+ * Keep Cloud V2's canonical support snapshot current without creating an event
+ * stream from noisy store updates. Only the explicitly selected fields below
+ * leave the phone; Wi-Fi, Bluetooth addresses, location and diagnostics do not.
+ */
+export declare function startSupportProfileSync(): void;
+export declare function stopSupportProfileSync(): void;
+export declare function retryDelayForSupportProfileResult(result: {
+    status: "accepted" | "deduplicated" | "stale";
+}): number | null;
+/**
+ * Support freshness is not worth an aggressive retry loop. A snapshot the
+ * server keeps rejecting (skewed clock, deleted account, signed-out host)
+ * backs off exponentially until it converges on the heartbeat cadence.
+ */
+export declare function retryDelayForSendFailure(consecutiveFailures: number): number;
+export declare function buildSnapshot(observedAt?: Date): SupportStateInput;
+/** Record only normalized connection failures; arbitrary exception messages never leave the phone. */
+export declare function recordSupportProfileConnectionFailure(error: unknown, stage: string): void;
+export declare function snapshotFingerprint(snapshot: SupportStateInput): string;
+//# sourceMappingURL=SupportProfileSync.d.ts.map

package/build/services/SupportProfileSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SupportProfileSync.d.ts","sourceRoot":"","sources":["../../src/services/SupportProfileSync.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,uBAAuB,CAAA;AAwB5D;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAO9C;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAgB7C;AA+ED,wBAAgB,iCAAiC,CAAC,MAAM,EAAE;IACxD,MAAM,EAAE,UAAU,GAAG,cAAc,GAAG,OAAO,CAAA;CAC9C,GAAG,MAAM,GAAG,IAAI,CAGhB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,mBAAmB,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,wBAAgB,aAAa,CAAC,UAAU,OAAa,GAAG,iBAAiB,CAoCxE;AAED,sGAAsG;AACtG,wBAAgB,qCAAqC,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAiBzF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAEvE"}