@remnic/core 9.64.0 → 9.64.1

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),
+  };
+}

package/src/location/pipeline.test.ts

@@ -0,0 +1,324 @@
+import assert from "node:assert/strict";
+import { access, mkdir, mkdtemp, readFile, rm, symlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { syncLocationDay, sanitizeProviderError } from "./pipeline.js";
+import { parseLocationConfig } from "./config.js";
+import { locationDayFilePath, locationSyncStateFilePath, loadLocationSyncState } from "./store.js";
+import type { LocationConfig, LocationObservation, LocationProvider } from "./types.js";
+
+function config(overrides: Record<string, unknown> = {}): LocationConfig {
+  return parseLocationConfig({
+    enabled: true,
+    sources: [{ id: "fixture" }],
+    ...overrides,
+  });
+}
+
+function observationAt(observedAtUtc: string, placeId: string): LocationObservation {
+  return {
+    observedAtUtc,
+    place: { id: placeId, label: placeId === "home" ? "Home" : placeId, latitude: 41.8781, longitude: -87.6298 },
+  };
+}
+
+function provider(
+  pages: LocationObservation[][],
+  options: { failWith?: Error } = {},
+): LocationProvider {
+  return {
+    id: "fixture",
+    displayName: "Fixture",
+    async verify() {
+      return { ok: true };
+    },
+    async fetchObservations() {
+      if (options.failWith !== undefined) throw options.failWith;
+      const remaining = pages.splice(0, 1);
+      return { observations: remaining[0] ?? [], nextCursor: null };
+    },
+  };
+}
+
+const REGISTRY = new Map<string, LocationProvider>();
+function withProviders(providers: LocationProvider[]): (id: string) => LocationProvider | undefined {
+  REGISTRY.clear();
+  for (const item of providers) REGISTRY.set(item.id, item);
+  return (id: string) => REGISTRY.get(id);
+}
+
+test("the master gate short-circuits every path: no providers, no filesystem", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-pipeline-"));
+  try {
+    let fetches = 0;
+    const getProvider = withProviders([
+      {
+        id: "fixture",
+        displayName: "Fixture",
+        async verify() {
+          return { ok: true };
+        },
+        async fetchObservations() {
+          fetches += 1;
+          return { observations: [], nextCursor: null };
+        },
+      },
+    ]);
+    const disabled = parseLocationConfig({ enabled: false, sources: [{ id: "fixture" }] });
+    const results = await syncLocationDay({ config: disabled, memoryDir, date: "2026-08-17", getProvider });
+    assert.deepEqual(results, []);
+    assert.equal(fetches, 0);
+    await assert.rejects(() => access(locationSyncStateFilePath(memoryDir)), /ENOENT/);
+    await assert.rejects(() => access(locationDayFilePath(memoryDir, "2026-08-17")), /ENOENT/);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a disabled source is skipped without contacting its provider", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-pipeline-"));
+  try {
+    let fetches = 0;
+    const getProvider = withProviders([
+      {
+        id: "fixture",
+        displayName: "Fixture",
+        async verify() {
+          return { ok: true };
+        },
+        async fetchObservations() {
+          fetches += 1;
+          return { observations: [], nextCursor: null };
+        },
+      },
+    ]);
+    const results = await syncLocationDay({
+      config: config({ sources: [{ id: "fixture", enabled: false }] }),
+      memoryDir,
+      date: "2026-08-17",
+      getProvider,
+    });
+    assert.deepEqual(results, [
+      {
+        sourceId: "fixture",
+        status: "skipped",
+        skipReason: "source-disabled",
+        fetched: 0,
+        dayWritten: false,
+        stateSaved: false,
+      },
+    ]);
+    assert.equal(fetches, 0);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a configured source whose provider is not registered is skipped, not failed", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-pipeline-"));
+  try {
+    const results = await syncLocationDay({
+      config: config(),
+      memoryDir,
+      date: "2026-08-17",
+      getProvider: () => undefined,
+    });
+    assert.equal(results[0]?.status, "skipped");
+    assert.equal(results[0]?.skipReason, "provider-not-registered");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a successful sync writes the day document and only then advances state", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-pipeline-"));
+  try {
+    const getProvider = withProviders([
+      provider([[observationAt("2026-08-17T09:00:00Z", "home"), observationAt("2026-08-17T12:00:00Z", "office")]]),
+    ]);
+    const results = await syncLocationDay({
+      config: config(),
+      memoryDir,
+      date: "2026-08-17",
+      getProvider,
+      now: () => new Date("2026-08-18T00:00:05.000Z"),
+    });
+    assert.deepEqual(
+      results.map((result) => [result.status, result.fetched, result.dayWritten, result.stateSaved]),
+      [["synced", 2, true, true]],
+    );
+    const day = await readFile(locationDayFilePath(memoryDir, "2026-08-17"), "utf-8");
+    assert.match(day, /kind: "location-day"/);
+    assert.match(day, /Home: 3h 00m/);
+    assert.doesNotMatch(day, /41\.8781/, "coordinates are not persisted unless retention is enabled");
+    const state = await loadLocationSyncState(memoryDir);
+    assert.equal(state.sources.fixture?.lastSyncedAtUtc, "2026-08-18T00:00:05.000Z");
+    assert.equal(state.sources.fixture?.days?.["2026-08-17"]?.observationCount, 2);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("an empty fetch is a successful sync, not a provider failure", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-pipeline-"));
+  try {
+    const getProvider = withProviders([provider([[]])]);
+    const results = await syncLocationDay({ config: config(), memoryDir, date: "2026-08-17", getProvider });
+    assert.deepEqual(
+      results.map((result) => [result.status, result.fetched, result.dayWritten, result.stateSaved, result.error]),
+      [["synced", 0, false, true, undefined]],
+    );
+    await assert.rejects(() => access(locationDayFilePath(memoryDir, "2026-08-17")), /ENOENT/);
+    const state = await loadLocationSyncState(memoryDir);
+    assert.notEqual(state.sources.fixture, undefined, "state advances for an empty day");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a provider failure fails only that source and never advances its state", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-pipeline-"));
+  try {
+    const getProvider = withProviders([
+      provider([], { failWith: new Error("Bearer sk-live-abc123 failed at http://api.example/v1?key=hunter2 near 41.8781,-87.6298") }),
+      (() => {
+        const healthy = provider([[observationAt("2026-08-17T08:00:00Z", "gym")]]);
+        return { ...healthy, id: "healthy", displayName: "Healthy" };
+      })(),
+    ]);
+    const results = await syncLocationDay({
+      config: config({ sources: [{ id: "fixture" }, { id: "healthy" }] }),
+      memoryDir,
+      date: "2026-08-17",
+      getProvider,
+    });
+    const failed = results.find((result) => result.sourceId === "fixture")!;
+    assert.equal(failed.status, "failed");
+    assert.equal(failed.stateSaved, false);
+    assert.doesNotMatch(failed.error ?? "", /sk-live-abc123|hunter2|41\.8781/);
+    assert.match(failed.error ?? "", /\[redacted\]/);
+    assert.match(failed.error ?? "", /\[coordinates\]/);
+    const healthy = results.find((result) => result.sourceId === "healthy")!;
+    assert.equal(healthy.status, "synced");
+    const state = await loadLocationSyncState(memoryDir);
+    assert.equal(state.sources.fixture, undefined, "the failed source's state was never written");
+    assert.notEqual(state.sources.healthy, undefined);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("state is not advanced when the day write fails (durable write before state)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-location-pipeline-"));
+  try {
+    const memoryDir = path.join(root, "memory");
+    await mkdir(memoryDir, { recursive: true });
+    // A symlinked locations root fails containment BEFORE any write lands.
+    await mkdir(path.join(root, "elsewhere"), { recursive: true });
+    await symlink(path.join(root, "elsewhere"), path.join(memoryDir, "locations"));
+    const getProvider = withProviders([provider([[observationAt("2026-08-17T09:00:00Z", "home")]])]);
+    const results = await syncLocationDay({ config: config(), memoryDir, date: "2026-08-17", getProvider });
+    assert.equal(results[0]?.status, "failed");
+    assert.equal(results[0]?.stateSaved, false);
+    await assert.rejects(() => access(locationSyncStateFilePath(memoryDir)), /ENOENT/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("a re-sync of one source preserves the other sources' sections in the day file", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-pipeline-"));
+  try {
+    const alpha = { ...provider([[observationAt("2026-08-17T09:00:00Z", "home")]]), id: "alpha", displayName: "Alpha" };
+    const beta = { ...provider([[observationAt("2026-08-17T13:00:00Z", "office")]]), id: "beta", displayName: "Beta" };
+    let getProvider = withProviders([alpha, beta]);
+    await syncLocationDay({
+      config: config({ sources: [{ id: "alpha" }, { id: "beta" }] }),
+      memoryDir,
+      date: "2026-08-17",
+      getProvider,
+    });
+    let day = await readFile(locationDayFilePath(memoryDir, "2026-08-17"), "utf-8");
+    assert.match(day, /## Timeline — Alpha/);
+    assert.match(day, /## Timeline — Beta/);
+
+    // Re-sync only alpha with fresh observations; beta's section must survive
+    // from sync state without contacting beta again.
+    const alphaRefreshed = {
+      ...provider([[observationAt("2026-08-17T09:00:00Z", "cafe")]]),
+      id: "alpha",
+      displayName: "Alpha",
+    };
+    getProvider = withProviders([alphaRefreshed]);
+    const results = await syncLocationDay({
+      config: config({ sources: [{ id: "alpha" }] }),
+      memoryDir,
+      date: "2026-08-17",
+      getProvider,
+    });
+    assert.equal(results[0]?.status, "synced");
+    day = await readFile(locationDayFilePath(memoryDir, "2026-08-17"), "utf-8");
+    assert.match(day, /## Timeline — Alpha/);
+    assert.match(day, /## Timeline — Beta/, "the untouched source's day payload survives from state");
+    assert.match(day, /cafe/);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("retainCoordinates: true persists coordinates end to end", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-pipeline-"));
+  try {
+    const getProvider = withProviders([provider([[observationAt("2026-08-17T09:00:00Z", "home")]])]);
+    await syncLocationDay({
+      config: config({ retainCoordinates: true }),
+      memoryDir,
+      date: "2026-08-17",
+      getProvider,
+    });
+    const day = await readFile(locationDayFilePath(memoryDir, "2026-08-17"), "utf-8");
+    assert.match(day, /@ 41\.8781,-87\.6298/);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("malformed provider output is rejected loudly", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-pipeline-"));
+  try {
+    const broken: LocationProvider = {
+      id: "fixture",
+      displayName: "Fixture",
+      async verify() {
+        return { ok: true };
+      },
+      async fetchObservations() {
+        return {
+          observations: [{ observedAtUtc: "garbage", place: { id: "home", label: "Home" } }],
+          nextCursor: null,
+        };
+      },
+    };
+    const results = await syncLocationDay({
+      config: config(),
+      memoryDir,
+      date: "2026-08-17",
+      getProvider: withProviders([broken]),
+    });
+    assert.equal(results[0]?.status, "failed");
+    await assert.rejects(() => access(locationSyncStateFilePath(memoryDir)), /ENOENT/);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("sanitizeProviderError strips credentials, query strings, and coordinates", () => {
+  const sanitized = sanitizeProviderError(
+    new Error("GET http://x.example/v1?token=sekrit failed: Bearer abc.def.ghi at 41.878113,-87.629798"),
+  );
+  assert.doesNotMatch(sanitized, /sekrit|abc\.def\.ghi|41\.878113/);
+  assert.match(sanitized, /\[redacted\]/);
+  assert.match(sanitized, /\[coordinates\]/);
+});