@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/fst/types.ts

@@ -2,49 +2,40 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Types for the FST gazetteer language model. The FST maps token sequences (place names) to
- *   (placetype, wof_id, parent_chain) entries — pre-computing the valid interpretations for each
- *   prefix of every place name in the gazetteer.
+ * @file Types for the FST gazetteer. These types map place-name token sequences to place entries.
  */
 
 import type { PathBuilderLike } from "path-ts"
 
+/**
+ * One place that a token sequence in the FST accepts.
+ */
 export interface PlaceEntry {
 	wofID: number
 	placetype: PlacetypeID
 	name: string
 	parentChain: number[]
 	/**
-	 * REFERENTIAL likelihood in [0, 1] — population-anchored (`referentialFromPopulation`), and the ONLY score the
-	 * decoder bias is allowed to read (ROAD_TO_V9 §2, ratified 2026-08-06).
-	 *
-	 * This field was called `importance` through format v4, where it carried whichever score the source database happened
-	 * to hold: the population proxy on a database with no `place_importance` table (which is every shipped
-	 * `fst-per-locale` binary), the Wikipedia score where the concordance join landed otherwise. The rename is the point
-	 * — a v4 artifact's value is a CONFLATION that cannot be told apart after the fact, which is why `fst-freshness.ts`
-	 * reports anything below {@link FST_FORMAT_VERSION} as format-stale rather than reading it as referential.
+	 * The population-based referential likelihood in [0, 1] that the decoder bias uses.
 	 */
 	referential: number
 	/**
-	 * Encyclopedic (Wikipedia) importance in [0, 1], fan-out-guarded per #1497. Carried for consumers that want to
-	 * DISPLAY salience; never read by the decoder or by any ranking.
-	 *
-	 * `undefined` = this place has no encyclopedic signal, or the artifact predates format 5. NEVER conflate either with
-	 * 0 — the meaning-of-zero rule; roughly 89% of the 2026-08-05 gazetteer's rows have no Wikipedia article at all.
+	 * The encyclopedic importance in [0, 1], for display only.
+	 * It is `null` when unavailable.
 	 */
-	encyclopedic?: number
+	encyclopedic: number | null
 	lat: number
 	lon: number
 	/**
-	 * Surface-ambiguity class (survey #4): how many DISTINCT countries carry a place with THIS entry's accepting surface,
-	 * counted over the whole admin DB at build time (clamped to 255). A property of the surface, not the place — the same
-	 * place reached via different alias surfaces reports each surface's own count. `undefined` = built without ambiguity
-	 * data (pre-2026-07-27 artifacts) — NEVER conflate with 1 (the unambiguous case); the meaning-of-zero rule.
+	 * The number of countries with a place of this surface, clamped to 255.
+	 * It is `null` when unavailable.
 	 */
-	crossCountryBranches?: number
+	crossCountryBranches: number | null
 }
 
+/**
+ * The placetypes the FST stores.
+ */
 export type PlacetypeID =
 	| "country"
 	| "region"
@@ -58,18 +49,18 @@ export type PlacetypeID =
 	| "dependency"
 	| "street_affix"
 
-export interface FSTMatchResult {
-	stateID: number
-	accepted: boolean
-	depth: number
-}
-
+/**
+ * One outgoing edge from an FST state, with the number of places its target state accepts.
+ */
 export interface FSTContinuation {
 	token: string
 	targetState: number
 	acceptingCount: number
 }
 
+/**
+ * The places a token path accepts and the tokens that can extend it.
+ */
 export interface FSTQueryResult {
 	path: string[]
 	stateID: number
@@ -77,6 +68,9 @@ export interface FSTQueryResult {
 	continuations: FSTContinuation[]
 }
 
+/**
+ * The build metadata stored in an FST binary's provenance trailer.
+ */
 export interface FSTProvenance {
 	builtAt: string
 	countries: string[]
@@ -85,93 +79,102 @@ export interface FSTProvenance {
 	edgeCount: number
 	nameInsertions: number
 	/**
-	 * How many places carried a non-zero REFERENTIAL score at build time. Named `importanceMatches` for stamp
-	 * compatibility with every artifact written before the two-score split — renaming the JSON key would make every
-	 * existing stamp unreadable, and the number means the same thing it always did on a population-built artifact.
+	 * The count of places with a non-zero referential score at build time.
+	 *
+	 * The key keeps its older name so that existing provenance stamps stay readable.
 	 */
 	importanceMatches: number
 	/**
-	 * How many places carried an ENCYCLOPEDIC score at build time. `undefined` on a pre-split build — which is not the
-	 * same as 0 (a v5 build against a population-only database), so the freshness report says the two in different
-	 * words.
+	 * The count of places with an encyclopedic score at build time.
+	 *
+	 * It is `null` for a build that predates the separate encyclopedic score.
+	 * The value `0` means a current build used a database without encyclopedic scores.
 	 */
-	encyclopedicMatches?: number
+	encyclopedicMatches: number | null
 	/**
-	 * How the builder obtained its two scores — an {@link ImportanceSplitSource}. Recorded so an artifact states, in its
-	 * own provenance, whether its encyclopedic channel is real, reconstructed from a legacy conflated column, or absent.
+	 * The {@link ImportanceSplitSource} that records whether the encyclopedic score is real,
+	 * reconstructed from a legacy column, or absent.
 	 */
-	importanceSource?: string
-	sourceDB?: string
+	importanceSource: string | null
+	sourceDB: string | null
 	/**
-	 * MD5 of the source database's bytes at build time — the artifact's link to the gazetteer it is a projection of.
+	 * The MD5 of the source database's bytes at build time.
+	 * The freshness check compares it.
 	 *
-	 * `sourceDB` records the PATH, which is exactly the field that cannot change when the bytes behind it do: the admin
-	 * DB is a sealed readonly artifact that a rebuild REPLACES in place, so every FST built before the 2026-08-04 swap
-	 * still names the current file and none of them was built from it. Compared by `fst-freshness.ts`.
+	 * `sourceDB` by itself cannot detect staleness.
+	 * A rebuild replaces the admin database at the same path.
 	 *
-	 * `undefined` = built before the stamp existed (every artifact predating 2026-08-05). NEVER conflate that with "built
-	 * from a database whose md5 is unknown" — the freshness check reports the two in different words.
+	 * The field is `null` for artifacts built before the stamp existed.
+	 * An unknown digest has a different value.
 	 */
-	sourceDBMD5?: string
+	sourceDBMD5: string | null
 	/**
-	 * Byte size of the source database at build time. Not redundant with {@link FSTProvenance.sourceDBMD5}: it survives a
-	 * truncated source and it is what makes a staleness warning legible — "5,273,722,880 → 5,372,076,032" names the
-	 * rebuild, a hex delta does not.
+	 * The byte size of the source database at build time.
+	 *
+	 * It detects a truncated source and makes a staleness warning readable.
 	 */
-	sourceDBBytes?: number
-	modelCardVersion?: string
+	sourceDBBytes: number | null
+	modelCardVersion: string | null
 	/**
-	 * Degenerate-surface curation policy applied at build time (absent = uncurated build).
+	 * The surface-exclusion policy applied at build time.
+	 * It is absent for an uncurated build.
 	 */
-	exclusionPolicy?: string
+	exclusionPolicy: string | null
 	/**
-	 * Name insertions refused by the curation policy.
+	 * The count of name insertions the exclusion policy rejected.
 	 */
-	excludedInsertions?: number
+	excludedInsertions: number | null
 }
 
+/**
+ * Options for building an FST from a WOF admin database.
+ */
 export interface BuildFSTOpts {
 	dbPath: PathBuilderLike
 	/**
-	 * Pre-computed identity of `dbPath` to stamp into provenance. Omit and the builder reads it via
-	 * `readWOFSourceIdentity` (sidecar-cached). Supply it when the digest is already in hand, or when the caller is
-	 * building from something whose identity it defines itself.
+	 * The precomputed identity of `dbPath` to record in provenance.
+	 *
+	 * When omitted, the builder reads it with `readWOFSourceIdentity`, which caches it in a sidecar file.
 	 */
 	sourceIdentity?: { md5: string; bytes: number }
 	countries?: string[]
 	placetypes?: PlacetypeID[]
 	languages?: string[]
 	/**
-	 * Degenerate-surface curation (build-time; the ASR-contextual-biasing "prune the bias list" discipline). A name whose
-	 * FULL normalized token sequence joins to a member of this set is never inserted — the surface carries no
-	 * discriminative value as a bias key (bare function words: "la"; bare street-type words: "boulevard"). The FST is a
-	 * bias list, not the gazetteer of record — the resolver's candidate tables are untouched, so excluded places stay
-	 * findable; they just stop nudging the decoder on degenerate keys. Keys must be `normalizeTokens(...).join(" ")`.
+	 * Surfaces the builder never inserts, such as the bare function word "la"
+	 * or the bare street type "boulevard".
+	 *
+	 * These surfaces do not discriminate between places when used as decoder bias keys.
+	 * The resolver's candidate tables still hold the excluded places.
+	 * Keys must be `normalizeTokens(...).join(" ")`.
 	 */
 	excludeSurfaces?: ReadonlySet<string>
 	/**
-	 * Compositional clause of the same policy: refuse a name whose EVERY normalized token is a member (e.g. "de la") — a
-	 * surface made entirely of function words cannot be discriminative. Source this from stopwords only, never
-	 * street-type words ("Avenue Road" is a real name; "de la" is not).
+	 * Tokens that a name must not consist of entirely, such as "de la".
+	 *
+	 * Build this set from stopwords only.
+	 * A street-type word can be part of a real name, as in "Avenue Road".
 	 */
 	excludeAllTokensOf?: ReadonlySet<string>
 	/**
-	 * Recorded verbatim into provenance when either exclusion set is supplied.
+	 * The policy label recorded in provenance when either exclusion set is supplied.
 	 */
 	exclusionPolicy?: string
 	/**
-	 * Surface-ambiguity classes (survey #4, 2026-07-27): normalized-join surface → the number of DISTINCT countries
-	 * (across the WHOLE admin DB, not just this build's country scope) with a place carrying that surface. When supplied,
-	 * every inserted place row records the count for ITS accepting surface (`PlaceEntry.crossCountryBranches`) — an entry
-	 * accessible under several surfaces records each surface's own count. Serialized into the place row's former `_pad`
-	 * byte with presence signaled by header flags bit0, so VERSION stays put and pre-ambiguity artifacts read as "no
-	 * data" (never "0 branches" — the meaning-of-zero rule). No decoder consumes it yet; consumers (FST-prior tempering,
-	 * the Option-A evidence channel) arrive behind their own measured checks.
+	 * Maps each normalized surface to the number of distinct countries in the whole
+	 * admin database with a place of that surface.
+	 *
+	 * When supplied, each inserted place entry records the count for its accepting
+	 * surface as `PlaceEntry.crossCountryBranches`.
+	 * A place reachable under several surfaces records each surface's own count.
 	 */
 	surfaceCountryCounts?: ReadonlyMap<string, number>
 	onProgress?: (phase: string, detail?: string) => void
 }
 
+/**
+ * Counts reported by an FST build.
+ */
 export interface BuildFSTResult {
 	stateCount: number
 	placeCount: number

package/lib/{fst/index.ts → fst.ts}

@@ -11,4 +11,5 @@ export * from "#fst/format"
 export * from "#fst/freshness"
 export * from "#fst/matcher"
 export * from "#fst/serialize"
+export { FST_FORMAT_VERSION } from "#fst/format"
 export * from "#fst/types"

package/lib/fts/query.ts

@@ -3,9 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Query shaping for the FTS5 lookup: placetype normalization and the MATCH-expression sanitizer.
- *   Both turn a caller's loose input into something SQLite's FTS5 parser accepts without throwing —
- *   an unescaped quote or a bare `*` is a syntax error, not an empty result.
+ * Query shaping for the FTS5 lookup: placetype normalization and the match-expression sanitizer.
  */
 
 import type { FindPlaceQuery, WOFPlacetype } from "#types"
@@ -17,30 +15,7 @@ export function normalizePlacetypes(p: FindPlaceQuery["placetype"]): WOFPlacetyp
 }
 
 /**
- * Make an arbitrary user-typed string safe for FTS5 MATCH.
- *
- * FTS5 has its own query syntax (`"phrase"`, `term1 OR term2`, `prefix*`, NEAR/N, etc.). Letting raw user input through
- * means a user typing `Paris's` or `St. (Petersburg)` causes a syntax error.
- *
- * Per-token rules:
- *
- * - Strip all punctuation except trailing `*` from each whitespace-separated token.
- * - **Trailing `*`** is preserved as FTS5 **prefix syntax** — `627*` becomes the literal `627*` (unquoted). The caller
- *   signaled they want a prefix; respect that.
- * - All other tokens are wrapped in `"..."` as a single-word phrase. Conservative — handles apostrophes, parens, accented
- *   input, etc. safely.
- * - Multiple tokens join with implicit AND.
- *
- * Examples:
- *
- * - `"Paris"` → `"Paris"` (phrase)
- * - `"627*"` → `627*` (prefix)
- * - `"St. (Petersburg)"` → `"St" "Petersburg"` (two phrases, AND-joined)
- * - `"Thiron-Gardais"` → `"Thiron" "Gardais"` (intra-token punctuation SPLITS — #945; fusing to `ThironGardais` matched
- *   nothing because the FTS doc tokenizes the hyphenated name as two terms)
- * - `"110 00"` with `fuseTokens` (postcode-typed) → `"110" "00"` per-token fused — the #920 name law
- * - `"Pari* TX"` → `Pari* "TX"` (mixed prefix + phrase)
- * - `"*"` alone → `""` (no body → drop)
+ * Make an arbitrary user-typed string safe for FTS5 match.
  */
 export function sanitizeFTSQuery(text: string, opts?: { fuseTokens?: boolean }): string {
 	const out: string[] = []
@@ -51,8 +26,7 @@ export function sanitizeFTSQuery(text: string, opts?: { fuseTokens?: boolean }):
 		if (!trimmed) continue
 		const hasPrefixStar = trimmed.endsWith("*")
 
-		// #920 name law (postcode-typed queries ONLY): delete intra-token punctuation and FUSE the
-		// remainder — postal names are stored in this collapsed shape ("SW1A" stays one term).
+		// Fused mode deletes intra-token punctuation because postal names are stored in that collapsed shape.
 		if (opts?.fuseTokens) {
 			const body = trimmed.replaceAll(/[^\p{L}\p{N}]/gu, "")
 
@@ -62,12 +36,7 @@ export function sanitizeFTSQuery(text: string, opts?: { fuseTokens?: boolean }):
 			continue
 		}
 
-		// Everything else SPLITS on intra-token punctuation — the behavior the docstring always
-		// promised ("St. (Petersburg)" → two phrases). The old code DELETED punctuation instead,
-		// fusing "Thiron-Gardais" into the unmatchable single term `ThironGardais` while the FTS
-		// doc holds two terms (#945 — the entire hyphenated-name class missed at the raw lookup;
-		// masked for years because pre-splice tokenizers never emitted hyphen-preserved values).
-		const parts = trimmed.split(/[^\p{L}\p{N}]+/u).filter((part) => part.length > 0)
+		const parts = trimmed.split(/[^\p{L}\p{N}]+/u).filter((part) => part.length)
 
 		if (!parts.length) continue
 
@@ -75,7 +44,7 @@ export function sanitizeFTSQuery(text: string, opts?: { fuseTokens?: boolean }):
 			const body = parts[i]!.replaceAll("*", "")
 
 			if (!body) continue
-			// The caller's trailing `*` applies to the FINAL part ("Thiron-Gard*" → "Thiron" Gard*).
+			// The caller's trailing `*` applies only to the final part.
 			out.push(hasPrefixStar && i === parts.length - 1 ? `${body}*` : `"${body.replaceAll('"', '""')}"`)
 		}
 	}

package/lib/fts.ts

@@ -0,0 +1,280 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { tableExists } from "@mailwoman/sqlite/introspection"
+
+/**
+ * The name of the FTS5 virtual table that indexes WOF place names for `match` queries.
+ */
+export const PLACE_SEARCH_TABLE = "place_search"
+
+/**
+ * The separator between aliases in the `alt_names` bag.
+ * It stops a phrase query from matching across two aliases.
+ *
+ * FTS5 assigns positions only to tokens.
+ * Spaces and punctuation are not tokens and would leave the aliases adjacent,
+ * but unicode61 indexes the Private Use Area codepoint U+E000 as a token.
+ *
+ * Query sanitizers strip this character, so no user query can match the separator.
+ */
+export const ALIAS_SEPARATOR = "\uE000"
+
+const ALIAS_SEPARATOR_CODEPOINT = ALIAS_SEPARATOR.codePointAt(0) as number
+
+/**
+ * Folds a query or name for exact-tier comparison by lowercasing, trimming
+ * and collapsing internal whitespace.
+ *
+ * Every exact-tier consumer uses this function, so its output compares equal to
+ * the aliases that {@link aliasBagExactMatch} parses.
+ */
+export function foldQueryText(input: string): string {
+	return input.toLowerCase().trim().replaceAll(/\s+/g, " ")
+}
+
+/**
+ * Returns whether any alias in an `alt_names` bag exactly equals the folded query.
+ *
+ * A bag without {@link ALIAS_SEPARATOR} is a legacy space-joined bag without alias boundaries.
+ * For such a bag, the function checks word-bounded containment only when no candidate matched strictly.
+ *
+ * Containment by itself would promote fragments such as "York" inside "New York City".
+ *
+ * @param altNames The `alt_names` bag from `place_search`, or null when the row has no aliases.
+ * @param normalizedQuery The query folded by {@link foldQueryText}.
+ * @param anyStrictExact Whether any candidate already matched on its canonical name or region abbreviation.
+ * Only legacy bags use it.
+ */
+export function aliasBagExactMatch(altNames: string | null, normalizedQuery: string, anyStrictExact: boolean): boolean {
+	if (!altNames || altNames === "" || !normalizedQuery) return false
+
+	if (altNames.includes(ALIAS_SEPARATOR)) {
+		return altNames.split(ALIAS_SEPARATOR).some((alias) => foldQueryText(alias) === normalizedQuery)
+	}
+
+	if (anyStrictExact) return false
+
+	return ` ${foldQueryText(altNames)} `.includes(` ${normalizedQuery} `)
+}
+
+/**
+ * The name of the R*Tree virtual table that indexes WOF place bounding boxes for bbox and proximity lookups.
+ */
+export const PLACE_BBOX_TABLE = "place_bbox"
+
+/**
+ * The name of the sparse table that stores `wof:population` per place.
+ *
+ * The lookup uses this value to apply the population ranking boost.
+ *
+ * A place without a row gets no boost and no penalty.
+ */
+export const PLACE_POPULATION_TABLE = "place_population"
+
+/**
+ * The name of the table of per-place `referential` and `encyclopedic` scores,
+ * built by `mailwoman gazetteer importance`.
+ *
+ * The lookup copies `encyclopedic` onto results without ranking by it.
+ * It refuses to read an older table with a single `importance` column.
+ */
+export const PLACE_IMPORTANCE_TABLE = "place_importance"
+
+/**
+ * The indexes a {@link buildPlaceSearchFTS} run built and their row counts.
+ */
+export interface BuildPlaceSearchFTSResult {
+	/**
+	 * Whether this call built the FTS5 index.
+	 * It is false when an existing index was kept.
+	 */
+	created: boolean
+
+	/**
+	 * The row count of the `place_search` table after the call.
+	 */
+	indexedRows: number
+
+	/**
+	 * Whether this call built the R*Tree bbox index.
+	 * It is false when an existing index was kept.
+	 */
+	bboxCreated: boolean
+
+	/**
+	 * The row count of the `place_bbox` R*Tree after the call.
+	 */
+	bboxIndexedRows: number
+
+	/**
+	 * The wall-clock duration of the whole build in milliseconds.
+	 */
+	durationMs: number
+}
+
+/**
+ * Options for {@link buildPlaceSearchFTS}.
+ */
+export interface BuildPlaceSearchFTSOpts {
+	/**
+	 * Whether to drop and rebuild existing `place_search` and `place_bbox` tables,
+	 * such as after an `spr` or `names` update.
+	 * By default an existing index is kept.
+	 */
+	drop?: boolean
+
+	/**
+	 * Receives each build phase as it begins.
+	 * A planet-scale build takes minutes to populate.
+	 */
+	onProgress?: (
+		phase: "checking" | "dropping" | "creating" | "populating" | "creating-bbox" | "populating-bbox" | "done",
+		detail?: string
+	) => void
+}
+
+/**
+ * Builds the `place_search` FTS5 table and the `place_bbox` R*Tree from a WOF
+ * database's `spr` and `names` tables.
+ *
+ * Without `drop: true`, an existing index is kept.
+ */
+export function buildPlaceSearchFTS<DB>(
+	db: DatabaseClient<DB>,
+	opts: BuildPlaceSearchFTSOpts = {}
+): BuildPlaceSearchFTSResult {
+	const start = Date.now()
+	const onProgress = opts.onProgress ?? (() => {})
+
+	onProgress("checking")
+	const ftsExisting = tableExists(db, PLACE_SEARCH_TABLE)
+	const bboxExisting = tableExists(db, PLACE_BBOX_TABLE)
+
+	let ftsCreated = false
+
+	if (ftsExisting && opts.drop) {
+		onProgress("dropping", PLACE_SEARCH_TABLE)
+		db.exec(`DROP TABLE ${PLACE_SEARCH_TABLE}`)
+	}
+
+	if (!ftsExisting || opts.drop) {
+		onProgress("creating")
+
+		db.exec(`
+			CREATE VIRTUAL TABLE ${PLACE_SEARCH_TABLE} USING fts5(
+				wof_id UNINDEXED,
+				name,
+				alt_names,
+				tokenize = 'unicode61 remove_diacritics 2'
+			);
+		`)
+
+		onProgress("populating")
+
+		db.exec(`
+			INSERT INTO ${PLACE_SEARCH_TABLE} (wof_id, name, alt_names)
+			SELECT
+				spr.id,
+				spr.name,
+				COALESCE((
+					SELECT GROUP_CONCAT(
+						REPLACE(name, char(${ALIAS_SEPARATOR_CODEPOINT}), ' '),
+						' ' || char(${ALIAS_SEPARATOR_CODEPOINT}) || ' '
+					) || ' ' || char(${ALIAS_SEPARATOR_CODEPOINT})
+					FROM names WHERE names.id = spr.id
+				), '')
+			FROM spr
+			WHERE spr.is_current != 0
+				AND spr.is_deprecated = 0
+				AND spr.name IS NOT NULL;
+		`)
+
+		ftsCreated = true
+	}
+
+	const ftsCountRow = db.prepare(`SELECT COUNT(*) AS n FROM ${PLACE_SEARCH_TABLE}`).get() as { n: number }
+
+	let bboxCreated = false
+
+	if (bboxExisting && opts.drop) {
+		onProgress("dropping", PLACE_BBOX_TABLE)
+		db.exec(`DROP TABLE ${PLACE_BBOX_TABLE}`)
+	}
+
+	if (!bboxExisting || opts.drop) {
+		onProgress("creating-bbox")
+
+		db.exec(`
+			CREATE VIRTUAL TABLE ${PLACE_BBOX_TABLE} USING rtree(
+				id,
+				min_lat, max_lat,
+				min_lon, max_lon
+			);
+		`)
+
+		onProgress("populating-bbox")
+
+		db.exec(`
+			INSERT INTO ${PLACE_BBOX_TABLE} (id, min_lat, max_lat, min_lon, max_lon)
+			SELECT
+				spr.id,
+				spr.min_latitude,
+				spr.max_latitude,
+				spr.min_longitude,
+				spr.max_longitude
+			FROM spr
+			WHERE spr.is_current != 0
+				AND spr.is_deprecated = 0
+				AND spr.min_latitude IS NOT NULL
+				AND spr.max_latitude IS NOT NULL
+				AND spr.min_longitude IS NOT NULL
+				AND spr.max_longitude IS NOT NULL
+				AND NOT (spr.min_latitude = 0 AND spr.max_latitude = 0
+				     AND spr.min_longitude = 0 AND spr.max_longitude = 0);
+		`)
+
+		bboxCreated = true
+	}
+
+	const bboxCountRow = db.prepare(`SELECT COUNT(*) AS n FROM ${PLACE_BBOX_TABLE}`).get() as { n: number }
+
+	onProgress(
+		"done",
+		`${ftsCountRow.n} FTS rows + ${bboxCountRow.n} bbox rows ` +
+			`(${ftsCreated ? "built" : "preexisting"} / ${bboxCreated ? "built" : "preexisting"})`
+	)
+
+	return {
+		created: ftsCreated,
+		indexedRows: ftsCountRow.n,
+		bboxCreated,
+		bboxIndexedRows: bboxCountRow.n,
+		durationMs: Date.now() - start,
+	}
+}
+
+/**
+ * Returns whether the connected database has the `place_search` FTS table.
+ */
+export function placeSearchFTSExists<DB>(db: DatabaseClient<DB>): boolean {
+	return tableExists(db, PLACE_SEARCH_TABLE)
+}
+
+/**
+ * Returns whether the connected database has the `place_bbox` R*Tree table.
+ */
+export function placeBboxExists<DB>(db: DatabaseClient<DB>): boolean {
+	return tableExists(db, PLACE_BBOX_TABLE)
+}
+
+/**
+ * Returns whether the connected database has the `place_population` table.
+ */
+export function placePopulationExists<DB>(db: DatabaseClient<DB>): boolean {
+	return tableExists(db, PLACE_POPULATION_TABLE)
+}