@remnic/core 9.63.12 → 9.64.1

package/src/location/intervals.test.ts

@@ -0,0 +1,202 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  bucketObservationsByDay,
+  dominantPlace,
+  intervalOverlapMs,
+  localDayKey,
+  locationDayWindow,
+  observationSegments,
+} from "./intervals.js";
+import type { LocationObservation, LocationSegment } from "./types.js";
+
+const HOUR_MS = 3_600_000;
+
+function observation(observedAtUtc: string, placeId: string, label = placeId): LocationObservation {
+  return { observedAtUtc, place: { id: placeId, label } };
+}
+
+function segment(startUtc: string, endUtc: string, placeId: string): LocationSegment {
+  return { startUtc, endUtc, place: { id: placeId, label: placeId } };
+}
+
+test("intervalOverlapMs is 0 for disjoint intervals and exact for partial overlap", () => {
+  assert.equal(
+    intervalOverlapMs(
+      { startUtc: "2026-08-17T09:00:00Z", endUtc: "2026-08-17T10:00:00Z" },
+      { startUtc: "2026-08-17T10:00:00Z", endUtc: "2026-08-17T11:00:00Z" },
+    ),
+    0,
+    "half-open intervals that touch at one instant do not overlap",
+  );
+  assert.equal(
+    intervalOverlapMs(
+      { startUtc: "2026-08-17T09:00:00Z", endUtc: "2026-08-17T10:30:00Z" },
+      { startUtc: "2026-08-17T10:00:00Z", endUtc: "2026-08-17T11:00:00Z" },
+    ),
+    30 * 60_000,
+  );
+  assert.equal(
+    intervalOverlapMs(
+      { startUtc: "2026-08-17T09:00:00Z", endUtc: "2026-08-17T12:00:00Z" },
+      { startUtc: "2026-08-17T09:30:00Z", endUtc: "2026-08-17T10:00:00Z" },
+    ),
+    30 * 60_000,
+    "a contained interval overlaps by its own length",
+  );
+  assert.equal(
+    intervalOverlapMs(
+      { startUtc: "2026-08-17T09:00:00Z", endUtc: "2026-08-17T10:00:00Z" },
+      { startUtc: "2026-08-17T09:00:00Z", endUtc: "2026-08-17T10:00:00Z" },
+    ),
+    HOUR_MS,
+    "identical intervals overlap by their full length",
+  );
+});
+
+test("locationDayWindow produces 23h spring-forward and 25h fall-back days in America/Chicago", () => {
+  // US DST 2026: spring forward 2026-03-08, fall back 2026-11-01.
+  const spring = locationDayWindow("2026-03-08", "America/Chicago");
+  assert.equal(
+    Date.parse(spring.endUtc) - Date.parse(spring.startUtc),
+    23 * HOUR_MS,
+    "spring-forward local day is 23 hours",
+  );
+  assert.equal(spring.startUtc, "2026-03-08T06:00:00.000Z");
+
+  const fall = locationDayWindow("2026-11-01", "America/Chicago");
+  assert.equal(
+    Date.parse(fall.endUtc) - Date.parse(fall.startUtc),
+    25 * HOUR_MS,
+    "fall-back local day is 25 hours",
+  );
+  assert.equal(fall.startUtc, "2026-11-01T05:00:00.000Z");
+
+  const utc = locationDayWindow("2026-08-17", "UTC");
+  assert.equal(Date.parse(utc.endUtc) - Date.parse(utc.startUtc), 24 * HOUR_MS);
+  assert.throws(() => locationDayWindow("2026-02-30", "UTC"), RangeError);
+  assert.throws(() => locationDayWindow("2026-8-7", "UTC"), RangeError);
+});
+
+test("localDayKey buckets midnight exactly on the owning day (half-open)", () => {
+  assert.equal(localDayKey("2026-08-17T00:00:00.000Z", "UTC"), "2026-08-17");
+  assert.equal(localDayKey("2026-08-17T23:59:59.999Z", "UTC"), "2026-08-17");
+  assert.equal(localDayKey("2026-08-18T00:00:00.000Z", "UTC"), "2026-08-18");
+  // Zones east of UTC roll over mid-UTC-afternoon.
+  assert.equal(localDayKey("2026-08-17T18:30:00.000Z", "Asia/Tokyo"), "2026-08-18");
+  assert.throws(() => localDayKey("not-an-instant", "UTC"), RangeError);
+});
+
+test("bucketObservationsByDay sorts within each local day bucket", () => {
+  const buckets = bucketObservationsByDay(
+    [
+      observation("2026-08-17T20:00:00Z", "b"),
+      observation("2026-08-17T09:00:00Z", "a"),
+      observation("2026-08-18T01:00:00Z", "c"),
+    ],
+    "UTC",
+  );
+  assert.deepEqual([...buckets.keys()].sort(), ["2026-08-17", "2026-08-18"]);
+  assert.deepEqual(
+    buckets.get("2026-08-17")!.map((item) => item.observedAtUtc),
+    ["2026-08-17T09:00:00Z", "2026-08-17T20:00:00Z"],
+  );
+  assert.throws(
+    () => bucketObservationsByDay([observation("garbage", "a")], "UTC"),
+    RangeError,
+    "a malformed instant is rejected loudly, never bucketed",
+  );
+});
+
+test("observationSegments attributes dwell to the next observation and caps at window end", () => {
+  const window = locationDayWindow("2026-08-17", "UTC");
+  const segments = observationSegments(
+    [observation("2026-08-17T09:00:00Z", "home"), observation("2026-08-17T09:30:00Z", "office")],
+    window,
+    { retainCoordinates: false },
+  );
+  assert.deepEqual(
+    segments.map((item) => [item.startUtc, item.endUtc, item.place.id]),
+    [
+      ["2026-08-17T09:00:00.000Z", "2026-08-17T09:30:00.000Z", "home"],
+      ["2026-08-17T09:30:00.000Z", window.endUtc, "office"],
+    ],
+    "the last observation dwells until the day window ends, never across it",
+  );
+});
+
+test("observationSegments drops coordinates unless retention is enabled", () => {
+  const window = locationDayWindow("2026-08-17", "UTC");
+  const withCoords: LocationObservation[] = [
+    {
+      observedAtUtc: "2026-08-17T09:00:00Z",
+      place: { id: "home", label: "Home", latitude: 41.8781, longitude: -87.6298 },
+    },
+  ];
+  const stripped = observationSegments(withCoords, window, { retainCoordinates: false });
+  assert.equal(stripped[0]!.place.latitude, undefined);
+  assert.equal(stripped[0]!.place.longitude, undefined);
+  const kept = observationSegments(withCoords, window, { retainCoordinates: true });
+  assert.equal(kept[0]!.place.latitude, 41.8781);
+  assert.equal(kept[0]!.place.longitude, -87.6298);
+});
+
+test("observationSegments rejects observations outside the requested window", () => {
+  const window = locationDayWindow("2026-08-17", "UTC");
+  assert.throws(
+    () => observationSegments([observation("2026-08-18T00:00:00Z", "home")], window, { retainCoordinates: false }),
+    RangeError,
+    "the window end is exclusive",
+  );
+  assert.throws(
+    () =>
+      observationSegments([observation("2026-08-16T23:59:59.999Z", "home")], window, { retainCoordinates: false }),
+    RangeError,
+  );
+  assert.throws(
+    () =>
+      observationSegments(
+        [observation("2026-08-17T09:00:00Z", "home")],
+        { startUtc: "2026-08-17T10:00:00Z", endUtc: "2026-08-17T09:00:00Z" },
+        { retainCoordinates: false },
+      ),
+    RangeError,
+    "an inverted window is rejected",
+  );
+});
+
+test("dominantPlace breaks duration ties by earlier first start, then place id", () => {
+  const tieEarlierStart = [
+    segment("2026-08-17T09:00:00Z", "2026-08-17T10:00:00Z", "gym"),
+    segment("2026-08-17T10:00:00Z", "2026-08-17T11:00:00Z", "alpha"),
+    segment("2026-08-17T11:00:00Z", "2026-08-17T12:00:00Z", "alpha"),
+  ];
+  assert.equal(dominantPlace(tieEarlierStart)?.place.id, "alpha");
+
+  const tieSameStartLexicographic = [
+    segment("2026-08-17T09:00:00Z", "2026-08-17T10:00:00Z", "zeta"),
+    segment("2026-08-17T09:00:00Z", "2026-08-17T10:00:00Z", "beta"),
+  ];
+  assert.equal(
+    dominantPlace(tieSameStartLexicographic)?.place.id,
+    "beta",
+    "equal totals and equal first starts fall back to the smaller place id",
+  );
+
+  // Deterministic across orderings (insertion order must never win).
+  const shuffled = [...tieEarlierStart].reverse();
+  assert.equal(dominantPlace(shuffled)?.place.id, "alpha");
+  assert.equal(dominantPlace([]), null);
+});
+
+test("dominantPlace unions overlapping segments so two sources do not double-count", () => {
+  const overlapping = [
+    segment("2026-08-17T09:00:00Z", "2026-08-17T12:00:00Z", "home"),
+    segment("2026-08-17T10:00:00Z", "2026-08-17T11:00:00Z", "office"),
+    segment("2026-08-17T14:00:00Z", "2026-08-17T18:00:00Z", "office"),
+  ];
+  const dominant = dominantPlace(overlapping)!;
+  assert.equal(dominant.place.id, "office");
+  assert.equal(dominant.totalMs, 5 * HOUR_MS, "1h overlapping office + 4h afternoon office");
+});

package/src/location/intervals.ts

@@ -0,0 +1,221 @@
+/**
+ * Location interval math (issue #2044).
+ *
+ * Pure, deterministic helpers over UTC ISO-8601 instants: half-open
+ * [start, end) day windows (reusing the DST-correct activity day-window), IANA
+ * local-day bucketing, overlap, observation→segment dwell, and dominant-place
+ * selection with stable tie-breaking. No IO, no clocks, no randomness.
+ */
+
+import { activityDayWindow, isValidActivityDate } from "../activity/digest.js";
+import type { LocationObservation, LocationPlace, LocationSegment } from "./types.js";
+
+export function isValidLocationDate(date: string): boolean {
+  return isValidActivityDate(date);
+}
+
+/** Half-open [start, end) UTC ISO bounds of a local day. */
+export function locationDayWindow(date: string, timezone: string): { startUtc: string; endUtc: string } {
+  if (!isValidActivityDate(date)) {
+    throw new RangeError(`Invalid location date "${date}"; expected a real YYYY-MM-DD day.`);
+  }
+  return activityDayWindow(date, timezone);
+}
+
+function assertFiniteInstant(iso: string, what: string): number {
+  const ms = Date.parse(iso);
+  if (typeof iso !== "string" || !Number.isFinite(ms)) {
+    throw new RangeError(`${what} must be a UTC ISO-8601 instant; got "${String(iso)}"`);
+  }
+  return ms;
+}
+
+/** The IANA local calendar day (YYYY-MM-DD) an instant falls in. */
+export function localDayKey(instantUtc: string, timezone: string): string {
+  assertFiniteInstant(instantUtc, "instantUtc");
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(new Date(instantUtc));
+}
+
+function compareObservations(a: LocationObservation, b: LocationObservation): number {
+  if (a.observedAtUtc !== b.observedAtUtc) {
+    return a.observedAtUtc < b.observedAtUtc ? -1 : 1;
+  }
+  // Total comparator (§12): equal-key observations fall back to place id so
+  // ordering — and therefore dwell attribution — is deterministic.
+  if (a.place.id !== b.place.id) {
+    return a.place.id < b.place.id ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Bucket observations into their IANA local days, sorted within each day. */
+export function bucketObservationsByDay(
+  observations: readonly LocationObservation[],
+  timezone: string,
+): Map<string, LocationObservation[]> {
+  const buckets = new Map<string, LocationObservation[]>();
+  for (const observation of observations) {
+    assertFiniteInstant(observation.observedAtUtc, "observation observedAtUtc");
+    const key = localDayKey(observation.observedAtUtc, timezone);
+    const bucket = buckets.get(key);
+    if (bucket === undefined) buckets.set(key, [observation]);
+    else bucket.push(observation);
+  }
+  for (const bucket of buckets.values()) bucket.sort(compareObservations);
+  return buckets;
+}
+
+/** Overlap in ms of two half-open intervals; 0 when disjoint. */
+export function intervalOverlapMs(
+  a: { startUtc: string; endUtc: string },
+  b: { startUtc: string; endUtc: string },
+): number {
+  const overlap =
+    Math.min(Date.parse(a.endUtc), Date.parse(b.endUtc)) - Math.max(Date.parse(a.startUtc), Date.parse(b.startUtc));
+  return Math.max(0, overlap);
+}
+
+function placeForSegment(place: LocationPlace, retainCoordinates: boolean): LocationPlace {
+  if (retainCoordinates || place.latitude === undefined || place.longitude === undefined) {
+    return place;
+  }
+  return {
+    id: place.id,
+    label: place.label,
+    ...(place.kind === undefined ? {} : { kind: place.kind }),
+  };
+}
+
+/**
+ * Derive place-visit segments from a day's observations: each observation
+ * covers [its instant, the next observation's instant ∩ window end). The last
+ * observation is capped by the window end, so dwell never crosses the day
+ * boundary. Out-of-window observations are a provider contract violation and
+ * are rejected loudly rather than silently reshaping the day. Coordinates are
+ * stripped unless `retainCoordinates` is set.
+ */
+export function observationSegments(
+  observations: readonly LocationObservation[],
+  window: { startUtc: string; endUtc: string },
+  options: { retainCoordinates: boolean },
+): LocationSegment[] {
+  const startMs = assertFiniteInstant(window.startUtc, "window startUtc");
+  const endMs = assertFiniteInstant(window.endUtc, "window endUtc");
+  if (startMs >= endMs) {
+    throw new RangeError("location window must satisfy startUtc < endUtc");
+  }
+  const ordered = [...observations].sort(compareObservations);
+  const segments: LocationSegment[] = [];
+  for (let index = 0; index < ordered.length; index += 1) {
+    const current = ordered[index]!;
+    const currentMs = Date.parse(current.observedAtUtc);
+    if (currentMs < startMs || currentMs >= endMs) {
+      throw new RangeError(
+        `location observation at "${current.observedAtUtc}" falls outside the requested [${window.startUtc}, ${window.endUtc}) window`,
+      );
+    }
+    const nextMs =
+      index + 1 < ordered.length ? Date.parse(ordered[index + 1]!.observedAtUtc) : endMs;
+    const segmentEndMs = Math.min(nextMs, endMs);
+    if (currentMs >= segmentEndMs) continue;
+    segments.push({
+      startUtc: new Date(currentMs).toISOString(),
+      endUtc: new Date(segmentEndMs).toISOString(),
+      place: placeForSegment(current.place, options.retainCoordinates),
+    });
+  }
+  return segments;
+}
+
+/** Total time a place was occupied (union of its segment intervals, ms). */
+export interface PlaceDuration {
+  place: LocationPlace;
+  totalMs: number;
+  /** Earliest segment start contributing to this place's total. */
+  firstStartUtc: string;
+}
+
+function unionIntervalMs(segments: readonly LocationSegment[]): number {
+  // Merge overlapping [start, end) intervals per place so two providers
+  // observing the same visit do not double-count its duration.
+  const bounds = segments
+    .map((segment) => ({ start: Date.parse(segment.startUtc), end: Date.parse(segment.endUtc) }))
+    .sort((a, b) => (a.start !== b.start ? a.start - b.start : a.end - b.end));
+  let total = 0;
+  let sweepStart: number | null = null;
+  let sweepEnd = 0;
+  for (const bound of bounds) {
+    if (sweepStart === null || bound.start > sweepEnd) {
+      if (sweepStart !== null) total += sweepEnd - sweepStart;
+      sweepStart = bound.start;
+      sweepEnd = bound.end;
+    } else if (bound.end > sweepEnd) {
+      sweepEnd = bound.end;
+    }
+  }
+  if (sweepStart !== null) total += sweepEnd - sweepStart;
+  return total;
+}
+
+/** Per-place totals across every segment given (multi-source safe). */
+export function placeDurations(segments: readonly LocationSegment[]): PlaceDuration[] {
+  const byPlace = new Map<string, { place: LocationPlace; segments: LocationSegment[]; firstStartUtc: string }>();
+  for (const segment of segments) {
+    const existing = byPlace.get(segment.place.id);
+    if (existing === undefined) {
+      byPlace.set(segment.place.id, { place: segment.place, segments: [segment], firstStartUtc: segment.startUtc });
+      continue;
+    }
+    existing.segments.push(segment);
+    if (segment.startUtc < existing.firstStartUtc) existing.firstStartUtc = segment.startUtc;
+    // Two providers may label the same place id differently; keep the
+    // lexicographically smallest label so rendering stays deterministic.
+    if (segment.place.label < existing.place.label) existing.place = segment.place;
+  }
+  const durations: PlaceDuration[] = [...byPlace.values()].map((entry) => ({
+    place: entry.place,
+    totalMs: unionIntervalMs(entry.segments),
+    firstStartUtc: entry.firstStartUtc,
+  }));
+  durations.sort((a, b) => {
+    if (a.place.id !== b.place.id) return a.place.id < b.place.id ? -1 : 1;
+    return 0;
+  });
+  return durations;
+}
+
+export interface DominantPlaceResult {
+  place: LocationPlace;
+  totalMs: number;
+}
+
+/**
+ * The place with the longest total occupancy. Ties are stable and
+ * deterministic: earlier first start wins, then the lexicographically smaller
+ * place id — never insertion order.
+ */
+export function dominantPlace(segments: readonly LocationSegment[]): DominantPlaceResult | null {
+  const durations = placeDurations(segments);
+  let best: PlaceDuration | null = null;
+  for (const duration of durations) {
+    if (best === null) {
+      best = duration;
+      continue;
+    }
+    if (duration.totalMs !== best.totalMs) {
+      if (duration.totalMs > best.totalMs) best = duration;
+      continue;
+    }
+    if (duration.firstStartUtc !== best.firstStartUtc) {
+      if (duration.firstStartUtc < best.firstStartUtc) best = duration;
+      continue;
+    }
+    if (duration.place.id < best.place.id) best = duration;
+  }
+  return best === null ? null : { place: best.place, totalMs: best.totalMs };
+}

package/src/location/parse-companions.ts

@@ -0,0 +1,12 @@
+import { parseActivityConfig } from "../activity/config.js";
+import { parseMeetingsConfig } from "../meetings/config.js";
+import { parseProvenanceConfig } from "../provenance.js";
+
+/** Parse capture-adjacent config blocks without location (#2044). */
+export function parseCaptureCompanionConfigs(cfg: Record<string, unknown>) {
+  return {
+    activity: parseActivityConfig(cfg.activity),
+    meetings: parseMeetingsConfig(cfg.meetings),
+    provenance: parseProvenanceConfig(cfg.provenance),
+  };
+}