@remnic/core 9.64.0 → 9.64.2

package/src/access-mcp.ts

@@ -45,6 +45,7 @@ import { applyToolOutputSchemas } from "./access-mcp-output-schemas.js";
 import { MCP_READ_ONLY_TOOL_SUFFIXES } from "./mcp-read-only-tools.js";
 import { MEETINGS_MCP_TOOLS } from "./meetings/mcp-tools.js";
 import { WEARABLES_MCP_TOOLS } from "./wearables/mcp-tools.js";
+import { WHO_KNOWS_MCP_TOOLS } from "./who-knows.js";
 import { EXTERNAL_WIKI_MCP_TOOLS } from "./external-wiki-mcp-tools.js";
 import { abortError, isAbortError } from "./abort-error.js";
 import { SUPPORT_PASSPORT_MCP_MIGRATED_OPERATIONS, SUPPORT_PASSPORT_MCP_TOOLS } from "./support-passport/mcp-tools.js";
@@ -186,7 +187,7 @@ const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> = {
   "engram.recall_explain": "recall_explain",
   "engram.set_coding_context": "set_coding_context",
   "engram.recall_tier_explain": "recall_tier_explain",
-  "engram.recall_xray": "recall_xray",
+  "engram.recall_xray": "recall_xray", "engram.who_knows": "who_knows",
   "engram.wearables_status": "wearables_status",
   "engram.wearables_sync": "wearables_sync",
   "engram.transcript_day": "transcript_day",
@@ -705,7 +706,7 @@ export class EngramMcpServer {
           additionalProperties: false,
         },
       },
-      ...WEARABLES_MCP_TOOLS, ...MEETINGS_MCP_TOOLS,
+      ...WEARABLES_MCP_TOOLS, ...MEETINGS_MCP_TOOLS, ...WHO_KNOWS_MCP_TOOLS,
       ...(service.supportPassportEnabled ? SUPPORT_PASSPORT_MCP_TOOLS : []),
       {
         name: "engram.action_confidence",

package/src/access-operations-batch.ts

@@ -139,6 +139,14 @@ defineOperation({ name: "recall_xray", description: "X-ray recall.", schema: str
     return { result: await ctx.service.recallXray({ query: defStr(input.query, ""), sessionKey: optStr(input.sessionKey), namespace: optStr(input.namespace), budget, authenticatedPrincipal: ctx.authenticatedPrincipal, sourceConnector: ctx.sourceConnector, ...(dr && dr !== "" ? { disclosure: dr as RecallDisclosure } : {}), ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}) }) };
   },
 });
+defineOperation({ name: "who_knows", description: "Rank entities by demonstrated expertise for a topic (#2057).", schema: strictSchema({ topic: S.str, limit: S.flexNum, namespace: S.str }),
+  handler: async (input, ctx) => {
+    const topic = defStr(input.topic, "");
+    let limit: number | undefined;
+    if (input.limit !== undefined) { const p = typeof input.limit === "number" ? input.limit : Number(input.limit); if (!Number.isInteger(p) || p < 1) throw new EngramAccessInputError("who_knows: limit expects a positive integer"); limit = p; }
+    return { result: await ctx.service.whoKnows({ topic, ...(limit !== undefined ? { limit } : {}), namespace: optStr(input.namespace), authenticatedPrincipal: ctx.authenticatedPrincipal }) };
+  },
+});
 defineOperation({ name: "namespace_writable", description: "Read-only preflight: is a namespace writable for the caller's principal?", allowedByOps: ["namespace_writable", "observe", "memory_store"], schema: strictSchema({ namespace: S.str, sessionKey: S.str, op: S.str, cwd: S.str, projectTag: S.str }), handler: async (input, ctx) => {
   const writeOp = parseNamespacePreflightWriteOp(optStr(input.op));
   const namespace = optStr(input.namespace);

package/src/access-service.ts

@@ -304,6 +304,7 @@ import { decideDisclosureEscalation } from "./recall-disclosure-escalation.js";
 import { toRecallExplainJson } from "./recall-explain-renderer.js";
 import { type TagMatchMode, applyTagFilter, normalizeTags, parseTagMatch } from "./recall-tag-filter.js";
 import { type RecallXraySnapshot, estimateRecallTokens } from "./recall-xray.js";
+import { computeWhoKnows, loadWhoKnowsEntities, validateWhoKnowsInput, WHO_KNOWS_DEFAULT_LIMIT, type WhoKnowsResult } from "./who-knows.js";
 import { SupportPassportAccessServiceBase } from "./support-passport/access-service-base.js";
 import {
   type ExportCapsuleOptions,
@@ -2712,6 +2713,31 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
   }> {
     return this.accessRecallSurface.recallXray(request);
   }
+
+  /**
+   * Rank entities by demonstrated expertise for a topic (issue #2057).
+   * Deterministic — no LLM, no QMD. Reads the namespace-scoped corpus and
+   * entity files only; namespace resolution + ACL mirror recall semantics
+   * (`resolveReadableNamespace`), so a principal cannot rank outside a
+   * namespace it cannot read.
+   */
+  async whoKnows(request: {
+    topic: string;
+    limit?: number;
+    namespace?: string;
+    authenticatedPrincipal?: string;
+  }): Promise<WhoKnowsResult> {
+    const topic = request.topic?.trim() ?? "";
+    const limit = request.limit ?? WHO_KNOWS_DEFAULT_LIMIT;
+    validateWhoKnowsInput(topic, limit);
+    const resolvedNamespace = this.resolveReadableNamespace(request.namespace, request.authenticatedPrincipal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const [memories, entities] = await Promise.all([
+      storage.readAllMemories(),
+      loadWhoKnowsEntities(storage, this.orchestrator.config.entitySchemas),
+    ]);
+    return computeWhoKnows({ topic, limit, memories, entities });
+  }
   async memoryStore(
     request: EngramAccessMemoryStoreRequest,
     hooks?: { enforceWriteQuota?: () => void | Promise<void> }

package/src/access-surface-catalog.ts

@@ -56,6 +56,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "set_coding_context", operation: "set_coding_context" },
   { tool: "recall_tier_explain", operation: "recall_tier_explain" },
   { tool: "recall_xray", operation: "recall_xray" },
+  { tool: "who_knows", operation: "who_knows" },
   { tool: "wearables_status", operation: "wearables_status" },
   { tool: "wearables_sync", operation: "wearables_sync" },
   { tool: "transcript_day", operation: "transcript_day" },
@@ -210,6 +211,7 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "POST", pathname: "/engram/v1/action-confidence", operation: "action_confidence" },
   { method: "GET", pathname: "/engram/v1/recall/tier-explain", operation: "recall_tier_explain" },
   { method: "GET", pathname: "/engram/v1/recall/xray", operation: "recall_xray" },
+  { method: "GET", pathname: "/engram/v1/who-knows", operation: "who_knows" },
   { method: "GET", pathname: "/engram/v1/namespace/writable", operation: "namespace_writable" },
   { method: "GET", pathname: "/engram/v1/wearables/status", operation: "wearables_status" },
   { method: "POST", pathname: "/engram/v1/wearables/sync", operation: "wearables_sync" },

package/src/cli/okf-commands.ts

@@ -0,0 +1,23 @@
+import type { Orchestrator } from "../orchestrator.js";
+import type { CliCommand } from "../cli.js";
+import { runOkfCliCommand } from "../okf/cli.js";
+
+export function registerOkfCommands(cmd: CliCommand, orchestrator: Orchestrator): void {
+  const okfCmd = cmd.command("okf").description("OKF v0.1 conformance (lint, sweep)");
+  const forward = async (argv: string[]): Promise<void> => {
+    const code = await runOkfCliCommand(argv, { stdout: process.stdout, stderr: process.stderr }, {
+      memoryDir: orchestrator.config.memoryDir,
+      conformanceEnabled: orchestrator.config.okf.conformanceEnabled,
+      sweepEnabled: orchestrator.config.okf.sweepEnabled,
+    });
+    if (code !== 0) process.exitCode = code;
+  };
+  okfCmd.command("lint").description("Report OKF conformance findings").option("--json", "JSON output").action(async (...args: unknown[]) => {
+    const options = (args[0] ?? {}) as Record<string, unknown>;
+    await forward(["lint", ...(options.json === true ? ["--json"] : [])]);
+  });
+  okfCmd.command("sweep").description("Add missing type fields without bumping updated").option("--json", "JSON output").action(async (...args: unknown[]) => {
+    const options = (args[0] ?? {}) as Record<string, unknown>;
+    await forward(["sweep", ...(options.json === true ? ["--json"] : [])]);
+  });
+}

package/src/cli.ts

@@ -15,6 +15,7 @@ import { utcDayRange } from "./transcript.js";
 import { padEndDisplay, truncateGraphemeSafe } from "./whitespace.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
 import { registerMeetingsCommands } from "./cli/meetings-commands.js";
+import { registerOkfCommands } from "./cli/okf-commands.js";
 import { registerResearchStatusCommands } from "./cli/research-status-commands.js";
 import { registerCreationLedgerCommands } from "./cli/creation-ledger-commands.js";
 import type {
@@ -6227,7 +6228,7 @@ export function registerCli(
 
       registerResearchStatusCommands(cmd, orchestrator);
 
-      registerCreationLedgerCommands(cmd, orchestrator); registerMeetingsCommands(cmd, orchestrator);
+      registerCreationLedgerCommands(cmd, orchestrator); registerMeetingsCommands(cmd, orchestrator); registerOkfCommands(cmd, orchestrator);
 
       cmd
         .command("trust-zone-promote")

package/src/config.ts

@@ -61,9 +61,9 @@ 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 { parseOkfConfig } from "./okf/config.js";
 import { parseBoundedJsonlStateConfig } from "./bounded-jsonl-state.js";
 import { parseCodingKnowledgeConfig } from "./coding/coding-knowledge-config.js";
 import { parseChatConfig } from "./chat/chat-config.js";
@@ -516,7 +516,6 @@ function normalizeMemoryRelativeDir(raw: unknown, fallback: string): string {
   return normalized.length > 0 ? normalized : fallback;
 }
 
-
 function parseSemanticChunkingConfig(
   raw: unknown,
 ): Partial<SemanticChunkingConfigShape> {
@@ -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)
@@ -2322,7 +2320,9 @@ export function parseConfig(
     converge: parseConvergeConfig(cfg.converge),
     wearables,
     meetings,
+    okf: parseOkfConfig(cfg.okf),
     activity,
+    location,
     provenance,
     // At-rest encryption (#690): coerceBool handles CLI string "true" (#36).
     secureStoreEnabled: coerceBool(cfg.secureStoreEnabled) === true,

package/src/index.ts

@@ -499,6 +499,8 @@ export type {
   RecallXrayServedBy,
   RecallFilterTrace,
 } from "./recall-xray.js";
+export * from "./who-knows.js";
+export * from "./who-knows-cli.js";
 
 // ChatGPT Apps-compatible memory inspector demo.
 export {
@@ -1215,6 +1217,7 @@ export { runAuditMemoryCliCommand, runBulkImportCliCommand, type BulkImportCliCo
 export * from "./wearables/index.js";
 export * from "./activity/index.js";
 export * from "./meetings/index.js";
+export * from "./okf/cli.js";
 
 // ---------------------------------------------------------------------------
 // Shared importer base (issue #568)

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