@tikoci/centrs 0.1.1 → 0.1.3

package/src/protocols/native-api.ts

@@ -348,6 +348,32 @@ interface PendingCommand {
 	reject: (error: CentrsError) => void;
 }
 
+/**
+ * A long-lived `/listen` subscription. Unlike {@link PendingCommand} it never
+ * buffers to a single resolve — each `!re` is pushed to the consumer as it
+ * arrives, and the stream ends on `!done` (after a `/cancel`'s `interrupted`
+ * trap) or fails on `!fatal`/transport closure.
+ */
+interface StreamingSubscription {
+	command: string;
+	/** An `!re` change frame arrived. */
+	push: (reply: ApiReply) => void;
+	/** An `!trap` arrived (an `interrupted` trap is the normal `/cancel` path). */
+	trap: (reply: ApiReply) => void;
+	/** `!done` arrived — the listen closed. */
+	settle: () => void;
+	/** `!fatal` or transport closure — the stream cannot continue. */
+	fail: (error: CentrsError) => void;
+}
+
+/** A `/cancel`'s `interrupted` trap (category 2) is the expected end of a listen, not an error. */
+function isInterruptedTrap(trap: ApiReply): boolean {
+	const message = readAttribute(trap, "message") ?? "";
+	return (
+		/interrupted/i.test(message) || readAttribute(trap, "category") === "2"
+	);
+}
+
 export interface NativeApiSessionOptions {
 	sink: NativeApiByteSink;
 	/** Host/port label used in error envelopes. */
@@ -366,6 +392,7 @@ export class NativeApiSession {
 	private readonly endpoint: string;
 	private readonly reader = new SentenceReader();
 	private readonly pending = new Map<string, PendingCommand>();
+	private readonly subscriptions = new Map<string, StreamingSubscription>();
 	private tagCounter = 0;
 	private closed = false;
 	private closeError: CentrsError | undefined;
@@ -439,33 +466,51 @@ export class NativeApiSession {
 			return; // untagged async/system notice — no waiter to route to
 		}
 		const waiter = this.pending.get(tag);
-		if (waiter === undefined) {
-			return;
+		if (waiter !== undefined) {
+			switch (reply.type) {
+				case "!re":
+					waiter.records.push(reply);
+					return;
+				case "!trap":
+					waiter.trap = reply;
+					return;
+				case "!empty":
+					return;
+				case "!done": {
+					this.pending.delete(tag);
+					if (waiter.trap) {
+						waiter.reject(this.trapToError(waiter.command, waiter.trap));
+						return;
+					}
+					if (Object.keys(reply.attributes).length > 0) {
+						waiter.records.push(reply);
+					}
+					waiter.resolve(waiter.records);
+					return;
+				}
+				default:
+					return;
+			}
 		}
 
-		switch (reply.type) {
-			case "!re":
-				waiter.records.push(reply);
-				return;
-			case "!trap":
-				waiter.trap = reply;
-				return;
-			case "!empty":
-				return;
-			case "!done": {
-				this.pending.delete(tag);
-				if (waiter.trap) {
-					waiter.reject(this.trapToError(waiter.command, waiter.trap));
+		const subscription = this.subscriptions.get(tag);
+		if (subscription !== undefined) {
+			switch (reply.type) {
+				case "!re":
+					subscription.push(reply);
+					return;
+				case "!trap":
+					subscription.trap(reply);
+					return;
+				case "!empty":
+					return;
+				case "!done":
+					this.subscriptions.delete(tag);
+					subscription.settle();
+					return;
+				default:
 					return;
-				}
-				if (Object.keys(reply.attributes).length > 0) {
-					waiter.records.push(reply);
-				}
-				waiter.resolve(waiter.records);
-				return;
 			}
-			default:
-				return;
 		}
 	}
 
@@ -503,6 +548,11 @@ export class NativeApiSession {
 		for (const waiter of waiters) {
 			waiter.reject(error);
 		}
+		const subscriptions = [...this.subscriptions.values()];
+		this.subscriptions.clear();
+		for (const subscription of subscriptions) {
+			subscription.fail(error);
+		}
 	}
 
 	private nextTag(): string {
@@ -573,6 +623,145 @@ export class NativeApiSession {
 		});
 	}
 
+	/**
+	 * Open a `/listen` subscription and yield each `!re` change frame as it
+	 * arrives (the open-ended follow path; the listen command never sends `!done`
+	 * on its own). The generator ends cleanly when the listen is cancelled:
+	 * - via `options.signal` aborting — the subscription stays registered, so the
+	 *   resulting `interrupted` trap + `!done` are drained and the loop ends
+	 *   without throwing;
+	 * - via the consumer breaking out of the `for await` — `finally` sends
+	 *   `/cancel` best-effort (the subscription is already torn down, so the
+	 *   trap/`!done` are not awaited) and the generator returns.
+	 * A non-`interrupted` trap (e.g. a bad path) or `!fatal`/transport closure
+	 * throws. CHR-grounded (7.23.1): see `commands/api/AGENTS.md`.
+	 */
+	async *listen(
+		command: NativeApiCommand,
+		options: { signal?: AbortSignal; onListening?: () => void } = {},
+	): AsyncGenerator<ApiReply, void, void> {
+		if (this.closed) {
+			throw (
+				this.closeError ??
+				new CentrsError({
+					code: "transport/connection-closed",
+					summary: `The RouterOS API session to ${this.endpoint} is closed.`,
+					remediation: "Open a new connection before listening.",
+				})
+			);
+		}
+		const tag = this.nextTag();
+		const words = this.buildWords(command, tag);
+
+		const queue: ApiReply[] = [];
+		let wake: (() => void) | undefined;
+		let ended = false;
+		let failure: CentrsError | undefined;
+		let trap: ApiReply | undefined;
+		const signalWake = (): void => {
+			const resume = wake;
+			wake = undefined;
+			resume?.();
+		};
+
+		this.subscriptions.set(tag, {
+			command: command.command,
+			push: (reply) => {
+				queue.push(reply);
+				signalWake();
+			},
+			trap: (reply) => {
+				trap = reply;
+			},
+			settle: () => {
+				ended = true;
+				signalWake();
+			},
+			fail: (error) => {
+				failure = error;
+				ended = true;
+				signalWake();
+			},
+		});
+
+		try {
+			this.sink.write(encodeSentence(words));
+		} catch (error) {
+			this.subscriptions.delete(tag);
+			throw error instanceof CentrsError
+				? error
+				: new CentrsError({
+						code: "transport/network",
+						summary: `Failed to open a listen on the RouterOS API connection to ${this.endpoint}.`,
+						remediation: "Retry; confirm the connection is still open.",
+						cause: error,
+					});
+		}
+
+		// The subscription is on the wire — signal "listening established" so callers
+		// can act on a real barrier rather than a blind timer.
+		options.onListening?.();
+
+		const onAbort = (): void => this.cancel(tag);
+		if (options.signal) {
+			if (options.signal.aborted) {
+				this.cancel(tag);
+			} else {
+				options.signal.addEventListener("abort", onAbort, { once: true });
+			}
+		}
+
+		try {
+			for (;;) {
+				if (queue.length > 0) {
+					// Drain the whole batch at once: repeated `shift()` is O(n) per frame
+					// (it shifts every remaining element), so a high-volume listen would
+					// be O(n²). New
+					// frames pushed while we yield land in the freshly emptied queue and
+					// drain on the next pass.
+					const batch = queue.splice(0, queue.length);
+					for (const reply of batch) {
+						yield reply;
+					}
+				} else if (ended) {
+					break;
+				} else {
+					await new Promise<void>((resolve) => {
+						wake = resolve;
+					});
+				}
+			}
+			if (failure) {
+				throw failure;
+			}
+			if (trap && !isInterruptedTrap(trap)) {
+				throw this.trapToError(command.command, trap);
+			}
+		} finally {
+			options.signal?.removeEventListener("abort", onAbort);
+			this.subscriptions.delete(tag);
+			// Consumer broke out early (e.g. --count reached): tell the router to stop.
+			if (!ended && !this.closed) {
+				this.cancel(tag);
+			}
+		}
+	}
+
+	/** Cancel an in-flight `/listen` by its tag (`/cancel =tag=<tag> .tag=<new>`). */
+	private cancel(tag: string): void {
+		if (this.closed) {
+			return;
+		}
+		const cancelTag = this.nextTag();
+		try {
+			this.sink.write(
+				encodeSentence(["/cancel", `=tag=${tag}`, `.tag=${cancelTag}`]),
+			);
+		} catch {
+			// Best effort — the connection may already be gone.
+		}
+	}
+
 	/**
 	 * Authenticate. Uses the combined approach: send name+password; if the
 	 * router answers with a legacy `=ret=` challenge, compute the MD5 response
@@ -607,16 +796,20 @@ export class NativeApiSession {
 		try {
 			this.sink.close();
 		} finally {
+			const closeError = new CentrsError({
+				code: "transport/connection-closed",
+				summary: `The RouterOS API session to ${this.endpoint} was closed by the caller.`,
+				remediation: "Open a new connection before sending more commands.",
+			});
 			const waiters = [...this.pending.values()];
 			this.pending.clear();
 			for (const waiter of waiters) {
-				waiter.reject(
-					new CentrsError({
-						code: "transport/connection-closed",
-						summary: `The RouterOS API session to ${this.endpoint} was closed by the caller.`,
-						remediation: "Open a new connection before sending more commands.",
-					}),
-				);
+				waiter.reject(closeError);
+			}
+			const subscriptions = [...this.subscriptions.values()];
+			this.subscriptions.clear();
+			for (const subscription of subscriptions) {
+				subscription.fail(closeError);
 			}
 		}
 	}

package/src/resolver/cdb.ts

@@ -153,6 +153,7 @@ function warningFromDevices(warning: DevicesWarning): ResolverWarning {
 export async function resolveCdb(
 	input: CdbResolveInput,
 	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
 ): Promise<CdbResolution | undefined> {
 	if (!input.targetInput) {
 		return undefined;
@@ -162,12 +163,18 @@ export async function resolveCdb(
 		cdbFile: input.cdbFile,
 		cdbPassword: input.cdbPassword,
 		env,
+		config,
 	});
+	// A user-configured `centrs.env` default CDB path counts as explicit, same
+	// as an env var: it is an intentional choice, not the built-in fallback,
+	// so a missing file there should surface as a real error rather than
+	// silently degrading to "no CDB in play".
 	const explicitCdb =
 		input.cdbFile !== undefined ||
 		input.cdbPassword !== undefined ||
 		env[ENV_CDB_FILE] !== undefined ||
-		env[ENV_CDB_PASSWORD] !== undefined;
+		env[ENV_CDB_PASSWORD] !== undefined ||
+		config[ENV_CDB_FILE] !== undefined;
 	if (!explicitCdb && !(await Bun.file(settings.cdbFile.value).exists())) {
 		return undefined;
 	}
@@ -178,6 +185,7 @@ export async function resolveCdb(
 			cdbFile: input.cdbFile,
 			cdbPassword: input.cdbPassword,
 			env,
+			config,
 		});
 	} catch (error) {
 		if (
@@ -312,7 +320,7 @@ export async function expandCdbGroup(
 	return { targets, warnings, empty: false };
 }
 
-function resolutionFromEntry(
+export function resolutionFromEntry(
 	entry: WinBoxCdbEntry,
 	recordIndex: number,
 ): CdbResolution {

package/src/resolver/comment-kv.ts

@@ -17,9 +17,12 @@
  *   token (which may have been quoted).
  * - Free-form text outside well-formed `key=value` tokens is inert: no value,
  *   no warning.
- * - Allowlisted keys populate `values`. First-class CDB keys are rejected with
- *   a `cdb/reserved-option` warning (they have dedicated CDB tags and must not
- *   live in the comment). Any other key emits `cdb/unknown-option`.
+ * - Allowlisted keys populate `values`; lookup keys (`identity`/`mac`/`ip`)
+ *   populate `lookups`; geo facts (`lat`/`lon`/`altitude`/`altitude-type`,
+ *   issue #146 Slice 1) populate `geo` — all three are recognized (no warning).
+ *   First-class CDB keys are rejected with a `cdb/reserved-option` warning
+ *   (they have dedicated CDB tags and must not live in the comment). Any other
+ *   key emits `cdb/unknown-option`.
  *
  * This module is intentionally pure: it returns raw string values. Type
  * coercion (`validate` -> boolean, `timeout`/`port` -> integer) and settings
@@ -52,6 +55,23 @@ export const commentKvLookupKeys = ["identity", "mac", "ip"] as const;
 
 export type CommentKvLookupKey = (typeof commentKvLookupKeys)[number];
 
+/**
+ * Device GPS facts (issue #146 Slice 1): recognized comment-kv keys that are
+ * **facts, not settings** — queryable via `--where` and surfaced in `devices
+ * show`/`list`'s `location` block, but never coerced into resolver settings
+ * (distinct from both the override allowlist above and the lookup keys below).
+ * See `commands/devices/README.md` (Location / GPS) and `src/resolver/geo.ts`
+ * for parsing/validation.
+ */
+export const commentKvGeoKeys = [
+	"lat",
+	"lon",
+	"altitude",
+	"altitude-type",
+] as const;
+
+export type CommentKvGeoKey = (typeof commentKvGeoKeys)[number];
+
 /**
  * First-class CDB fields. These have dedicated CDB tags and must never be
  * expressed through the comment kv-soup; `devices set` refuses to write them
@@ -76,6 +96,8 @@ export interface CommentKvResult {
 	values: Partial<Record<CommentKvKey, string>>;
 	/** Lookup keys (identity/mac/ip), last-wins, raw string values. */
 	lookups: Partial<Record<CommentKvLookupKey, string>>;
+	/** Geo facts (lat/lon/altitude/altitude-type), last-wins, raw string values. */
+	geo: Partial<Record<CommentKvGeoKey, string>>;
 	warnings: CommentKvWarning[];
 }
 
@@ -95,6 +117,7 @@ const BARE_KEY = /^[A-Za-z][A-Za-z0-9_-]*$/;
 const allowSet = new Set<string>(commentKvAllowlist);
 const reservedSet = new Set<string>(commentKvReservedKeys);
 const lookupSet = new Set<string>(commentKvLookupKeys);
+const geoSet = new Set<string>(commentKvGeoKeys);
 
 function isAllowlistKey(key: string): key is CommentKvKey {
 	return allowSet.has(key);
@@ -104,6 +127,10 @@ function isLookupKey(key: string): key is CommentKvLookupKey {
 	return lookupSet.has(key);
 }
 
+function isGeoKey(key: string): key is CommentKvGeoKey {
+	return geoSet.has(key);
+}
+
 /**
  * Shell-word tokenize a comment, tracking which characters originated inside a
  * quoted span so the kv splitter can require a bare, unquoted key.
@@ -208,6 +235,7 @@ function splitKv(word: ShellWord): { key: string; value: string } | undefined {
 export function parseCommentKv(comment: string): CommentKvResult {
 	const values: Partial<Record<CommentKvKey, string>> = {};
 	const lookups: Partial<Record<CommentKvLookupKey, string>> = {};
+	const geo: Partial<Record<CommentKvGeoKey, string>> = {};
 	const warnings: CommentKvWarning[] = [];
 
 	for (const word of tokenize(comment)) {
@@ -219,6 +247,10 @@ export function parseCommentKv(comment: string): CommentKvResult {
 			lookups[kv.key] = kv.value;
 			continue;
 		}
+		if (isGeoKey(kv.key)) {
+			geo[kv.key] = kv.value;
+			continue;
+		}
 		if (isAllowlistKey(kv.key)) {
 			values[kv.key] = kv.value;
 			continue;
@@ -238,7 +270,29 @@ export function parseCommentKv(comment: string): CommentKvResult {
 		});
 	}
 
-	return { values, lookups, warnings };
+	return { values, lookups, geo, warnings };
+}
+
+/**
+ * Read EVERY well-formed `key=value` token from a comment as raw facts —
+ * **no allowlist filter, no warnings, no setting coercion**. This is the
+ * device-class selector surface (`--where`): derived facts a record carries in
+ * its comment (e.g. `board=RB5009`, `version=7.23.1`) are real selectors here,
+ * even though they are NOT settings (so {@link parseCommentKv} drops them with a
+ * `cdb/unknown-option` warning). Last token wins on a duplicate bare key. Core
+ * CDB fields (`target`/`identity`/`group`/`mac`) are layered ON TOP of this map
+ * by the selector and win, so a hand-written `group=`/`target=` comment token
+ * can never spoof a first-class field.
+ */
+export function parseRawCommentFacts(comment: string): Record<string, string> {
+	const facts: Record<string, string> = {};
+	for (const word of tokenize(comment)) {
+		const kv = splitKv(word);
+		if (kv) {
+			facts[kv.key] = kv.value;
+		}
+	}
+	return facts;
 }
 
 /**

package/src/resolver/config-file.ts

@@ -0,0 +1,136 @@
+/**
+ * `centrs.env` — the user-global config-file precedence tier (constitution:
+ * "Settings precedence", `default < config < comment-kv < env < cli`).
+ *
+ * Two read paths, deliberately kept separate:
+ *
+ * - {@link loadEnvFileDefaults} is what every *other* command calls to pick
+ *   up the `config` tier. It honors `CENTRS_SKIP_ENV_FILE` (returns `{}` when
+ *   set) and is safe to call unconditionally once per invocation.
+ * - {@link readSettingsFileRaw} is what the `settings` command itself calls.
+ *   `settings` always inspects/edits the real file regardless of
+ *   `--skip-env-file` — that flag controls whether *other* commands see the
+ *   file's values, not whether `settings` can see the file.
+ *
+ * The path resolver takes an injectable `env` map (mirroring
+ * `defaultCdbPath` in `src/devices.ts`) so tests can point
+ * `XDG_CONFIG_HOME` at a per-test temp directory instead of touching a real
+ * user's `~/.config`.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseBoolean, REFUSED_CONFIG_ENV_KEYS } from "./settings.ts";
+
+const ENV_XDG_CONFIG_HOME = "XDG_CONFIG_HOME";
+const ENV_HOME = "HOME";
+const ENV_SKIP_ENV_FILE = "CENTRS_SKIP_ENV_FILE";
+const CONFIG_RELATIVE_DIR = "tikoci";
+const CONFIG_FILE_NAME = "centrs.env";
+
+/**
+ * Resolve `${XDG_CONFIG_HOME:-~/.config}/tikoci/centrs.env`. This is a
+ * deliberately different base-path convention from `defaultCdbPath`'s
+ * `$HOME`-only scheme — the constitution and the settings spec already
+ * commit to XDG for this file specifically.
+ */
+export function defaultSettingsPath(
+	env?: Record<string, string | undefined>,
+): string {
+	const xdgConfigHome = env?.[ENV_XDG_CONFIG_HOME];
+	const configHome =
+		xdgConfigHome && xdgConfigHome.length > 0
+			? xdgConfigHome
+			: join(env?.[ENV_HOME] ?? homedir(), ".config");
+	return join(configHome, CONFIG_RELATIVE_DIR, CONFIG_FILE_NAME);
+}
+
+function isSkippingEnvFile(env: Record<string, string | undefined>): boolean {
+	const raw = env[ENV_SKIP_ENV_FILE];
+	if (raw === undefined) {
+		return false;
+	}
+	try {
+		return parseBoolean(raw, ENV_SKIP_ENV_FILE);
+	} catch {
+		return false;
+	}
+}
+
+export interface SettingsFileContents {
+	readonly exists: boolean;
+	/** Every non-blank, non-comment line verbatim, in file order. */
+	readonly lines: readonly string[];
+}
+
+/**
+ * Raw line-level read, no `CENTRS_SKIP_ENV_FILE` short-circuit. Used by
+ * `settings` itself, which must always see the real file.
+ */
+export async function readSettingsFileRaw(
+	path: string,
+): Promise<SettingsFileContents> {
+	const file = Bun.file(path);
+	if (!(await file.exists())) {
+		return { exists: false, lines: [] };
+	}
+	const text = await file.text();
+	return { exists: true, lines: text.split("\n") };
+}
+
+/**
+ * Parse `CENTRS_*=value` lines into a flat map. Blank lines and `#`
+ * comments are ignored; a later duplicate key wins. Malformed lines
+ * (no `=`, or a key that isn't a bare identifier) are silently skipped —
+ * a hand-edited file with foreign content should not fail every other
+ * command's settings resolution.
+ */
+export function parseEnvFileDefaults(
+	lines: readonly string[],
+): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const rawLine of lines) {
+		const line = rawLine.trim();
+		if (line.length === 0 || line.startsWith("#")) {
+			continue;
+		}
+		const separatorIndex = line.indexOf("=");
+		if (separatorIndex <= 0) {
+			continue;
+		}
+		const key = line.slice(0, separatorIndex).trim();
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+			continue;
+		}
+		result[key] = line.slice(separatorIndex + 1).trim();
+	}
+	return result;
+}
+
+/**
+ * The `config` tier every command resolver call should pass through. Empty
+ * (`{}`) when the file is absent or `CENTRS_SKIP_ENV_FILE` is active — never
+ * throws, since a missing or foreign-content file is not an error for
+ * anything but `settings` itself.
+ *
+ * Credential/self-referential keys ({@link REFUSED_CONFIG_ENV_KEYS}) are
+ * stripped even if a hand-edited file contains them: most resolvers already
+ * never consult `config` for these, but dropping them here means the shared
+ * `config` map itself never carries a secret, rather than relying on every
+ * call site to keep excluding it. `parseEnvFileDefaults` is left unfiltered
+ * so `settings print --all` can still inspect/redact a hand-added line.
+ */
+export async function loadEnvFileDefaults(
+	env: Record<string, string | undefined> = Bun.env,
+): Promise<Record<string, string>> {
+	if (isSkippingEnvFile(env)) {
+		return {};
+	}
+	const path = defaultSettingsPath(env);
+	const { lines } = await readSettingsFileRaw(path);
+	const parsed = parseEnvFileDefaults(lines);
+	for (const key of REFUSED_CONFIG_ENV_KEYS) {
+		delete parsed[key];
+	}
+	return parsed;
+}

package/src/resolver/facts.ts

@@ -0,0 +1,78 @@
+/**
+ * Device-class fact extraction + selector matching, shared by the fan-out
+ * resolver ({@link ../resolver/selection.ts | expandCdbSelection}) and
+ * `devices list` (`src/devices.ts`) so **both surfaces match `--where` /
+ * `--near` / `--bbox` against identical semantics**.
+ *
+ * This is a deliberate leaf module — it imports only from `comment-kv.ts`,
+ * `mac.ts`, and `geo.ts` (all leaves). It exists because `src/devices.ts` and
+ * `src/resolver/cdb.ts` form a cycle (`cdb.ts` imports `devices.ts`), so
+ * `devices.ts` cannot import `cdb.ts`'s `identityFromComment`/`macFromComment`
+ * nor `selection.ts`'s local `entryFacts` without a circular import. That forced
+ * the `--where` fact-builder to be duplicated in both files; hosting it here
+ * removes the duplication and the "keep the two in sync" hazard.
+ */
+
+import { parseCommentKv, parseRawCommentFacts } from "./comment-kv.ts";
+import {
+	canonicalizeGeoKey,
+	type DeviceLocation,
+	deviceLocation,
+} from "./geo.ts";
+import { normalizeMac } from "./mac.ts";
+
+/** One exact-match device-class clause (`attr=value`), AND-combined by callers. */
+export interface WhereClause {
+	key: string;
+	value: string;
+}
+
+/**
+ * Turn a CDB entry's `(comment, target, group)` into the device-class fact map
+ * `--where` matches against: every raw comment-kv token, with the core fields
+ * (`target`/`identity`/`group`/`mac`) layered **on top** so a hand-written
+ * comment token can never spoof a first-class field. MAC is normalized so a
+ * `mac=` lookup or a MAC `target` compares separator/case-insensitively.
+ */
+export function entryFacts(
+	comment: string,
+	target: string,
+	group: string,
+): Record<string, string> {
+	const facts = parseRawCommentFacts(comment);
+	const lookups = parseCommentKv(comment).lookups;
+	facts["target"] = target;
+	facts["identity"] = lookups.identity ?? target;
+	facts["group"] = group;
+	const mac = normalizeMac(lookups.mac ?? "") ?? normalizeMac(target);
+	if (mac !== undefined) {
+		facts["mac"] = mac;
+	}
+	return facts;
+}
+
+/**
+ * True when every `--where` clause matches the entry's facts (exact,
+ * AND-combined). The clause key is run through {@link canonicalizeGeoKey} here —
+ * the single seam — so a geo alias (`--where latitude=…`/`lng=…`/`elevation=…`)
+ * matches the canonical `lat`/`lon`/`altitude` fact the write side stores, on
+ * BOTH `devices list` and every fan-out command's `--where`. A no-op for
+ * non-geo keys.
+ */
+export function matchesWhere(
+	facts: Record<string, string>,
+	where: readonly WhereClause[],
+): boolean {
+	return where.every(
+		(clause) => facts[canonicalizeGeoKey(clause.key)] === clause.value,
+	);
+}
+
+/**
+ * Read a CDB entry's GPS location from its comment, or `undefined` when it
+ * carries no well-formed `lat`/`lon`. The single seam `--near`/`--bbox` use to
+ * exclude geo-less devices (never an error — they simply don't match).
+ */
+export function entryLocation(comment: string): DeviceLocation | undefined {
+	return deviceLocation(parseRawCommentFacts(comment));
+}