@remnic/core 9.64.0 → 9.64.1

package/src/location/cli.ts

@@ -0,0 +1,163 @@
+/**
+ * Location surface helpers (issue #2044): status, provider health checks, and
+ * multi-day sync. Pure `@remnic/core` — no optional packages, no host CLI
+ * wiring; a host adapter (or the core CLI, in a later slice) renders these
+ * structured results into its own command surface.
+ */
+
+import { getLocationProvider } from "./registry.js";
+import { isValidLocationDate, localDayKey } from "./intervals.js";
+import { listLocationDayDates, loadLocationSyncState, parseLocationDaySummary, readLocationDay } from "./store.js";
+import { syncLocationDay, type LocationDaySyncOptions, type LocationSourceSyncResult } from "./pipeline.js";
+import type { LocationConfig, LocationProvider } from "./types.js";
+
+export interface LocationSourceStatus {
+  id: string;
+  enabled: boolean;
+  providerRegistered: boolean;
+  lastSyncedAtUtc?: string;
+  trackedDays: number;
+}
+
+export interface LocationDayStatus {
+  date: string;
+  sources: string[];
+  observationCount: number;
+}
+
+export interface LocationStatusReport {
+  enabled: boolean;
+  timezone: string;
+  sources: LocationSourceStatus[];
+  /** Stored day documents, newest first (at most `maxDays`). */
+  recentDays: LocationDayStatus[];
+}
+
+export interface LocationStatusOptions {
+  /** Provider lookup seam (defaults to the registry); tests inject doubles. */
+  getProvider?: (id: string) => LocationProvider | undefined;
+  /** Cap on day documents listed; defaults to 7. */
+  maxDays?: number;
+  now?: () => Date;
+}
+
+export async function locationStatus(
+  config: LocationConfig,
+  memoryDir: string,
+  options: LocationStatusOptions = {},
+): Promise<LocationStatusReport> {
+  const resolveProvider = options.getProvider ?? getLocationProvider;
+  const state = await loadLocationSyncState(memoryDir);
+  const sources: LocationSourceStatus[] = config.sources.map((source) => {
+    const sourceState = state.sources[source.id];
+    return {
+      id: source.id,
+      enabled: source.enabled,
+      providerRegistered: resolveProvider(source.id) !== undefined,
+      ...(sourceState?.lastSyncedAtUtc === undefined ? {} : { lastSyncedAtUtc: sourceState.lastSyncedAtUtc }),
+      trackedDays: Object.keys(sourceState?.days ?? {}).length,
+    };
+  });
+
+  const maxDays = options.maxDays ?? 7;
+  const recentDays: LocationDayStatus[] = [];
+  for (const date of (await listLocationDayDates(memoryDir)).slice(0, Math.max(0, maxDays))) {
+    const raw = await readLocationDay(memoryDir, date);
+    const summary = raw === null ? null : parseLocationDaySummary(raw);
+    recentDays.push({
+      date,
+      sources: summary?.sources ?? [],
+      observationCount: summary?.observationCount ?? 0,
+    });
+  }
+  return { enabled: config.enabled, timezone: config.timezone, sources, recentDays };
+}
+
+export interface LocationSourceCheckResult {
+  id: string;
+  ok: boolean;
+  detail?: string;
+  skipped?: "location-disabled" | "source-disabled" | "provider-not-registered";
+}
+
+export interface LocationCheckOptions {
+  signal?: AbortSignal;
+  getProvider?: (id: string) => LocationProvider | undefined;
+}
+
+/** Probe every configured provider's health. The master gate short-circuits. */
+export async function checkLocationSources(
+  config: LocationConfig,
+  options: LocationCheckOptions = {},
+): Promise<LocationSourceCheckResult[]> {
+  if (!config.enabled) {
+    return config.sources.map((source) => ({ id: source.id, ok: false, skipped: "location-disabled" as const }));
+  }
+  const resolveProvider = options.getProvider ?? getLocationProvider;
+  const results: LocationSourceCheckResult[] = [];
+  for (const source of config.sources) {
+    if (!source.enabled) {
+      results.push({ id: source.id, ok: false, skipped: "source-disabled" });
+      continue;
+    }
+    const provider = resolveProvider(source.id);
+    if (provider === undefined) {
+      results.push({ id: source.id, ok: false, skipped: "provider-not-registered" });
+      continue;
+    }
+    try {
+      const check = await provider.verify(options.signal);
+      results.push({
+        id: source.id,
+        ok: check.ok,
+        ...(check.detail === undefined || check.detail.length === 0 ? {} : { detail: check.detail }),
+      });
+    } catch (error) {
+      results.push({ id: source.id, ok: false, detail: error instanceof Error ? error.name : "provider error" });
+    }
+  }
+  return results;
+}
+
+function shiftIsoDate(date: string, days: number): string {
+  const parsed = new Date(`${date}T00:00:00Z`);
+  parsed.setUTCDate(parsed.getUTCDate() + days);
+  return parsed.toISOString().slice(0, 10);
+}
+
+export interface LocationSyncRunOptions
+  extends Omit<LocationDaySyncOptions, "config" | "date" | "memoryDir"> {
+  config: LocationConfig;
+  memoryDir: string;
+  /** Exclusive end date (local YYYY-MM-DD); defaults to today in config.timezone. */
+  endDate?: string;
+  /** Number of days to sync ending at endDate; defaults to config.syncDays. */
+  days?: number;
+  now?: () => Date;
+}
+/**
+ * Sync the trailing `days` local days ending AT `endDate` (inclusive).
+ * `endDate` defaults to yesterday in config.timezone (today is incomplete);
+ * days run oldest-first so a failure stops before newer days, matching the
+ * incremental-sync intent of `syncDays`.
+ */
+export async function syncLocation(
+  options: LocationSyncRunOptions,
+): Promise<Array<{ date: string; results: LocationSourceSyncResult[] }>> {
+  const { config, memoryDir, endDate, days, ...rest } = options;
+  if (endDate !== undefined && !isValidLocationDate(endDate)) {
+    throw new RangeError(`Invalid location endDate "${endDate}"; expected a real YYYY-MM-DD day.`);
+  }
+  const now = rest.now ?? (() => new Date());
+  const end = endDate ?? shiftIsoDate(localDayKey(now().toISOString(), config.timezone), -1);
+  const count = days ?? config.syncDays;
+  if (!Number.isInteger(count) || count < 1 || count > 90) {
+    throw new RangeError("location sync days must be an integer from 1 to 90");
+  }
+  const runs: Array<{ date: string; results: LocationSourceSyncResult[] }> = [];
+  for (let offset = count; offset >= 1; offset -= 1) {
+    const date = shiftIsoDate(end, -(offset - 1));
+    runs.push({ date, results: await syncLocationDay({ ...rest, config, memoryDir, date, now }) });
+  }
+  return runs;
+}

package/src/location/config.test.ts

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { defaultLocationConfig, parseLocationConfig } from "./config.js";
+
+test("parseLocationConfig defaults to an inert configuration", () => {
+  assert.deepEqual(defaultLocationConfig(), {
+    enabled: false,
+    timezone: "UTC",
+    syncDays: 1,
+    retainCoordinates: false,
+    sources: [],
+  });
+  assert.deepEqual(parseLocationConfig(undefined), defaultLocationConfig());
+  assert.deepEqual(parseLocationConfig(null), defaultLocationConfig());
+});
+
+test("parseLocationConfig treats string false gates as disabled", () => {
+  assert.equal(parseLocationConfig({ enabled: "false", sources: [{ id: "reitti" }] }).enabled, false);
+  assert.equal(
+    parseLocationConfig({
+      enabled: true,
+      retainCoordinates: "0",
+      sources: [{ id: "reitti", enabled: "false" }],
+    }).retainCoordinates,
+    false,
+  );
+});
+
+test("parseLocationConfig rejects unrecognized gate values instead of defaulting", () => {
+  assert.throws(() => parseLocationConfig({ enabled: "maybe" }), TypeError);
+  assert.throws(() => parseLocationConfig({ retainCoordinates: 42 }), TypeError);
+  assert.throws(() => parseLocationConfig({ sources: [{ id: "reitti", enabled: "nope" }] }), TypeError);
+});
+
+test("parseLocationConfig validates the timezone at parse time", () => {
+  assert.throws(() => parseLocationConfig({ timezone: "Mars/Olympus" }), RangeError);
+  assert.equal(parseLocationConfig({ timezone: "America/Chicago" }).timezone, "America/Chicago");
+  assert.throws(() => parseLocationConfig({ timezone: "" }), TypeError);
+});
+
+test("parseLocationConfig enforces the syncDays integer range", () => {
+  assert.equal(parseLocationConfig({ syncDays: "3" }).syncDays, 3);
+  assert.throws(() => parseLocationConfig({ syncDays: 0 }), RangeError);
+  assert.throws(() => parseLocationConfig({ syncDays: 1.5 }), RangeError);
+  assert.throws(() => parseLocationConfig({ syncDays: 91 }), RangeError);
+  assert.throws(() => parseLocationConfig({ syncDays: "abc" }), TypeError);
+});
+
+test("parseLocationConfig requires a source when enabled", () => {
+  assert.throws(() => parseLocationConfig({ enabled: true }), RangeError);
+  assert.throws(() => parseLocationConfig({ enabled: true, sources: "reitti" }), TypeError);
+  const parsed = parseLocationConfig({ enabled: true, sources: [{ id: "reitti" }] });
+  assert.deepEqual(parsed.sources, [{ id: "reitti", enabled: true }]);
+});
+
+test("parseLocationConfig rejects malformed source entries", () => {
+  assert.throws(() => parseLocationConfig({ sources: [{ id: "" }] }), TypeError);
+  assert.throws(() => parseLocationConfig({ sources: [{}] }), TypeError);
+  assert.throws(() => parseLocationConfig({ sources: [{ id: "Bad_Id" }] }), RangeError);
+  assert.throws(() => parseLocationConfig({ sources: [{ id: "../escape" }] }), RangeError);
+  assert.throws(() => parseLocationConfig({ sources: ["reitti"] }), TypeError);
+});
+
+test("parseLocationConfig rejects duplicate source ids", () => {
+  assert.throws(
+    () => parseLocationConfig({ enabled: true, sources: [{ id: "reitti" }, { id: "reitti", enabled: false }] }),
+    RangeError,
+  );
+});
+
+test("parseLocationConfig rejects non-object blocks", () => {
+  assert.throws(() => parseLocationConfig("nope"), TypeError);
+  assert.throws(() => parseLocationConfig([1, 2]), TypeError);
+});

package/src/location/config.ts

@@ -0,0 +1,105 @@
+import { coerceBooleanLike, coerceNumber } from "../connectors/coerce.js";
+import { assertValidTimezone } from "../activity/digest.js";
+import type { LocationConfig, LocationSourceConfig } from "./types.js";
+
+const PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+/** The inert default: disabled, UTC days, one day per run, no sources, no coordinates. */
+export function defaultLocationConfig(): LocationConfig {
+  return {
+    enabled: false,
+    timezone: "UTC",
+    syncDays: 1,
+    retainCoordinates: false,
+    sources: [],
+  };
+}
+
+function asRecord(value: unknown, name: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError(`${name} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function optionalNonEmptyString(value: unknown, name: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.length === 0) throw new TypeError(`${name} must be a non-empty string`);
+  return value;
+}
+
+function parseLocationSource(value: unknown): LocationSourceConfig {
+  const raw = asRecord(value, "location source");
+  const id = optionalNonEmptyString(raw.id, "location source id");
+  if (id === undefined) {
+    throw new TypeError("location source requires id");
+  }
+  if (!PROVIDER_ID_PATTERN.test(id)) {
+    throw new RangeError(
+      `location source id must be a lowercase kebab string (a-z, 0-9, hyphens): got "${id}"`,
+    );
+  }
+  const enabledValue = coerceBooleanLike(raw.enabled, "location source enabled");
+  if (raw.enabled !== undefined && enabledValue === undefined) {
+    throw new TypeError(`location source '${id}' enabled must be a boolean`);
+  }
+  return { id, enabled: enabledValue ?? true };
+}
+
+/**
+ * Parse the unified `location.*` block. `enabled` gates everything and
+ * requires at least one source; a source's own `enabled` gates that source
+ * only. `retainCoordinates` defaults to `false` — coordinates are privacy
+ * data and are dropped everywhere unless explicitly retained.
+ */
+export function parseLocationConfig(raw: unknown): LocationConfig {
+  const defaults = defaultLocationConfig();
+  if (raw === undefined || raw === null) {
+    return { ...defaults };
+  }
+  const config = asRecord(raw, "location");
+  const enabledValue = coerceBooleanLike(config.enabled, "location.enabled");
+  if (config.enabled !== undefined && enabledValue === undefined) {
+    throw new TypeError("location.enabled must be a boolean");
+  }
+  const enabled = enabledValue ?? false;
+
+  const timezone = optionalNonEmptyString(config.timezone, "location.timezone") ?? "UTC";
+  // Validate the IANA zone at parse so a typo fails at config load, not
+  // mid-sync after some sources may already have advanced their state.
+  assertValidTimezone(timezone);
+
+  const syncDaysValue = coerceNumber(config.syncDays, "location.syncDays");
+  if (config.syncDays !== undefined && syncDaysValue === undefined) {
+    throw new TypeError("location.syncDays must be a finite number");
+  }
+  const syncDays = syncDaysValue ?? 1;
+  if (!Number.isInteger(syncDays) || syncDays < 1 || syncDays > 90) {
+    throw new RangeError("location.syncDays must be an integer from 1 to 90");
+  }
+
+  const retainCoordinatesValue = coerceBooleanLike(config.retainCoordinates, "location.retainCoordinates");
+  if (config.retainCoordinates !== undefined && retainCoordinatesValue === undefined) {
+    throw new TypeError("location.retainCoordinates must be a boolean");
+  }
+  const retainCoordinates = retainCoordinatesValue ?? false;
+
+  if (config.sources !== undefined && !Array.isArray(config.sources)) {
+    throw new TypeError("location.sources must be an array");
+  }
+  const sources = (config.sources ?? []).map(parseLocationSource);
+  // Day payloads and sync state are keyed on source id; two sources sharing
+  // an id would overwrite each other's state. Reject the collision at parse.
+  const ids = new Set<string>();
+  for (const source of sources) {
+    if (ids.has(source.id)) {
+      throw new RangeError(`location source id must be unique: ${source.id}`);
+    }
+    ids.add(source.id);
+  }
+  if (enabled && sources.length === 0) {
+    throw new RangeError("location.enabled requires at least one source");
+  }
+
+  return { enabled, timezone, syncDays, retainCoordinates, sources };
+}

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