@remnic/core 9.63.12 → 9.64.1

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\]/);
+});

package/src/location/pipeline.ts

@@ -0,0 +1,245 @@
+/**
+ * Location day-sync pipeline (issue #2044).
+ *
+ * For one local day, each configured (enabled, registered) provider's
+ * observations are fetched over the day's half-open UTC window, folded into
+ * place-visit segments, merged with the other sources' last-known day
+ * payloads from sync state, and rendered to the day document. Sync state
+ * advances only AFTER the day document (when any) is durable, so a failed
+ * write never moves the watermark past data that did not land. An empty
+ * fetch is a successful sync — never conflated with a provider failure
+ * (AGENTS.md rule 22).
+ */
+
+import { getLocationProvider } from "./registry.js";
+import { locationDayWindow, observationSegments } from "./intervals.js";
+import {
+  composeLocationDayBody,
+  composeLocationDayMeta,
+  loadLocationSyncState,
+  serializeLocationDay,
+  updateLocationSourceDay,
+  writeLocationDay,
+  type LocationDaySourceEntry,
+} from "./store.js";
+import type { LocationConfig, LocationObservation, LocationProvider, LocationSegment } from "./types.js";
+
+const MAX_SYNC_PAGES = 10_000;
+
+export interface LocationDaySyncOptions {
+  config: LocationConfig;
+  memoryDir: string;
+  date: string;
+  signal?: AbortSignal;
+  /** Runaway-pagination guard; defaults to MAX_SYNC_PAGES. */
+  maxPages?: number;
+  now?: () => Date;
+  /** Provider lookup seam (defaults to the registry); tests inject doubles. */
+  getProvider?: (id: string) => LocationProvider | undefined;
+}
+
+export interface LocationSourceSyncResult {
+  sourceId: string;
+  status: "synced" | "skipped" | "failed";
+  skipReason?: "source-disabled" | "provider-not-registered";
+  fetched: number;
+  dayWritten: boolean;
+  stateSaved: boolean;
+  /** Sanitized provider error (no tokens, URLs, or coordinates). */
+  error?: string;
+}
+
+/** Redact credential, URL query, and coordinate shapes from a provider error. */
+export function sanitizeProviderError(error: unknown): string {
+  const raw = error instanceof Error ? error.message : String(error);
+  return raw
+    .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]")
+    .replace(/[?#][^ \t"']*/g, "[redacted]")
+    .replace(/[+-]?\d+\.\d{3,},\s?[+-]?\d+\.\d{3,}/g, "[coordinates]")
+    .slice(0, 300);
+}
+
+function assertValidObservation(observation: LocationObservation): void {
+  if (typeof observation !== "object" || observation === null) {
+    throw new TypeError("location provider returned a non-object observation");
+  }
+  if (typeof observation.observedAtUtc !== "string" || !Number.isFinite(Date.parse(observation.observedAtUtc))) {
+    throw new TypeError("location provider returned an observation with an invalid observedAtUtc");
+  }
+  const place = observation.place;
+  if (typeof place !== "object" || place === null || typeof place.id !== "string" || place.id.length === 0) {
+    throw new TypeError("location provider returned an observation without a valid place");
+  }
+  if (typeof place.label !== "string" || place.label.trim().length === 0) {
+    throw new TypeError(`location provider returned place '${place.id}' without a label`);
+  }
+}
+
+/** Fetch every observation one provider holds for the window, all pages. */
+async function fetchWindow(
+  provider: LocationProvider,
+  window: { startUtc: string; endUtc: string },
+  options: LocationDaySyncOptions,
+): Promise<LocationObservation[]> {
+  const maxPages = options.maxPages ?? MAX_SYNC_PAGES;
+  if (!Number.isInteger(maxPages) || maxPages < 1) {
+    throw new RangeError("location sync maxPages must be a positive integer");
+  }
+  const observations: LocationObservation[] = [];
+  const seenCursors = new Set<string>();
+  let cursor: string | null = null;
+  let pages = 0;
+  let completed = false;
+  while (pages < maxPages) {
+    options.signal?.throwIfAborted();
+    const page = await provider.fetchObservations({
+      startUtc: window.startUtc,
+      endUtc: window.endUtc,
+      cursor,
+      signal: options.signal,
+    });
+    pages += 1;
+    for (const observation of page.observations) assertValidObservation(observation);
+    observations.push(...page.observations);
+    if (page.nextCursor === null) {
+      completed = true;
+      break;
+    }
+    if (typeof page.nextCursor !== "string" || page.nextCursor.length === 0) {
+      throw new TypeError("location provider returned an invalid cursor");
+    }
+    if (seenCursors.has(page.nextCursor)) {
+      throw new Error("location provider returned a repeated cursor");
+    }
+    seenCursors.add(page.nextCursor);
+    cursor = page.nextCursor;
+  }
+  // Only a loop that ran out of its page budget without a terminal null
+  // cursor is a runaway; completing on the final allowed page is normal.
+  if (!completed) {
+    throw new Error(`location provider exceeded ${maxPages} pages`);
+  }
+  return observations;
+}
+
+/**
+ * Sync every configured source for one local day. The master gate
+ * (`config.enabled === false`) short-circuits every path: no providers are
+ * contacted and nothing touches the filesystem. A provider failure fails
+ * that source only (state not advanced) and never blocks the others.
+ */
+export async function syncLocationDay(options: LocationDaySyncOptions): Promise<LocationSourceSyncResult[]> {
+  if (!options.config.enabled) return [];
+  const window = locationDayWindow(options.date, options.config.timezone);
+  const now = options.now ?? (() => new Date());
+  const resolveProvider = options.getProvider ?? getLocationProvider;
+
+  const results: LocationSourceSyncResult[] = [];
+  for (const source of options.config.sources) {
+    if (!source.enabled) {
+      results.push({
+        sourceId: source.id,
+        status: "skipped",
+        skipReason: "source-disabled",
+        fetched: 0,
+        dayWritten: false,
+        stateSaved: false,
+      });
+      continue;
+    }
+    const provider = resolveProvider(source.id);
+    if (provider === undefined) {
+      results.push({
+        sourceId: source.id,
+        status: "skipped",
+        skipReason: "provider-not-registered",
+        fetched: 0,
+        dayWritten: false,
+        stateSaved: false,
+      });
+      continue;
+    }
+
+    let observations: LocationObservation[];
+    try {
+      observations = await fetchWindow(provider, window, options);
+    } catch (error) {
+      results.push({
+        sourceId: source.id,
+        status: "failed",
+        fetched: 0,
+        dayWritten: false,
+        stateSaved: false,
+        ...(error instanceof Error && error.name === "AbortError"
+          ? { error: "aborted" }
+          : { error: sanitizeProviderError(error) }),
+      });
+      continue;
+    }
+
+    try {
+      options.signal?.throwIfAborted();
+      const segments = observationSegments(observations, window, {
+        retainCoordinates: options.config.retainCoordinates,
+      });
+      const payload = { observationCount: observations.length, segments, providerDisplayName: provider.displayName };
+      const merged = await mergeDaySources(options.memoryDir, source.id, options.date, payload);
+      let dayWritten = false;
+      if (Object.values(merged).some((entry) => entry.observationCount > 0)) {
+        const body = composeLocationDayBody(options.date, options.config.timezone, merged);
+        const meta = composeLocationDayMeta(options.date, options.config.timezone, merged, body);
+        dayWritten = await writeLocationDay(options.memoryDir, options.date, serializeLocationDay(meta, body));
+      }
+      // State advances only after the durable day write above succeeded.
+      await updateLocationSourceDay(
+        options.memoryDir,
+        source.id,
+        options.date,
+        payload,
+        now().toISOString(),
+      );
+      results.push({
+        sourceId: source.id,
+        status: "synced",
+        fetched: observations.length,
+        dayWritten,
+        stateSaved: true,
+      });
+    } catch (error) {
+      results.push({
+        sourceId: source.id,
+        status: "failed",
+        fetched: observations.length,
+        dayWritten: false,
+        stateSaved: false,
+        ...(error instanceof Error && error.name === "AbortError"
+          ? { error: "aborted" }
+          : { error: sanitizeProviderError(error) }),
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * The day-document source map: this source's fresh payload plus every OTHER
+ * source's last-known payload from sync state. Rendered documents therefore
+ * survive a re-sync of one source without re-fetching the others.
+ */
+async function mergeDaySources(
+  memoryDir: string,
+  sourceId: string,
+  date: string,
+  payload: { observationCount: number; segments: LocationSegment[] },
+): Promise<Record<string, LocationDaySourceEntry>> {
+  const state = await loadLocationSyncState(memoryDir);
+  const merged: Record<string, LocationDaySourceEntry> = {};
+  for (const [otherId, otherState] of Object.entries(state.sources)) {
+    if (otherId === sourceId) continue;
+    const day = otherState.days?.[date];
+    if (day === undefined) continue;
+    merged[otherId] = { ...day, segments: [...day.segments] };
+  }
+  merged[sourceId] = payload;
+  return merged;
+}

package/src/location/recall-exclusion.test.ts

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isSearchExcludedPath } from "../orchestration/generic-recall-paths.js";
+import { isLocationDayPath } from "../orchestration/orchestrator-helpers.js";
+
+const MEMORY_DIR = "/tmp/remnic-fixture-memory";
+
+test("isLocationDayPath matches only the top-level day-file shape", () => {
+  assert.equal(isLocationDayPath("locations/2026-08-17.md", MEMORY_DIR), true);
+  assert.equal(isLocationDayPath(`${MEMORY_DIR}/locations/2026-08-17.md`, MEMORY_DIR), true);
+  assert.equal(isLocationDayPath("facts/notes/locations.md", MEMORY_DIR), false);
+  assert.equal(isLocationDayPath("facts/locations/2026-08-17.md", MEMORY_DIR), false, "nested stays recallable");
+  assert.equal(isLocationDayPath("locations/2026-08-17.md"), true, "root-unaware best-effort fallback");
+  assert.equal(isLocationDayPath("locations/not-a-date.md"), false);
+});
+
+test("isSearchExcludedPath keeps location day documents out of generic search and recall", () => {
+  assert.equal(isSearchExcludedPath("locations/2026-08-17.md"), true);
+  assert.equal(
+    isSearchExcludedPath("qmd://collection/locations/2026-08-17.md", {}, "qmd"),
+    true,
+    "collection-qualified QMD paths are stripped and re-tested",
+  );
+  assert.equal(
+    isSearchExcludedPath(`${MEMORY_DIR}/namespaces/team/locations/2026-08-17.md`, { memoryDir: MEMORY_DIR }),
+    true,
+    "a namespaced day document is excluded via the namespace root",
+  );
+  assert.equal(isSearchExcludedPath("facts/locations-tips.md"), false);
+  assert.equal(
+    isSearchExcludedPath("namespaces/locations/facts/a.md", { memoryDir: MEMORY_DIR }),
+    false,
+    "a namespace literally named locations keeps its memories recallable",
+  );
+});

package/src/location/registry.test.ts

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  clearLocationProviders,
+  getLocationProvider,
+  listLocationProviders,
+  registerLocationProvider,
+} from "./registry.js";
+import type { LocationProvider } from "./types.js";
+
+function provider(overrides: Partial<LocationProvider> = {}): LocationProvider {
+  return {
+    id: "fixture-provider",
+    displayName: "Fixture Provider",
+    async verify() {
+      return { ok: true };
+    },
+    async fetchObservations() {
+      return { observations: [], nextCursor: null };
+    },
+    ...overrides,
+  };
+}
+
+test("registerLocationProvider registers, looks up, and lists sorted", () => {
+  clearLocationProviders();
+  registerLocationProvider(provider({ id: "zeta", displayName: "Z" }));
+  registerLocationProvider(provider({ id: "alpha", displayName: "A" }));
+  assert.deepEqual(listLocationProviders(), ["alpha", "zeta"]);
+  assert.equal(getLocationProvider("alpha")?.displayName, "A");
+  assert.equal(getLocationProvider("missing"), undefined);
+});
+
+test("registerLocationProvider rejects duplicate ids", () => {
+  clearLocationProviders();
+  registerLocationProvider(provider());
+  assert.throws(() => registerLocationProvider(provider()), /already registered/);
+});
+
+test("registerLocationProvider rejects invalid ids", () => {
+  clearLocationProviders();
+  assert.throws(() => registerLocationProvider(provider({ id: "" })), RangeError);
+  assert.throws(() => registerLocationProvider(provider({ id: "Upper" })), RangeError);
+  assert.throws(() => registerLocationProvider(provider({ id: "has space" })), RangeError);
+  assert.throws(() => registerLocationProvider(provider({ id: "../traversal" })), RangeError);
+  assert.throws(
+    () => registerLocationProvider(provider({ id: "x", displayName: "" as unknown as string })),
+    TypeError,
+  );
+  assert.throws(
+    () =>
+      registerLocationProvider(
+        provider({ id: "x", verify: undefined as unknown as LocationProvider["verify"] }),
+      ),
+    TypeError,
+  );
+  assert.throws(
+    () =>
+      registerLocationProvider(
+        provider({ id: "x", fetchObservations: undefined as unknown as LocationProvider["fetchObservations"] }),
+      ),
+    TypeError,
+  );
+  assert.deepEqual(listLocationProviders(), []);
+});
+
+test("clearLocationProviders resets the registry", () => {
+  clearLocationProviders();
+  registerLocationProvider(provider());
+  clearLocationProviders();
+  assert.deepEqual(listLocationProviders(), []);
+  assert.equal(getLocationProvider("fixture-provider"), undefined);
+});