@remnic/core 9.63.12 → 9.64.1

package/dist/{types-CltSWcND.d.ts → types-CpgsN-Gb.d.ts}

@@ -569,6 +569,29 @@ interface MeetingRecord extends FusedMeeting {
     formatVersion: number;
 }
 
+/** One configured location source: a registered provider plus its toggle. */
+interface LocationSourceConfig {
+    /** Must match a registered provider id. */
+    id: string;
+    /** `false` short-circuits this source only. */
+    enabled: boolean;
+}
+/** Opt-in location synchronization settings. */
+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[];
+}
+
 /**
  * Wearable transcript subsystem — shared types (issue: wearable connectors).
  *
@@ -2375,10 +2398,8 @@ 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).
      *

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export { bb as AccessTrackingEntry, a1 as ActiveRecallChatType, a5 as ActiveRecallModelFallbackPolicy, a3 as ActiveRecallPromptStyle, a2 as ActiveRecallQueryMode, a4 as ActiveRecallThinking, w as AgentAccessAuthToken, ct as AgentAccessHttpConfig, cu as AgentDefaultsConfig, cv as AgentPersona, A as AgentPersonaModelConfig, cw as BehaviorLoopAdjustment, t as BehaviorLoopPolicyState, cx as BehaviorSignalDirection, a7 as BehaviorSignalEvent, cy as BehaviorSignalType, bf as BootstrapOptions, bg as BootstrapResult, g as BriefingActiveThread, cz as BriefingCalendarSourceError, bB as BriefingConfig, d as BriefingFocus, c as BriefingFollowup, i as BriefingOpenCommitment, j as BriefingRecentEntity, h as BriefingResult, B as BriefingSections, bC as BriefingWindow, cA as BufferEntryState, b7 as BufferState, a8 as BufferSurpriseEvent, k as BufferTurn, f as CalendarEvent, e as CalendarSource, y as CaptureMode, cB as ChatConfig, n as Checkpoint, cC as CodexCliReasoningEffort, cD as CodexCompactionFlushMode, bF as CodexCompatConfig, cE as CodexConnectorConfig, C as CodingContext, cF as CodingGraphLspConfig, bo as CodingKnowledgeConfig, bi as CodingModeConfig, cG as CompressionGuidelineActivationState, ae as CompressionGuidelineOptimizerActionSummary, ad as CompressionGuidelineOptimizerEventCounts, af as CompressionGuidelineOptimizerRuleUpdate, cH as CompressionGuidelineOptimizerSourceWindow, ai as CompressionGuidelineOptimizerState, cI as ConfidenceTier, cJ as ConsolidationAction, cK as ConsolidationItem, bh as ConsolidationObservation, aF as ConsolidationResult, aj as ConvergeConfig, a0 as ConvergeConflictPolicy, U as ConversationThread, cL as CronConversationRecallMode, cM as CronRecallMode, bG as DEFAULT_RECALL_DISCLOSURE, aG as DaySummaryResult, al as DependencyPropagationConfig, cN as DreamingConfig, cO as DreamingNarrativePromptStyle, cP as DreamsDeepSleepConfig, cQ as DreamsLightSleepConfig, D as DreamsPhase, cR as DreamsPhaseStatus, cS as DreamsPhasesConfig, cT as DreamsRemConfig, a as DreamsRunResult, bd as DreamsStatusResult, cU as EngramTraceEvent, ba as EntityActivityEntry, E as EntityFile, ak as EntityMention, b9 as EntityRelationship, an as EntitySchemaDefinition, ao as EntitySchemaSectionDefinition, am as EntityStructuredSection, b5 as EntityTimelineEntry, ap as ExtractedFact, cV as ExtractedProcedureStep, cW as ExtractedQuestion, cX as ExtractedReasoningTrace, cY as ExtractedReasoningTraceStep, cZ as ExtractedRelationship, _ as ExtractionFailureClass, c_ as ExtractionPassSource, a6 as ExtractionResult, F as FaithfulnessFrontmatter, b8 as FileHygieneConfig, G as GatewayConfig, c$ as GitHubLiveConnectorConfig, d0 as GmailLiveConnectorConfig, d1 as GoogleDriveLiveConnectorConfig, d2 as HeartbeatConfig, d3 as HeartbeatDetectionMode, H as HourlySummary, I as IdentityInjectionMode, $ as ImportanceLevel, ar as ImportanceScore, V as LifecycleState, L as LiveConnectorsConfig, d4 as LlmTraceCallback, d5 as LlmTraceEvent, at as MemoryActionEligibilityContext, bQ as MemoryActionEligibilitySource, ah as MemoryActionEvent, d6 as MemoryActionOutcome, d7 as MemoryActionPolicyDecision, au as MemoryActionPolicyResult, d8 as MemoryActionStatus, ag as MemoryActionType, x as MemoryCategory, M as MemoryFile, m as MemoryFrontmatter, as as MemoryIntent, K as MemoryLifecycleEvent, av as MemoryLifecycleEventType, aw as MemoryLifecycleStateSummary, b6 as MemoryLink, d9 as MemoryLinkType, bR as MemoryObservation, da as MemoryOsPresetName, J as MemoryProjectionCurrentState, bS as MemoryScope, z as MemoryStatus, bc as MemorySummary, aA as MetaState, db as ModelApi, dc as ModelDefinitionConfig, dd as ModelProviderAuthMode, ax as ModelProviderConfig, de as NamespacePolicy, ay as NativeKnowledgeConfig, df as NativeKnowledgeFolderRuleConfig, dg as NativeKnowledgeObsidianVaultConfig, dh as NativeKnowledgeOpenClawWorkspaceConfig, di as NotionLiveConnectorConfig, P as PluginConfig, X as PolicyClass, dj as PrincipalFromSessionKeyMode, dk as PrincipalRule, dl as ProceduralConfig, aq as ProvenanceConfig, N as ProvenanceSource, aH as QmdSearchExplain, Q as QmdSearchResult, dm as QuestionEntry, bT as RECALL_DISCLOSURE_LEVELS, dn as ReasoningEffort, o as RecallDisclosure, dp as RecallPipelineConfig, R as RecallPlanMode, be as RecallSectionConfig, b as RecallTierExplain, dq as RecallTraceEvent, dr as RelevanceFeedback, aC as RetrievalTier, ds as SPECULATIVE_TTL_DAYS, dt as ScopeProfileAutoPromoteConfig, q as ScopeProfileConfig, r as ScopeProfileLayerId, s as ScopeProfilePromotionTarget, du as ScopeProfileTeamProjectConfig, dv as ScopeTeamConfig, dw as ScoredEntity, v as SecretRef, dx as SemanticChunkingConfigShape, S as SessionObserverBandConfig, dy as SignalLevel, aD as SignalScanResult, dz as SlotBehaviorConfig, dA as SlotMismatchMode, p as SourceConnectorProvenance, c2 as SupportPassportConfig, aE as TopicScore, T as TranscriptEntry, dB as TriggerMode, O as TrustWeights, W as VerificationState, dC as confidenceTier, b$ as isRecallDisclosure } from './types-CltSWcND.js';
+export { bb as AccessTrackingEntry, a1 as ActiveRecallChatType, a5 as ActiveRecallModelFallbackPolicy, a3 as ActiveRecallPromptStyle, a2 as ActiveRecallQueryMode, a4 as ActiveRecallThinking, w as AgentAccessAuthToken, ct as AgentAccessHttpConfig, cu as AgentDefaultsConfig, cv as AgentPersona, A as AgentPersonaModelConfig, cw as BehaviorLoopAdjustment, t as BehaviorLoopPolicyState, cx as BehaviorSignalDirection, a7 as BehaviorSignalEvent, cy as BehaviorSignalType, bf as BootstrapOptions, bg as BootstrapResult, g as BriefingActiveThread, cz as BriefingCalendarSourceError, bB as BriefingConfig, d as BriefingFocus, c as BriefingFollowup, i as BriefingOpenCommitment, j as BriefingRecentEntity, h as BriefingResult, B as BriefingSections, bC as BriefingWindow, cA as BufferEntryState, b7 as BufferState, a8 as BufferSurpriseEvent, k as BufferTurn, f as CalendarEvent, e as CalendarSource, y as CaptureMode, cB as ChatConfig, n as Checkpoint, cC as CodexCliReasoningEffort, cD as CodexCompactionFlushMode, bF as CodexCompatConfig, cE as CodexConnectorConfig, C as CodingContext, cF as CodingGraphLspConfig, bo as CodingKnowledgeConfig, bi as CodingModeConfig, cG as CompressionGuidelineActivationState, ae as CompressionGuidelineOptimizerActionSummary, ad as CompressionGuidelineOptimizerEventCounts, af as CompressionGuidelineOptimizerRuleUpdate, cH as CompressionGuidelineOptimizerSourceWindow, ai as CompressionGuidelineOptimizerState, cI as ConfidenceTier, cJ as ConsolidationAction, cK as ConsolidationItem, bh as ConsolidationObservation, aF as ConsolidationResult, aj as ConvergeConfig, a0 as ConvergeConflictPolicy, U as ConversationThread, cL as CronConversationRecallMode, cM as CronRecallMode, bG as DEFAULT_RECALL_DISCLOSURE, aG as DaySummaryResult, al as DependencyPropagationConfig, cN as DreamingConfig, cO as DreamingNarrativePromptStyle, cP as DreamsDeepSleepConfig, cQ as DreamsLightSleepConfig, D as DreamsPhase, cR as DreamsPhaseStatus, cS as DreamsPhasesConfig, cT as DreamsRemConfig, a as DreamsRunResult, bd as DreamsStatusResult, cU as EngramTraceEvent, ba as EntityActivityEntry, E as EntityFile, ak as EntityMention, b9 as EntityRelationship, an as EntitySchemaDefinition, ao as EntitySchemaSectionDefinition, am as EntityStructuredSection, b5 as EntityTimelineEntry, ap as ExtractedFact, cV as ExtractedProcedureStep, cW as ExtractedQuestion, cX as ExtractedReasoningTrace, cY as ExtractedReasoningTraceStep, cZ as ExtractedRelationship, _ as ExtractionFailureClass, c_ as ExtractionPassSource, a6 as ExtractionResult, F as FaithfulnessFrontmatter, b8 as FileHygieneConfig, G as GatewayConfig, c$ as GitHubLiveConnectorConfig, d0 as GmailLiveConnectorConfig, d1 as GoogleDriveLiveConnectorConfig, d2 as HeartbeatConfig, d3 as HeartbeatDetectionMode, H as HourlySummary, I as IdentityInjectionMode, $ as ImportanceLevel, ar as ImportanceScore, V as LifecycleState, L as LiveConnectorsConfig, d4 as LlmTraceCallback, d5 as LlmTraceEvent, at as MemoryActionEligibilityContext, bQ as MemoryActionEligibilitySource, ah as MemoryActionEvent, d6 as MemoryActionOutcome, d7 as MemoryActionPolicyDecision, au as MemoryActionPolicyResult, d8 as MemoryActionStatus, ag as MemoryActionType, x as MemoryCategory, M as MemoryFile, m as MemoryFrontmatter, as as MemoryIntent, K as MemoryLifecycleEvent, av as MemoryLifecycleEventType, aw as MemoryLifecycleStateSummary, b6 as MemoryLink, d9 as MemoryLinkType, bR as MemoryObservation, da as MemoryOsPresetName, J as MemoryProjectionCurrentState, bS as MemoryScope, z as MemoryStatus, bc as MemorySummary, aA as MetaState, db as ModelApi, dc as ModelDefinitionConfig, dd as ModelProviderAuthMode, ax as ModelProviderConfig, de as NamespacePolicy, ay as NativeKnowledgeConfig, df as NativeKnowledgeFolderRuleConfig, dg as NativeKnowledgeObsidianVaultConfig, dh as NativeKnowledgeOpenClawWorkspaceConfig, di as NotionLiveConnectorConfig, P as PluginConfig, X as PolicyClass, dj as PrincipalFromSessionKeyMode, dk as PrincipalRule, dl as ProceduralConfig, aq as ProvenanceConfig, N as ProvenanceSource, aH as QmdSearchExplain, Q as QmdSearchResult, dm as QuestionEntry, bT as RECALL_DISCLOSURE_LEVELS, dn as ReasoningEffort, o as RecallDisclosure, dp as RecallPipelineConfig, R as RecallPlanMode, be as RecallSectionConfig, b as RecallTierExplain, dq as RecallTraceEvent, dr as RelevanceFeedback, aC as RetrievalTier, ds as SPECULATIVE_TTL_DAYS, dt as ScopeProfileAutoPromoteConfig, q as ScopeProfileConfig, r as ScopeProfileLayerId, s as ScopeProfilePromotionTarget, du as ScopeProfileTeamProjectConfig, dv as ScopeTeamConfig, dw as ScoredEntity, v as SecretRef, dx as SemanticChunkingConfigShape, S as SessionObserverBandConfig, dy as SignalLevel, aD as SignalScanResult, dz as SlotBehaviorConfig, dA as SlotMismatchMode, p as SourceConnectorProvenance, c2 as SupportPassportConfig, aE as TopicScore, T as TranscriptEntry, dB as TriggerMode, O as TrustWeights, W as VerificationState, dC as confidenceTier, b$ as isRecallDisclosure } from './types-CpgsN-Gb.js';
 import './message-parts/index.js';
 import './bounded-jsonl-state.js';
 import './external-wiki-config.js';

package/dist/types.js

@@ -4,7 +4,7 @@ import {
   SPECULATIVE_TTL_DAYS,
   confidenceTier,
   isRecallDisclosure
-} from "./chunk-AR253JBM.js";
+} from "./chunk-DPPTG6VJ.js";
 import "./chunk-PZ5AY32C.js";
 export {
   DEFAULT_RECALL_DISCLOSURE,

package/dist/utility-runtime.d.ts

@@ -1,6 +1,6 @@
 import { TierRoutingPolicy } from './tier-routing.js';
 import './lifecycle.js';
-import './types-CltSWcND.js';
+import './types-CpgsN-Gb.js';
 import './message-parts/index.js';
 import './bounded-jsonl-state.js';
 import './operator-doctor-types.js';

package/dist/verified-recall.js

@@ -1,9 +1,9 @@
 import {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
-} from "./chunk-BTBAHTQ5.js";
+} from "./chunk-CI6YIT5S.js";
 import "./chunk-B7RWBZXW.js";
-import "./chunk-5SZ6CLGJ.js";
+import "./chunk-2RZCOG63.js";
 import "./chunk-UHVXE24Y.js";
 import "./chunk-46WM6JX2.js";
 import "./chunk-SXIMQLGV.js";
@@ -22,7 +22,7 @@ import "./chunk-ET356KSB.js";
 import "./chunk-72A4L5JJ.js";
 import "./chunk-A7Q43EUZ.js";
 import "./chunk-S2V7RUCL.js";
-import "./chunk-AR253JBM.js";
+import "./chunk-DPPTG6VJ.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-PO7NXBG2.js";
 import "./chunk-S2HLHAZ4.js";

package/dist/write-envelope.d.ts

@@ -1,4 +1,4 @@
-import { x as MemoryCategory } from './types-CltSWcND.js';
+import { x as MemoryCategory } from './types-CpgsN-Gb.js';
 import './message-parts/index.js';
 import './bounded-jsonl-state.js';
 import './operator-doctor-types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.63.12",
+  "version": "9.64.1",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3156,7 +3156,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.63.12"
+    "@remnic/coding-graph": "^9.64.1"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/config.ts

@@ -61,9 +61,8 @@ import {
   resolveNamespaceCatalogEnabled,
 } from "./emit-legacy-tools.js";
 import { parseWearablesConfig } from "./wearables/config.js";
-import { parseMeetingsConfig } from "./meetings/config.js";
-import { parseActivityConfig } from "./activity/config.js";
-import { parseProvenanceConfig } from "./provenance.js";
+import { parseCaptureCompanionConfigs } from "./location/parse-companions.js";
+import { parseLocationConfig } from "./location/config.js";
 import { parseBoundedJsonlStateConfig } from "./bounded-jsonl-state.js";
 import { parseCodingKnowledgeConfig } from "./coding/coding-knowledge-config.js";
 import { parseChatConfig } from "./chat/chat-config.js";
@@ -1159,9 +1158,8 @@ export function parseConfig(
     recallMaxProcedures,
   };
   const wearables = parseWearablesConfig(cfg.wearables);
-  const activity = parseActivityConfig(cfg.activity);
-  const meetings = parseMeetingsConfig(cfg.meetings);
-  const provenance = parseProvenanceConfig(cfg.provenance);
+  const { activity, meetings, provenance } = parseCaptureCompanionConfigs(cfg);
+  const location = parseLocationConfig(cfg.location);
   // Coding-agent project/branch scoping (issue #569)
   const rawCodingMode =
     cfg.codingMode && typeof cfg.codingMode === "object" && !Array.isArray(cfg.codingMode)
@@ -2323,6 +2321,7 @@ export function parseConfig(
     wearables,
     meetings,
     activity,
+    location,
     provenance,
     // At-rest encryption (#690): coerceBool handles CLI string "true" (#36).
     secureStoreEnabled: coerceBool(cfg.secureStoreEnabled) === true,

package/src/connectors/index.test.ts

@@ -174,6 +174,30 @@ test("BUILTIN catalog includes the omp (oh-my-pi) connector", async (t) => {
   );
 });
 
+test("BUILTIN catalog includes the prime-agent connector", async (t) => {
+  const sandbox = makeSandbox(t);
+
+  await withEnv(
+    {
+      HOME: sandbox.home,
+      USERPROFILE: sandbox.home,
+      XDG_CONFIG_HOME: sandbox.xdgConfigHome,
+    },
+    () => {
+      const registry = loadRegistry();
+      const primeAgent = registry.connectors.find((connector) => connector.id === "prime-agent");
+
+      assert.ok(primeAgent, "prime-agent connector should be present in the built-in catalog");
+      assert.equal(primeAgent?.requiresToken, true);
+      assert.equal(primeAgent?.capabilities?.connectionType, "http");
+      assert.ok(
+        (primeAgent?.tags ?? []).includes("official"),
+        "prime-agent should be tagged official",
+      );
+    },
+  );
+});
+
 test("loadRegistry filters custom connectors with invalid IDs", async (t) => {
   const sandbox = makeSandbox(t);
 

package/src/connectors/index.ts

@@ -38,6 +38,7 @@ import {
   droidMcpDoctorCheck as droidMcpDoctorCheckImpl,
   readDroidMcpProvenance,
 } from "./droid-mcp.js";
+import { PRIME_AGENT_CONNECTOR_MANIFEST } from "./prime-agent.js";
 
 // Native memory artifact materialization for Codex CLI (#378). Surfaced here
 // so downstream callers can `import { materializeForNamespace } from "@remnic/core/connectors"`.
@@ -464,6 +465,7 @@ export const BUILTIN_CONNECTORS: ConnectorManifest[] = [
     tags: ["official", "ai", "omp", "pi", "coding-agent"],
     requiresToken: true,
   },
+  PRIME_AGENT_CONNECTOR_MANIFEST,
   {
     id: "replit",
     name: "Replit Agent",

package/src/connectors/prime-agent.ts

@@ -0,0 +1,38 @@
+import type { ConnectorManifest } from "./index.js";
+
+/**
+ * Builtin manifest for the Prime Agent connector (#2313). Prime Agent is a
+ * Pi-fork coding agent; the runtime extension is `@remnic/plugin-pi`, published
+ * to `~/.prime/agent/extensions/remnic` (override: `PRIME_AGENT_CODING_AGENT_DIR`)
+ * by `PrimeAgentMemoryExtensionPublisher` in the plugin-pi package.
+ *
+ * Declared in this sibling module — not inline in index.ts — so the connector
+ * catalog addition does not grow index.ts past its file-size ratchet ceiling
+ * (same pattern as `DROID_CONNECTOR_MANIFEST` in droid-mcp.ts).
+ */
+export const PRIME_AGENT_CONNECTOR_MANIFEST: ConnectorManifest = {
+  id: "prime-agent",
+  name: "Prime Agent",
+  version: "1.0.0",
+  description:
+    "Prime Agent — Pi-fork coding agent; native extension for recall, observe, MCP tools, and compaction coordination",
+  capabilities: {
+    observe: true,
+    recall: true,
+    store: true,
+    search: true,
+    entities: true,
+    realtimeSync: true,
+    batch: true,
+    maxBudgetChars: 32000,
+    connectionType: "http",
+  },
+  configSchema: {
+    remnicDaemonUrl: "URL of the Remnic daemon (default: http://127.0.0.1:4318)",
+    namespace: "Optional namespace",
+    installExtension: "Install the Prime Agent extension into ~/.prime/agent/extensions/remnic (default: true)",
+  },
+  author: "Remnic",
+  tags: ["official", "ai", "prime-agent", "pi", "coding-agent"],
+  requiresToken: true,
+};

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