@remnic/core 9.63.12 → 9.64.1

package/src/location/types.ts

@@ -0,0 +1,95 @@
+/**
+ * Location context subsystem — shared types (issue #2044).
+ *
+ * A host-agnostic foundation: the provider contract, the observation/day
+ * shapes, and health-check results. No HTTP client lives here — providers are
+ * registered from host adapters (a future provider package is one such
+ * adapter), keeping `@remnic/core` free of host SDKs and network specifics.
+ *
+ * All timestamps are UTC ISO-8601; day bucketing is half-open [start, end).
+ */
+
+/** A named place the user was observed at. */
+export interface LocationPlace {
+  /** Provider-stable place identifier. */
+  id: string;
+  /** Human-readable label, already redacted by the provider. */
+  label: string;
+  kind?: "home" | "work" | "poi" | "transit" | "other";
+  /** Present only when coordinate retention is enabled. */
+  latitude?: number;
+  longitude?: number;
+}
+
+/** One place observation at a single instant, from a single provider. */
+export interface LocationObservation {
+  /** UTC ISO-8601 observation instant. */
+  observedAtUtc: string;
+  place: LocationPlace;
+  /** Provider confidence in [0,1], when reported. */
+  confidence?: number;
+}
+
+/** One page of observations from a provider fetch. */
+export interface LocationObservationPage {
+  observations: LocationObservation[];
+  nextCursor: string | null;
+}
+
+/** Result of a provider auth/health probe. */
+export interface LocationProviderCheck {
+  ok: boolean;
+  detail?: string;
+}
+
+/**
+ * Provider contract for a location source. Implemented by host adapters and
+ * registered in `registry.ts`; core never statically imports a provider
+ * package, so à-la-carte installs stay partial (a source whose provider is
+ * not registered is skipped, not an error).
+ */
+export interface LocationProvider {
+  /** Stable provider id (registry key; matches a config source id). */
+  id: string;
+  displayName: string;
+  /** Probe connectivity/auth without mutating anything. */
+  verify(signal?: AbortSignal): Promise<LocationProviderCheck>;
+  /** Fetch every observation in the half-open [startUtc, endUtc) window. */
+  fetchObservations(opts: {
+    startUtc: string;
+    endUtc: string;
+    cursor?: string | null;
+    signal?: AbortSignal;
+  }): Promise<LocationObservationPage>;
+}
+
+/** One configured location source: a registered provider plus its toggle. */
+export interface LocationSourceConfig {
+  /** Must match a registered provider id. */
+  id: string;
+  /** `false` short-circuits this source only. */
+  enabled: boolean;
+}
+
+/** Opt-in location synchronization settings. */
+export interface LocationConfig {
+  /** Master gate: `false` short-circuits every location path. */
+  enabled: boolean;
+  /** IANA timezone used to bucket observations into local days. */
+  timezone: string;
+  /** Number of local days to synchronize per run; integer 1..90. */
+  syncDays: number;
+  /**
+   * When `false` (the default), place coordinates are dropped before any
+   * persistence, rendering, or error reporting — only place labels remain.
+   */
+  retainCoordinates: boolean;
+  sources: LocationSourceConfig[];
+}
+
+/** A time-resolved place visit derived from consecutive observations. */
+export interface LocationSegment {
+  startUtc: string;
+  endUtc: string;
+  place: LocationPlace;
+}

package/src/orchestration/generic-recall-paths.ts

@@ -6,6 +6,7 @@ import { ALL_CATEGORY_DIRS } from "../utils/category-dir.js";
 import {
   isActivityDigestPath,
   isArtifactMemoryPath,
+  isLocationDayPath,
   isMeetingRecordPath,
 } from "./orchestrator-helpers.js";
 
@@ -133,6 +134,7 @@ export function isSearchExcludedPath(
     if (
       isArtifactMemoryPath(candidate) ||
       isNamespacedActivityDigestPath(candidate, policy.memoryDir) ||
+      isNamespacedLocationDayPath(candidate, policy.memoryDir) ||
       isMeetingRecordPath(candidate)
     ) {
       return true;
@@ -160,6 +162,21 @@ function isNamespacedActivityDigestPath(candidate: string, memoryDir?: string):
   return isActivityDigestPath(namespaced[2] ?? "", memoryDir);
 }
 
+/**
+ * The location day-file check, applied against the NAMESPACE root a hit came
+ * from — same rationale as `isNamespacedActivityDigestPath`: a namespaced
+ * search rewrites hits to absolute paths beneath `…/namespaces/<ns>/`, so the
+ * root-aware predicate is re-measured against the namespace's own root.
+ */
+function isNamespacedLocationDayPath(candidate: string, memoryDir?: string): boolean {
+  if (isLocationDayPath(candidate, memoryDir)) return true;
+  if (memoryDir === undefined || memoryDir.length === 0) return false;
+  const relative = path.relative(memoryDir, path.resolve(memoryDir, candidate));
+  const namespaced = /^namespaces[\\/]([^\\/]+)[\\/](.*)$/.exec(relative);
+  if (namespaced === null) return false;
+  return isLocationDayPath(namespaced[2] ?? "", memoryDir);
+}
+
 /** A path as given, plus its form with a leading COLLECTION segment removed. */
 function collectionSpellings(
   filePath: string,

package/src/orchestration/orchestrator-helpers.ts

@@ -643,6 +643,28 @@ export function isActivityDigestPath(filePath: string, memoryRoot?: string): boo
   return ACTIVITY_DIGEST_ANYWHERE.test(filePath);
 }
 
+/** Exactly `locations/<YYYY-MM-DD>.md`, at the top level of a memory root. */
+const LOCATION_DAY_TOPLEVEL = /^locations[\\/]\d{4}-\d{2}-\d{2}\.md$/i;
+/** The day-file shape anywhere in a path (root-unaware best-effort). */
+const LOCATION_DAY_ANYWHERE = /(?:^|[\\/])locations[\\/]\d{4}-\d{2}-\d{2}\.md$/i;
+
+/**
+ * Location day documents (issue #2044) live at
+ * `<memoryRoot>/locations/<YYYY-MM-DD>.md` — a dedicated searchable surface,
+ * never generic recall (place history must not auto-inject into ordinary
+ * prompts). Root-aware exactly like `isActivityDigestPath`: with a root, only
+ * the top-level `locations/<date>.md` matches, so an ordinary memory nested
+ * under a category (e.g. `facts/locations-note.md`) stays recallable; without
+ * a root, falls back to the day-file shape anywhere (best-effort).
+ */
+export function isLocationDayPath(filePath: string, memoryRoot?: string): boolean {
+  if (memoryRoot !== undefined && memoryRoot.length > 0) {
+    const relative = path.relative(memoryRoot, path.resolve(memoryRoot, filePath));
+    return LOCATION_DAY_TOPLEVEL.test(relative);
+  }
+  return LOCATION_DAY_ANYWHERE.test(filePath);
+}
+
 export function buildCompressionGuidelinesMarkdown(
   events: MemoryActionEvent[],
   generatedAtIso: string = new Date().toISOString(),

package/src/orchestration/qmd-result-resolver.ts

@@ -47,6 +47,7 @@ const INTERNAL_QMD_ROOTS = new Set([
   "config",
   "entities",
   "identity",
+  "locations",
   "meetings",
   "namespaces",
   "state",

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { BoundedJsonlStateConfig } from "./bounded-jsonl-state.js";
 import type { MeetingsConfig } from "./meetings/types.js";
+import type { LocationConfig } from "./location/types.js";
 import type { ActivityConfig } from "./activity/types.js";
 import type { WearablesConfig } from "./wearables/types.js";
 import type { ExtractionLivenessConfig } from "./extraction-liveness.js";
@@ -1232,10 +1233,8 @@ export interface PluginConfig extends BoundedJsonlStateConfig, SecurityConfig {
    */
   wearables: WearablesConfig;
   activity: ActivityConfig;
-  /** Retrospective meeting intelligence (issue #1900): detect + fuse meetings
-   * from already-ingested audio + screen activity. Disabled by default.
-   */
   meetings: MeetingsConfig;
+  location: LocationConfig;
   /**
    * At-rest encryption configuration (issue #690 PR 3/4).
    *