@remnic/core 9.12.0 → 9.13.0

package/src/meetings/detect.test.ts

@@ -0,0 +1,366 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { DEFAULT_MEETINGS_DETECTION_CONFIG, detectMeetings, meetingId } from "./detect.js";
+import type { MeetingAppSpan, MeetingAudioWindow, MeetingsDetectionInput } from "./types.js";
+
+const DATE = "2026-03-10";
+
+function span(app: string, startUtc: string, endUtc: string): MeetingAppSpan {
+  return { app, startUtc, endUtc };
+}
+
+function audio(overrides: Partial<MeetingAudioWindow> & { startUtc: string; endUtc: string }): MeetingAudioWindow {
+  return { source: "desktop", distinctNonWearerSpeakers: 2, ...overrides };
+}
+
+function input(overrides: Partial<MeetingsDetectionInput> = {}): MeetingsDetectionInput {
+  return { date: DATE, appSpans: [], audioWindows: [], ...overrides };
+}
+
+test("app+audio: an app span overlapping a conversation yields one meeting", () => {
+  const meetings = detectMeetings(
+    input({
+      appSpans: [span("Zoom", "2026-03-10T14:00:00.000Z", "2026-03-10T15:00:00.000Z")],
+      audioWindows: [audio({ source: "desktop", startUtc: "2026-03-10T14:01:00.000Z", endUtc: "2026-03-10T14:55:00.000Z" })],
+    }),
+  );
+  assert.equal(meetings.length, 1);
+  assert.equal(meetings[0]?.detectionSource, "app+audio");
+  assert.equal(meetings[0]?.app, "Zoom");
+  assert.deepEqual(meetings[0]?.sources, ["desktop"]);
+});
+
+test("activity only (app span, zero audio) → NO meeting (watching a recording)", () => {
+  const meetings = detectMeetings(
+    input({ appSpans: [span("Zoom", "2026-03-10T14:00:00.000Z", "2026-03-10T15:00:00.000Z")] }),
+  );
+  assert.equal(meetings.length, 0);
+});
+
+test("audio only: a long multi-speaker conversation with no app span is a meeting", () => {
+  const meetings = detectMeetings(
+    input({
+      audioWindows: [
+        audio({ source: "limitless", startUtc: "2026-03-10T09:00:00.000Z", endUtc: "2026-03-10T09:20:00.000Z", distinctNonWearerSpeakers: 3 }),
+      ],
+    }),
+  );
+  assert.equal(meetings.length, 1);
+  assert.equal(meetings[0]?.detectionSource, "audio");
+  assert.equal(meetings[0]?.app, undefined);
+});
+
+test("audio only: too short OR too few speakers is NOT a meeting", () => {
+  const short = detectMeetings(
+    input({ audioWindows: [audio({ startUtc: "2026-03-10T09:00:00.000Z", endUtc: "2026-03-10T09:05:00.000Z", distinctNonWearerSpeakers: 3 })] }),
+  );
+  assert.equal(short.length, 0);
+  const solo = detectMeetings(
+    input({ audioWindows: [audio({ startUtc: "2026-03-10T09:00:00.000Z", endUtc: "2026-03-10T09:30:00.000Z", distinctNonWearerSpeakers: 1 })] }),
+  );
+  assert.equal(solo.length, 0);
+});
+
+test("provider meeting is detected from its own boundaries without an app span", () => {
+  const meetings = detectMeetings(
+    input({
+      audioWindows: [
+        audio({ source: "granola", startUtc: "2026-03-10T16:00:00.000Z", endUtc: "2026-03-10T16:30:00.000Z", providerMeeting: true, title: "Roadmap", distinctNonWearerSpeakers: 0 }),
+      ],
+    }),
+  );
+  assert.equal(meetings.length, 1);
+  assert.equal(meetings[0]?.detectionSource, "provider");
+  assert.equal(meetings[0]?.title, "Roadmap");
+});
+
+test("rejoin within the merge gap collapses into ONE meeting; a 10-min gap stays TWO", () => {
+  const rejoin = detectMeetings(
+    input({
+      appSpans: [
+        span("Zoom", "2026-03-10T14:00:00.000Z", "2026-03-10T14:20:00.000Z"),
+        span("Zoom", "2026-03-10T14:21:00.000Z", "2026-03-10T14:40:00.000Z"),
+      ],
+      audioWindows: [
+        audio({ startUtc: "2026-03-10T14:00:00.000Z", endUtc: "2026-03-10T14:19:00.000Z" }),
+        audio({ startUtc: "2026-03-10T14:20:30.000Z", endUtc: "2026-03-10T14:39:00.000Z" }),
+      ],
+    }),
+  );
+  assert.equal(rejoin.length, 1);
+
+  const twoMeetings = detectMeetings(
+    input({
+      appSpans: [
+        span("Zoom", "2026-03-10T14:00:00.000Z", "2026-03-10T14:20:00.000Z"),
+        span("Zoom", "2026-03-10T14:30:00.000Z", "2026-03-10T14:50:00.000Z"),
+      ],
+      audioWindows: [
+        audio({ startUtc: "2026-03-10T14:00:00.000Z", endUtc: "2026-03-10T14:19:00.000Z" }),
+        audio({ startUtc: "2026-03-10T14:30:00.000Z", endUtc: "2026-03-10T14:49:00.000Z" }),
+      ],
+    }),
+  );
+  assert.equal(twoMeetings.length, 2);
+});
+
+test("multiple audio sources over the same window fuse into one meeting with both sources", () => {
+  const meetings = detectMeetings(
+    input({
+      appSpans: [span("Zoom", "2026-03-10T14:00:00.000Z", "2026-03-10T15:00:00.000Z")],
+      audioWindows: [
+        audio({ source: "desktop", startUtc: "2026-03-10T14:00:00.000Z", endUtc: "2026-03-10T14:55:00.000Z" }),
+        audio({ source: "limitless", startUtc: "2026-03-10T14:02:00.000Z", endUtc: "2026-03-10T14:58:00.000Z" }),
+      ],
+    }),
+  );
+  assert.equal(meetings.length, 1);
+  assert.deepEqual(meetings[0]?.sources, ["desktop", "limitless"]);
+});
+
+test("detected meetings never overlap and stay ordered after merge", () => {
+  const meetings = detectMeetings(
+    input({
+      appSpans: [span("Zoom", "2026-03-10T14:00:00.000Z", "2026-03-10T15:30:00.000Z")],
+      audioWindows: [
+        audio({ startUtc: "2026-03-10T14:00:00.000Z", endUtc: "2026-03-10T14:40:00.000Z" }),
+        audio({ startUtc: "2026-03-10T14:30:00.000Z", endUtc: "2026-03-10T15:10:00.000Z" }),
+        // A second, well-separated meeting so the ordering assertion is non-vacuous.
+        audio({
+          source: "granola",
+          startUtc: "2026-03-10T18:00:00.000Z",
+          endUtc: "2026-03-10T18:30:00.000Z",
+          providerMeeting: true,
+          title: "Sync",
+        }),
+      ],
+    }),
+  );
+  assert.equal(meetings.length, 2);
+  for (let i = 1; i < meetings.length; i++) {
+    assert.ok((meetings[i - 1]?.endUtc ?? "") <= (meetings[i]?.startUtc ?? ""), "meetings must not overlap");
+  }
+});
+
+test("sub-threshold overlap does not pair an app span with a conversation", () => {
+  // Only 1 minute of overlap; minOverlapMinutes default is 2 → audio-only rules apply.
+  const meetings = detectMeetings(
+    input({
+      appSpans: [span("Zoom", "2026-03-10T14:00:00.000Z", "2026-03-10T14:10:00.000Z")],
+      audioWindows: [audio({ startUtc: "2026-03-10T14:09:00.000Z", endUtc: "2026-03-10T14:16:00.000Z", distinctNonWearerSpeakers: 2 })],
+    }),
+  );
+  // 7-min conversation < 15-min audio-only floor and no qualifying app overlap → no meeting.
+  assert.equal(meetings.length, 0);
+});
+
+test("ids are stable across a re-run with 10% more fixture data appended", () => {
+  const base = input({
+    appSpans: [span("Zoom", "2026-03-10T14:00:00.000Z", "2026-03-10T15:00:00.000Z")],
+    audioWindows: [audio({ startUtc: "2026-03-10T14:00:00.000Z", endUtc: "2026-03-10T14:55:00.000Z" })],
+  });
+  const first = detectMeetings(base);
+  // Re-run with an extra, later meeting appended (more data, same early meeting).
+  const more = detectMeetings(
+    input({
+      appSpans: [...base.appSpans, span("Zoom", "2026-03-10T17:00:00.000Z", "2026-03-10T17:30:00.000Z")],
+      audioWindows: [...base.audioWindows, audio({ startUtc: "2026-03-10T17:01:00.000Z", endUtc: "2026-03-10T17:28:00.000Z" })],
+    }),
+  );
+  const firstId = first[0]?.id;
+  const sameId = more.find((m) => m.startUtc === first[0]?.startUtc)?.id;
+  assert.ok(firstId);
+  assert.equal(sameId, firstId, "the earlier meeting keeps its id when later data is added");
+});
+
+test("meetingId is deterministic and anchored on the exact start instant", () => {
+  const a = meetingId(DATE, "2026-03-10T14:00:05.000Z");
+  assert.equal(a, meetingId(DATE, "2026-03-10T14:00:05.000Z")); // same start instant → same id
+  assert.match(a, /^mtg-2026-03-10-[0-9a-f]{8}$/);
+  // Distinct start instants — even within the same minute — get distinct ids.
+  assert.notEqual(a, meetingId(DATE, "2026-03-10T14:00:06.000Z"));
+  assert.notEqual(a, meetingId(DATE, "2026-03-10T14:01:00.000Z"));
+});
+
+test("two short provider meetings in the same minute get distinct ids", () => {
+  const meetings = detectMeetings(
+    input({
+      audioWindows: [
+        audio({ source: "granola", startUtc: "2026-03-10T14:00:05.000Z", endUtc: "2026-03-10T14:00:20.000Z", providerMeeting: true, title: "A", distinctNonWearerSpeakers: 0 }),
+        audio({ source: "granola", startUtc: "2026-03-10T14:00:40.000Z", endUtc: "2026-03-10T14:00:55.000Z", providerMeeting: true, title: "B", distinctNonWearerSpeakers: 0 }),
+      ],
+    }),
+  );
+  // Provider candidates bypass the duration floors and don't merge (no shared
+  // app, disjoint), so both survive — and must not collide on id.
+  assert.equal(meetings.length, 2);
+  assert.notEqual(meetings[0]?.id, meetings[1]?.id);
+});
+
+test("a rolled-over calendar timestamp is dropped, not silently shifted", () => {
+  const meetings = detectMeetings(
+    input({
+      audioWindows: [
+        audio({ startUtc: "2026-02-30T14:00:00.000Z", endUtc: "2026-02-30T14:30:00.000Z", distinctNonWearerSpeakers: 3 }),
+        audio({ startUtc: "2026-03-10T10:00:00.000Z", endUtc: "2026-03-10T10:20:00.000Z", distinctNonWearerSpeakers: 3 }),
+      ],
+    }),
+  );
+  // Feb 30 is invalid → dropped, never rolled into Mar 2.
+  assert.equal(meetings.length, 1);
+  assert.equal(meetings[0]?.startUtc, "2026-03-10T10:00:00.000Z");
+});
+
+test("meeting id is unchanged when a late source extends the end (resync stability)", () => {
+  const first = detectMeetings(
+    input({
+      audioWindows: [
+        audio({ startUtc: "2026-03-10T14:00:00.000Z", endUtc: "2026-03-10T14:20:00.000Z", distinctNonWearerSpeakers: 3 }),
+      ],
+    }),
+  );
+  const extended = detectMeetings(
+    input({
+      audioWindows: [
+        audio({ source: "desktop", startUtc: "2026-03-10T14:00:00.000Z", endUtc: "2026-03-10T14:20:00.000Z", distinctNonWearerSpeakers: 3 }),
+        audio({ source: "limitless", startUtc: "2026-03-10T14:18:00.000Z", endUtc: "2026-03-10T14:45:00.000Z", distinctNonWearerSpeakers: 3 }),
+      ],
+    }),
+  );
+  assert.equal(first.length, 1);
+  assert.equal(extended.length, 1);
+  assert.equal(extended[0]?.endUtc, "2026-03-10T14:45:00.000Z"); // end grew
+  assert.equal(extended[0]?.id, first[0]?.id); // …but the id is unchanged
+});
+
+test("default config matches the issue-specified thresholds", () => {
+  assert.equal(DEFAULT_MEETINGS_DETECTION_CONFIG.minOverlapMinutes, 2);
+  assert.equal(DEFAULT_MEETINGS_DETECTION_CONFIG.audioOnlyMinMinutes, 15);
+  assert.equal(DEFAULT_MEETINGS_DETECTION_CONFIG.mergeGapMinutes, 2);
+});
+
+test("audio-only exactly at the 15-min floor qualifies", () => {
+  const meetings = detectMeetings(
+    input({
+      audioWindows: [
+        audio({ startUtc: "2026-03-10T09:00:00.000Z", endUtc: "2026-03-10T09:15:00.000Z", distinctNonWearerSpeakers: 2 }),
+      ],
+    }),
+  );
+  assert.equal(meetings.length, 1);
+  assert.equal(meetings[0]?.detectionSource, "audio");
+});
+
+test("app+audio exactly at the 2-min overlap threshold qualifies", () => {
+  const meetings = detectMeetings(
+    input({
+      appSpans: [span("Zoom", "2026-03-10T14:00:00.000Z", "2026-03-10T14:12:00.000Z")],
+      audioWindows: [
+        audio({ startUtc: "2026-03-10T14:10:00.000Z", endUtc: "2026-03-10T14:17:00.000Z", distinctNonWearerSpeakers: 2 }),
+      ],
+    }),
+  );
+  // Exactly 2 min overlap (14:10–14:12) → pairs as app+audio.
+  assert.equal(meetings.length, 1);
+  assert.equal(meetings[0]?.detectionSource, "app+audio");
+  assert.equal(meetings[0]?.app, "Zoom");
+});
+
+test("disjoint app + audio never pair even when minOverlapMinutes is 0", () => {
+  const meetings = detectMeetings(
+    input({
+      appSpans: [span("Zoom", "2026-03-10T14:00:00.000Z", "2026-03-10T14:05:00.000Z")],
+      audioWindows: [
+        audio({ startUtc: "2026-03-10T14:10:00.000Z", endUtc: "2026-03-10T14:17:00.000Z", distinctNonWearerSpeakers: 2 }),
+      ],
+    }),
+    { ...DEFAULT_MEETINGS_DETECTION_CONFIG, minOverlapMinutes: 0 },
+  );
+  // Disjoint windows (overlap 0) must not pair; 7-min audio < 15-min floor → no meeting.
+  assert.equal(meetings.length, 0);
+});
+
+test("invalid detection thresholds are rejected", () => {
+  for (const bad of [Number.NaN, -1, Number.POSITIVE_INFINITY]) {
+    assert.throws(
+      () => detectMeetings(input(), { ...DEFAULT_MEETINGS_DETECTION_CONFIG, minOverlapMinutes: bad }),
+      RangeError,
+    );
+  }
+  assert.throws(
+    () => detectMeetings(input(), { ...DEFAULT_MEETINGS_DETECTION_CONFIG, mergeGapMinutes: Number.NaN }),
+    RangeError,
+  );
+});
+
+test("a malformed timestamp is skipped defensively without dropping valid meetings", () => {
+  const meetings = detectMeetings(
+    input({
+      audioWindows: [
+        audio({ startUtc: "not-a-date", endUtc: "2026-03-10T09:20:00.000Z", distinctNonWearerSpeakers: 3 }),
+        audio({ startUtc: "2026-03-10T10:00:00.000Z", endUtc: "2026-03-10T10:20:00.000Z", distinctNonWearerSpeakers: 3 }),
+      ],
+    }),
+  );
+  // The malformed window is dropped; the valid conversation is still detected.
+  assert.equal(meetings.length, 1);
+  assert.equal(meetings[0]?.startUtc, "2026-03-10T10:00:00.000Z");
+});
+
+test("an offset-form rolled-over timestamp is also dropped", () => {
+  const meetings = detectMeetings(
+    input({
+      audioWindows: [
+        audio({ startUtc: "2026-02-30T14:00:00.000+00:00", endUtc: "2026-02-30T14:30:00.000+00:00", distinctNonWearerSpeakers: 3 }),
+        audio({ startUtc: "2026-03-10T10:00:00.000Z", endUtc: "2026-03-10T10:20:00.000Z", distinctNonWearerSpeakers: 3 }),
+      ],
+    }),
+  );
+  assert.equal(meetings.length, 1);
+  assert.equal(meetings[0]?.startUtc, "2026-03-10T10:00:00.000Z");
+});
+
+test("a timestamp offset beyond ±14:00 is dropped", () => {
+  const meetings = detectMeetings(
+    input({
+      audioWindows: [
+        audio({ startUtc: "2026-03-10T00:30:00.000+14:59", endUtc: "2026-03-10T01:00:00.000+14:59", distinctNonWearerSpeakers: 3 }),
+        audio({ startUtc: "2026-03-10T10:00:00.000Z", endUtc: "2026-03-10T10:20:00.000Z", distinctNonWearerSpeakers: 3 }),
+      ],
+    }),
+  );
+  assert.equal(meetings.length, 1);
+  assert.equal(meetings[0]?.startUtc, "2026-03-10T10:00:00.000Z");
+});
+
+test("a non-integer speaker count does not qualify an audio-only meeting", () => {
+  const meetings = detectMeetings(
+    input({
+      audioWindows: [
+        audio({ startUtc: "2026-03-10T09:00:00.000Z", endUtc: "2026-03-10T09:30:00.000Z", distinctNonWearerSpeakers: Number.POSITIVE_INFINITY }),
+      ],
+    }),
+  );
+  assert.equal(meetings.length, 0);
+});
+
+test("detectMeetings rejects a non-YYYY-MM-DD day (kept out of ids)", () => {
+  assert.throws(() => detectMeetings(input({ date: "2026/03/10" })), RangeError);
+  assert.throws(() => detectMeetings(input({ date: "2026-02-30" })), RangeError);
+});
+
+test("meetingId validates its inputs for direct callers", () => {
+  assert.throws(() => meetingId("2026/03/10", "2026-03-10T14:00:00.000Z"), RangeError);
+  assert.throws(() => meetingId("2026-03-10", "not-a-date"), RangeError);
+});
+
+test("equal-overlap app selection is deterministic regardless of input order", () => {
+  const win = { startUtc: "2026-03-10T14:00:00.000Z", endUtc: "2026-03-10T15:00:00.000Z", distinctNonWearerSpeakers: 2 };
+  const zoom = span("Zoom", "2026-03-10T14:00:00.000Z", "2026-03-10T15:00:00.000Z");
+  const meet = span("Meet", "2026-03-10T14:00:00.000Z", "2026-03-10T15:00:00.000Z");
+  const a = detectMeetings(input({ appSpans: [zoom, meet], audioWindows: [audio(win)] }));
+  const b = detectMeetings(input({ appSpans: [meet, zoom], audioWindows: [audio(win)] }));
+  assert.equal(a[0]?.app, b[0]?.app);
+  assert.equal(a[0]?.app, "Meet"); // tie broken by app name ("Meet" < "Zoom")
+});

package/src/meetings/detect.ts

@@ -0,0 +1,287 @@
+/**
+ * Retrospective meeting detection (issue #1900, Phase 4 slice 1).
+ *
+ * Pure functions over a day's already-ingested signals. A meeting candidate is
+ * either (a) an audio conversation overlapping a meeting-app foreground span
+ * (`app+audio`), (b) a provider meeting with its own boundaries (`provider`),
+ * or (c) a long enough multi-speaker conversation with no app span
+ * (`audio`, the phone-call/in-person fallback). App spans with no overlapping
+ * audio are NOT meetings (you were watching a recording). Candidates are then
+ * merged so a day's meetings never overlap, and each gets a re-run-stable id.
+ */
+
+import { createHash } from "node:crypto";
+
+import type {
+  DetectedMeeting,
+  MeetingAppSpan,
+  MeetingAudioWindow,
+  MeetingDetectionSource,
+  MeetingsDetectionConfig,
+  MeetingsDetectionInput,
+} from "./types.js";
+
+/** Shipped meeting-app patterns (used by the later activity-span derivation). */
+export const DEFAULT_MEETING_APP_PATTERNS: readonly string[] = [
+  "zoom.us",
+  "Zoom",
+  "Microsoft Teams",
+  "teams.microsoft.com",
+  "meet.google.com",
+  "Webex",
+  "Slack", // huddle windows
+  "FaceTime",
+];
+
+export const DEFAULT_MEETINGS_DETECTION_CONFIG: MeetingsDetectionConfig = {
+  appPatterns: [...DEFAULT_MEETING_APP_PATTERNS],
+  minOverlapMinutes: 2,
+  audioOnlyMinMinutes: 15,
+  mergeGapMinutes: 2,
+};
+
+interface Candidate {
+  startMs: number;
+  endMs: number;
+  app?: string;
+  detectionSource: MeetingDetectionSource;
+  sources: string[];
+  title?: string;
+}
+
+function ms(iso: string): number {
+  if (typeof iso !== "string") return Number.NaN;
+  if (!Number.isFinite(Date.parse(iso))) return Number.NaN;
+  // Reject invalid calendar rollovers (e.g. 2026-02-30 → Mar 2) in EITHER `Z`
+  // or explicit-offset form, by validating the wall-clock calendar fields in the
+  // string directly rather than trusting Date.parse's silent normalization.
+  const m = iso.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](?:0\d:[0-5]\d|1[0-3]:[0-5]\d|14:00))$/);
+  if (m === null) return Number.NaN;
+  const [year, month, day, hour, minute, second] = m.slice(1).map(Number);
+  const daysInMonth = month >= 1 && month <= 12 ? new Date(Date.UTC(year, month, 0)).getUTCDate() : 0;
+  if (day < 1 || day > daysInMonth || hour > 23 || minute > 59 || second > 59) return Number.NaN;
+  return Date.parse(iso);
+}
+
+/** Overlap of two half-open [start,end) windows, in milliseconds (0 if disjoint). */
+function overlapMs(aStart: number, aEnd: number, bStart: number, bEnd: number): number {
+  const start = Math.max(aStart, bStart);
+  const end = Math.min(aEnd, bEnd);
+  return end > start ? end - start : 0;
+}
+
+/** Re-run-stable id: same date + exact START instant ⇒ same id. Anchored on the
+ *  start ONLY (end + app both excluded from the hash) so a resync that extends
+ *  the meeting's end (a late source / rejoin) or reassigns its app never
+ *  renumbers an existing record — the start is the stable identity. Full start
+ *  precision (NOT minute-rounded) keeps ids unique even for short provider
+ *  meetings that share a start minute: post-merge meetings are non-overlapping,
+ *  so their start instants are always distinct.
+ *
+ *  A resync that moves a meeting's START earlier (a late source beginning before
+ *  the first-ingested one) does change the id — a stateless pure detector cannot
+ *  know the prior id. Preserving ids across a shifted start is cross-run identity
+ *  work that needs prior-emission state, so it belongs to the fusion/store slice
+ *  (#1900), which matches a re-detected meeting to its stored record by overlap
+ *  and keeps the original id. This function stays pure and deterministic. */
+export function meetingId(date: string, startUtc: string): string {
+  if (!isValidDay(date)) {
+    throw new RangeError(`meetings: invalid day "${date}" for a meeting id; expected a real YYYY-MM-DD.`);
+  }
+  const startMs = ms(startUtc);
+  if (Number.isNaN(startMs)) {
+    throw new RangeError(`meetings: invalid meeting start "${startUtc}" for a meeting id.`);
+  }
+  const anchor = new Date(startMs).toISOString();
+  const hash = createHash("sha256").update(`${date}|${anchor}`, "utf8").digest("hex").slice(0, 8);
+  return `mtg-${date}-${hash}`;
+}
+
+function isFinitePair(a: number, b: number): boolean {
+  return Number.isFinite(a) && Number.isFinite(b) && b > a;
+}
+
+function combineDetection(a: MeetingDetectionSource, b: MeetingDetectionSource): MeetingDetectionSource {
+  if (a === "app+audio" || b === "app+audio") return "app+audio";
+  if (a === "provider" || b === "provider") return "provider";
+  return "audio";
+}
+
+function buildCandidates(
+  audioWindows: MeetingAudioWindow[],
+  appSpans: MeetingAppSpan[],
+  config: MeetingsDetectionConfig,
+): Candidate[] {
+  const minOverlapMs = config.minOverlapMinutes * 60_000;
+  const audioOnlyMs = config.audioOnlyMinMinutes * 60_000;
+  const candidates: Candidate[] = [];
+
+  for (const window of audioWindows) {
+    const startMs = ms(window.startUtc);
+    const endMs = ms(window.endUtc);
+    if (!isFinitePair(startMs, endMs)) continue;
+
+    if (window.providerMeeting === true) {
+      candidates.push({
+        startMs,
+        endMs,
+        detectionSource: "provider",
+        sources: [window.source],
+        ...(window.title !== undefined ? { title: window.title } : {}),
+      });
+      continue;
+    }
+
+    // Best-overlapping meeting-app span (deterministic: max overlap, then earliest start).
+    let bestApp: { span: MeetingAppSpan; overlap: number } | undefined;
+    for (const span of appSpans) {
+      const spanStart = ms(span.startUtc);
+      const spanEnd = ms(span.endUtc);
+      if (!isFinitePair(spanStart, spanEnd)) continue;
+      const overlap = overlapMs(startMs, endMs, spanStart, spanEnd);
+      // Require genuine overlap for an app+audio pairing, even when the caller
+      // sets minOverlapMinutes to 0 — disjoint windows must not pair.
+      if (overlap <= 0 || overlap < minOverlapMs) continue;
+      if (bestApp === undefined || overlap > bestApp.overlap) {
+        bestApp = { span, overlap };
+      } else if (overlap === bestApp.overlap) {
+        // Fully deterministic tie-break so nested/duplicate spans covering the
+        // same window never depend on input order: earliest start, then app
+        // name, then earliest end.
+        const bestStart = ms(bestApp.span.startUtc);
+        const better =
+          spanStart < bestStart ||
+          (spanStart === bestStart &&
+            (span.app < bestApp.span.app ||
+              (span.app === bestApp.span.app && spanEnd < ms(bestApp.span.endUtc))));
+        if (better) bestApp = { span, overlap };
+      }
+    }
+
+    if (bestApp !== undefined) {
+      candidates.push({
+        startMs,
+        endMs,
+        app: bestApp.span.app,
+        detectionSource: "app+audio",
+        sources: [window.source],
+        ...(window.title !== undefined ? { title: window.title } : {}),
+      });
+      continue;
+    }
+
+    // Audio-only fallback: long enough, ≥ 2 distinct non-wearer speakers.
+    if (
+      endMs - startMs >= audioOnlyMs &&
+      Number.isInteger(window.distinctNonWearerSpeakers) &&
+      window.distinctNonWearerSpeakers >= 2
+    ) {
+      candidates.push({
+        startMs,
+        endMs,
+        detectionSource: "audio",
+        sources: [window.source],
+        ...(window.title !== undefined ? { title: window.title } : {}),
+      });
+    }
+  }
+
+  return candidates;
+}
+
+/** Detection-source rank for a total, stable candidate ordering. */
+const DETECTION_RANK: Record<MeetingDetectionSource, number> = {
+  "app+audio": 0,
+  provider: 1,
+  audio: 2,
+};
+
+/** Total order over candidates so equal-time spans resolve deterministically. */
+function candidateOrder(a: Candidate, b: Candidate): number {
+  return (
+    a.startMs - b.startMs ||
+    a.endMs - b.endMs ||
+    DETECTION_RANK[a.detectionSource] - DETECTION_RANK[b.detectionSource] ||
+    (a.app ?? "").localeCompare(b.app ?? "") ||
+    (a.title ?? "").localeCompare(b.title ?? "") ||
+    (a.sources[0] ?? "").localeCompare(b.sources[0] ?? "")
+  );
+}
+
+/**
+ * Merge candidates so the day's meetings never overlap. Two candidates merge
+ * when they overlap, or when they are within `mergeGapMinutes` and share the
+ * same app (rejoin-after-drop). Deterministic via `candidateOrder`.
+ */
+function mergeCandidates(candidates: Candidate[], mergeGapMs: number): Candidate[] {
+  const sorted = [...candidates].sort(candidateOrder);
+  const merged: Candidate[] = [];
+  for (const candidate of sorted) {
+    const prev = merged[merged.length - 1];
+    const overlaps = prev !== undefined && candidate.startMs < prev.endMs;
+    const sameAppAdjacent =
+      prev !== undefined &&
+      prev.app !== undefined &&
+      prev.app === candidate.app &&
+      candidate.startMs - prev.endMs <= mergeGapMs;
+    if (prev !== undefined && (overlaps || sameAppAdjacent)) {
+      prev.endMs = Math.max(prev.endMs, candidate.endMs);
+      prev.app = prev.app ?? candidate.app;
+      prev.detectionSource = combineDetection(prev.detectionSource, candidate.detectionSource);
+      prev.sources = [...new Set([...prev.sources, ...candidate.sources])];
+      prev.title = prev.title ?? candidate.title;
+      continue;
+    }
+    merged.push({ ...candidate, sources: [...candidate.sources] });
+  }
+  return merged;
+}
+
+function assertFiniteNonNegative(name: string, value: number): void {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`meetings config "${name}" must be a finite, non-negative number (got ${value}).`);
+  }
+}
+
+function isValidDay(date: string): boolean {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+  if (m === null) return false;
+  const [, year, month, day] = m.map(Number);
+  const daysInMonth = month >= 1 && month <= 12 ? new Date(Date.UTC(year, month, 0)).getUTCDate() : 0;
+  return day >= 1 && day <= daysInMonth;
+}
+
+function validateConfig(config: MeetingsDetectionConfig): void {
+  assertFiniteNonNegative("minOverlapMinutes", config.minOverlapMinutes);
+  assertFiniteNonNegative("audioOnlyMinMinutes", config.audioOnlyMinMinutes);
+  assertFiniteNonNegative("mergeGapMinutes", config.mergeGapMinutes);
+}
+
+/** Detect the day's non-overlapping meetings from its audio + app-span signals. */
+export function detectMeetings(
+  input: MeetingsDetectionInput,
+  config: MeetingsDetectionConfig = DEFAULT_MEETINGS_DETECTION_CONFIG,
+): DetectedMeeting[] {
+  validateConfig(config);
+  if (!isValidDay(input.date)) {
+    // The day is embedded verbatim in every meeting id (mtg-<date>-<hash>); a
+    // non-YYYY-MM-DD value would produce malformed ids (e.g. slashes).
+    throw new RangeError(`meetings: invalid day "${input.date}"; expected a real YYYY-MM-DD.`);
+  }
+  const candidates = buildCandidates(input.audioWindows, input.appSpans, config);
+  const merged = mergeCandidates(candidates, config.mergeGapMinutes * 60_000);
+  return merged.map((candidate) => {
+    const startUtc = new Date(candidate.startMs).toISOString();
+    const endUtc = new Date(candidate.endMs).toISOString();
+    return {
+      id: meetingId(input.date, startUtc),
+      date: input.date,
+      startUtc,
+      endUtc,
+      ...(candidate.app !== undefined ? { app: candidate.app } : {}),
+      detectionSource: candidate.detectionSource,
+      sources: [...candidate.sources].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+      ...(candidate.title !== undefined ? { title: candidate.title } : {}),
+    };
+  });
+}

package/src/meetings/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public entry for the retrospective meeting-detection subsystem (issue #1900):
+ * pure detection over a day's already-ingested audio + app-span signals.
+ * Re-exported from the package root (`src/index.ts`) so consumers import it from
+ * `@remnic/core`, matching the wearables/activity subsystems' surfacing.
+ */
+export * from "./types.js";
+export * from "./detect.js";