@mailwoman/resolver-wof-sqlite 9.2.0 → 9.3.0

package/{sharding.ts → lib/extracts.ts}

@@ -1,16 +1,18 @@
+import { basename } from "path-ts"
+
 /**
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Multi-shard support for `WOFSQLitePlaceLookup` — opens multiple WOF SQLite distributions on one
- *   connection via `ATTACH DATABASE`, and routes queries to the right shard based on placetype.
+ *   Multi-extract support for `WOFSQLitePlaceLookup` — opens multiple WOF SQLite distributions on one
+ *   connection via `ATTACH DATABASE`, and routes queries to the right extract based on placetype.
  *
  *   ## The FTS5 syntax rule that drove this design
  *
  *   The naive `SELECT … FROM pc.place_search WHERE pc.place_search MATCH ?` fails — SQLite parses the
  *   schema-qualified table on the left of MATCH as "column place_search of table pc". Discovered in
- *   the spike at PR review time; documented as `_SHARD_RULE.md` should it ever bite again.
+ *   the spike at PR review time; documented as `_EXTRACT_RULE.md` should it ever bite again.
  *
  *   The working form: schema-qualified in FROM, bare table name in MATCH:
  *
@@ -18,15 +20,13 @@
  *   SELECT … FROM pc.place_search WHERE place_search MATCH ?
  * ```
  *
- *   Identical table names across attached shards (which is what we have — every shard ships its own
+ *   Identical table names across attached extracts (which is what we have — every extract ships its own
  *   `place_search` + `place_bbox`) are fine because the bare-name MATCH resolves against FROM
  *   scope.
  */
 
-import { basename } from "node:path"
-
 /**
- * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS <name>` so each shard
+ * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS <name>` so each extract
  * gets a stable, predictable handle.
  *
  * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`) suffix, then replaces `-` with
@@ -39,7 +39,7 @@ import { basename } from "node:path"
  * - `whosonfirst-data-admin-latest.db` → `admin`
  * - `my-custom.db` → `my_custom`
  *
- * Callers can override the derived name explicitly via `ShardConfig.schemaName` when the filename doesn't follow WOF
+ * Callers can override the derived name explicitly via `ExtractConfig.schemaName` when the filename doesn't follow WOF
  * convention.
  */
 export function deriveSchemaName(path: string): string {
@@ -57,11 +57,11 @@ export function deriveSchemaName(path: string): string {
 }
 
 /**
- * Per-shard configuration. The simple form is just a path string — the schema name is derived from it. The object form
- * lets callers override the derived schema name (useful when a filename doesn't follow WOF convention) or attach an
- * extra hint about which placetypes route here.
+ * Per-extract configuration. The simple form is just a path string — the schema name is derived from it. The object
+ * form lets callers override the derived schema name (useful when a filename doesn't follow WOF convention) or attach
+ * an extra hint about which placetypes route here.
  */
-export interface ShardConfig {
+export interface ExtractConfig {
 	path: string
 	/**
 	 * Override the auto-derived schema name. Useful when the filename doesn't match WOF convention or when you want a
@@ -69,9 +69,9 @@ export interface ShardConfig {
 	 */
 	schemaName?: string
 	/**
-	 * Optional explicit list of placetypes this shard serves. When set, queries against any listed placetype are routed
-	 * to this shard. When omitted, routing falls back to a name-match heuristic: a shard whose `schemaName` contains the
-	 * placetype as a substring (e.g. `postalcode_us` for `postalcode` queries) is preferred for that placetype.
+	 * Optional explicit list of placetypes this extract serves. When set, queries against any listed placetype are routed
+	 * to this extract. When omitted, routing falls back to a name-match heuristic: a extract whose `schemaName` contains
+	 * the placetype as a substring (e.g. `postalcode_us` for `postalcode` queries) is preferred for that placetype.
 	 */
 	placetypes?: readonly string[]
 }
@@ -80,7 +80,7 @@ export interface ShardConfig {
  * Resolved post-derivation: paired path + chosen schema name + (possibly empty) placetypes hint. Used internally by
  * `WOFSQLitePlaceLookup` so the routing logic operates on uniform structures.
  */
-export interface ResolvedShard {
+export interface ResolvedExtract {
 	path: string
 	schemaName: string
 	placetypes: readonly string[]
@@ -93,40 +93,40 @@ const SQLITE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/u
 
 /**
  * Normalize the user-provided `databasePath` opt (which may be a single string, an array of strings, or an array of
- * `ShardConfig` objects) into a uniform `ResolvedShard[]`.
+ * `ExtractConfig` objects) into a uniform `ResolvedExtract[]`.
  *
- * The first shard becomes `main` regardless of its derived schema name — that's the SQLite convention. Subsequent
- * shards keep their derived (or override) schema name.
+ * The first extract becomes `main` regardless of its derived schema name — that's the SQLite convention. Subsequent
+ * extracts keep their derived (or override) schema name.
  */
-export function resolveShards(input: string | ReadonlyArray<string | ShardConfig>): ResolvedShard[] {
+export function resolveExtracts(input: string | ReadonlyArray<string | ExtractConfig>): ResolvedExtract[] {
 	const list = typeof input === "string" ? [input] : input
 
-	if (!list.length) throw new Error("resolveShards: at least one shard is required")
+	if (!list.length) throw new Error("resolveExtracts: at least one extract is required")
 
 	const seen = new Set<string>()
-	const out: ResolvedShard[] = []
+	const out: ResolvedExtract[] = []
 
 	for (let i = 0; i < list.length; i++) {
 		const entry = list[i]!
-		const cfg: ShardConfig = typeof entry === "string" ? { path: entry } : entry
+		const cfg: ExtractConfig = typeof entry === "string" ? { path: entry } : entry
 		const derived = cfg.schemaName ?? deriveSchemaName(cfg.path)
 
 		if (!SQLITE_IDENT_RE.test(derived)) {
 			throw new Error(
-				`resolveShards: schema name ${JSON.stringify(derived)} is not a valid SQLite identifier ` +
+				`resolveExtracts: schema name ${JSON.stringify(derived)} is not a valid SQLite identifier ` +
 					`(derived from path ${JSON.stringify(cfg.path)}). Pass an explicit ` +
 					`{ path, schemaName } to override.`
 			)
 		}
 
-		// The first shard is always main per SQLite semantics — its derived name is informational
-		// only. Subsequent shards must have unique non-main names.
+		// The first extract is always main per SQLite semantics — its derived name is informational
+		// only. Subsequent extracts must have unique non-main names.
 		const schemaName = i === 0 ? "main" : derived
 
 		if (i > 0 && (schemaName === "main" || seen.has(schemaName))) {
 			throw new Error(
-				`resolveShards: schema name ${JSON.stringify(schemaName)} collides ` +
-					`(either with "main" or another shard). Pass an explicit { path, schemaName }.`
+				`resolveExtracts: schema name ${JSON.stringify(schemaName)} collides ` +
+					`(either with "main" or another extract). Pass an explicit { path, schemaName }.`
 			)
 		}
 
@@ -143,36 +143,39 @@ export function resolveShards(input: string | ReadonlyArray<string | ShardConfig
 }
 
 /**
- * Pick the shard to route a query to given the requested placetype(s).
+ * Pick the extract to route a query to given the requested placetype(s).
  *
  * Routing rules, in order:
  *
- * 1. If any shard has explicit `placetypes` that includes the requested placetype, use it.
- * 2. Otherwise, if a non-main shard's `schemaName` matches the placetype (e.g. `postalcode_us` matches `postalcode`), use
- *    it.
+ * 1. If any extract has explicit `placetypes` that includes the requested placetype, use it.
+ * 2. Otherwise, if a non-main extract's `schemaName` matches the placetype (e.g. `postalcode_us` matches `postalcode`),
+ *    use it.
  * 3. Otherwise, fall back to `main`.
  *
- * This deliberately doesn't UNION across shards — BM25 scores aren't comparable across separately- indexed corpora, and
- * the typical mailwoman query has a single placetype anyway. If a caller needs cross-shard results they can issue two
- * `findPlace` calls.
+ * This deliberately doesn't UNION across extracts — BM25 scores aren't comparable across separately- indexed corpora,
+ * and the typical mailwoman query has a single placetype anyway. If a caller needs cross-extract results they can issue
+ * two `findPlace` calls.
  */
 /**
- * All placetype-matching shards, in routing order (the country-aware pick chooses among these). Used by the bias path:
- * a country-less postcode query with proximity hints fans out across every matching shard and merges, because
- * single-shard routing would hide the cross-country ambiguity the hints exist to resolve ("48026" lives in
+ * All placetype-matching extracts, in routing order (the country-aware pick chooses among these). Used by the bias
+ * path: a country-less postcode query with proximity hints fans out across every matching extract and merges, because
+ * single-extract routing would hide the cross-country ambiguity the hints exist to resolve ("48026" lives in
  * postalcode-us AND postalcode-intl).
  */
-export function pickShardsForPlacetype(shards: ResolvedShard[], placetype: string | undefined): ResolvedShard[] {
-	if (!placetype) return [shards[0]!]
-	const matches: ResolvedShard[] = []
-
-	for (const s of shards) {
+export function pickExtractsForPlacetype(
+	extracts: ResolvedExtract[],
+	placetype: string | undefined
+): ResolvedExtract[] {
+	if (!placetype) return [extracts[0]!]
+	const matches: ResolvedExtract[] = []
+
+	for (const s of extracts) {
 		if (s.placetypes.includes(placetype)) {
 			matches.push(s)
 		}
 	}
 
-	for (const s of shards) {
+	for (const s of extracts) {
 		if (s.schemaName === "main" || matches.includes(s)) continue
 
 		if (
@@ -184,19 +187,19 @@ export function pickShardsForPlacetype(shards: ResolvedShard[], placetype: strin
 		}
 	}
 
-	return matches.length ? matches : [shards[0]!]
+	return matches.length ? matches : [extracts[0]!]
 }
 
-export function pickShardForPlacetype(
-	shards: ResolvedShard[],
+export function pickExtractForPlacetype(
+	extracts: ResolvedExtract[],
 	placetype: string | undefined,
 	opts?: {
 		/**
-		 * #920: the query's country constraint, when the caller has one. With MULTIPLE shards matching a placetype
-		 * (postalcode-us + postalcode-geonames-tail), first-match routing sent every postcode query to the first shard and
-		 * starved the rest — a FI postcode could never reach the tail shard. When `country` is given and a matching shard's
-		 * probed country set contains it, that shard wins; shards without the country are skipped; the placetype-match
-		 * order remains the tiebreak when no shard claims the country (or none was probed).
+		 * #920: the query's country constraint, when the caller has one. With MULTIPLE extracts matching a placetype
+		 * (postalcode-us + postalcode-geonames-tail), first-match routing sent every postcode query to the first extract
+		 * and starved the rest — a FI postcode could never reach the tail extract. When `country` is given and a matching
+		 * extract's probed country set contains it, that extract wins; extracts without the country are skipped; the
+		 * placetype-match order remains the tiebreak when no extract claims the country (or none was probed).
 		 */
 		country?: string
 		/**
@@ -204,18 +207,18 @@ export function pickShardForPlacetype(
 		 */
 		countriesBySchema?: ReadonlyMap<string, ReadonlySet<string>>
 	}
-): ResolvedShard {
-	if (!placetype) return shards[0]!
+): ResolvedExtract {
+	if (!placetype) return extracts[0]!
 
-	const matches: ResolvedShard[] = []
+	const matches: ResolvedExtract[] = []
 
-	for (const s of shards) {
+	for (const s of extracts) {
 		if (s.placetypes.includes(placetype)) {
 			matches.push(s)
 		}
 	}
 
-	for (const s of shards) {
+	for (const s of extracts) {
 		if (s.schemaName === "main" || matches.includes(s)) continue
 
 		// Substring match: `postalcode_us` matches `postalcode`. Conservative — requires the
@@ -230,7 +233,7 @@ export function pickShardForPlacetype(
 		}
 	}
 
-	if (!matches.length) return shards[0]!
+	if (!matches.length) return extracts[0]!
 
 	if (opts?.country && opts.countriesBySchema) {
 		for (const s of matches) {

package/{fst-autocomplete.ts → lib/fst/autocomplete.ts}

@@ -26,9 +26,9 @@ import type {
 } from "@mailwoman/ancestrie"
 import { autocomplete as ancestrieAutocomplete } from "@mailwoman/ancestrie"
 
-import type { FSTMatcher } from "./fst-matcher.ts"
-import { normalizeTokens } from "./fst-matcher.ts"
-import type { PlaceEntry } from "./fst-types.ts"
+import type { FSTMatcher } from "#fst/matcher"
+import { normalizeTokens } from "#fst/matcher"
+import type { PlaceEntry } from "#fst/types"
 
 export interface AutocompleteResult {
 	query: string
@@ -85,7 +85,7 @@ function topByReferential(entries: readonly PlaceEntry[], k: number): PlaceEntry
 }
 
 /**
- * {@link FSTMatcher} presented through ancestrie's storage seam. Records carry the {@link PlaceEntry} itself as the
+ * {@link FSTMatcher} presented through ancestrie's storage interface. Records carry the {@link PlaceEntry} itself as the
  * payload, so the entry that WINS the algorithm's shallowest-depth rule is the entry whose fields the suggestion
  * reports — a side lookup keyed on id could pick a different surface's row (`crossCountryBranches` differs per
  * surface).

package/{fst-builder.ts → lib/fst/builder.ts}

@@ -11,14 +11,16 @@
  *   PlaceEntry at terminals → return FSTMatcher.
  */
 
-import { DatabaseSync } from "node:sqlite"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { resolvePath } from "path-ts"
 
-import { readWOFSourceIdentity } from "./fst-freshness.ts"
-import type { FSTNode } from "./fst-matcher.ts"
-import { FSTMatcher, normalizeTokens } from "./fst-matcher.ts"
-import type { BuildFSTOpts, BuildFSTResult, FSTProvenance, PlaceEntry, PlacetypeID } from "./fst-types.ts"
-import { loadImportanceSplit } from "./place-importance-schema.ts"
-import { allRows, getRow } from "./sqlite-utils.ts"
+import { readWOFSourceIdentity } from "#fst/freshness"
+import type { FSTNode } from "#fst/matcher"
+import { FSTMatcher, normalizeTokens } from "#fst/matcher"
+import type { BuildFSTOpts, BuildFSTResult, FSTProvenance, PlaceEntry, PlacetypeID } from "#fst/types"
+import { loadImportanceSplit } from "#place-importance-schema"
+import type { WOFDatabase } from "#schema"
+import { allRows, getRow } from "#sqlite-utils"
 
 const DEFAULT_PLACETYPES: PlacetypeID[] = [
 	"country",
@@ -54,18 +56,19 @@ interface NameRow {
 	privateuse: string
 }
 
-export function buildFSTFromWOF(opts: BuildFSTOpts): {
+export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 	matcher: FSTMatcher
 	provenance: FSTProvenance
 	result: BuildFSTResult
-} {
+}> {
 	const countries = opts.countries ?? DEFAULT_COUNTRIES
 	const placetypes = opts.placetypes ?? DEFAULT_PLACETYPES
 	const languages = opts.languages ?? DEFAULT_LANGUAGES
 	const progress = opts.onProgress ?? (() => {})
+	const dbPath = resolvePath(opts.dbPath)
 
-	progress("open", opts.dbPath)
-	const db = new DatabaseSync(opts.dbPath, { open: true })
+	progress("open", dbPath)
+	using db = new DatabaseClient<WOFDatabase>(dbPath, { open: true })
 
 	// Phase 1: Load all matching SPR rows.
 	progress("spr", `Loading places for countries=[${countries}], placetypes=[${placetypes}]`)
@@ -324,8 +327,6 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 		}
 	}
 
-	db.close()
-
 	progress(
 		"done",
 		`Built trie: ${nodes.length} states, ${insertCount} name insertions` +
@@ -341,8 +342,8 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 	// and is free whenever the `.md5` sidecar is current, which the admin build already writes.
 	// `sourceIdentity` lets a caller that already knows the digest (or is building from something that
 	// is not a file at all) supply it instead.
-	progress("stamp", `Reading source identity for ${opts.dbPath}`)
-	const source = opts.sourceIdentity ?? readWOFSourceIdentity(opts.dbPath)
+	progress("stamp", `Reading source identity for ${dbPath}`)
+	const source = opts.sourceIdentity ?? (await readWOFSourceIdentity(dbPath))
 
 	const provenance: FSTProvenance = {
 		builtAt: new Date().toISOString(),
@@ -354,7 +355,7 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 		importanceMatches: split.referential.size,
 		encyclopedicMatches: split.encyclopedic.size,
 		importanceSource: split.source,
-		sourceDB: opts.dbPath,
+		sourceDB: dbPath,
 		sourceDBMD5: source.md5,
 		sourceDBBytes: source.bytes,
 		...(excludeSurfaces !== undefined || excludeAllTokensOf !== undefined

package/{fst-deserialize-web.ts → lib/fst/deserialize-web.ts}

@@ -10,87 +10,27 @@
  *   build-time operation).
  */
 
-import { tryParsingJSON } from "@mailwoman/core/objects"
-
-import type { FSTNode } from "./fst-matcher.ts"
-import { FSTMatcher } from "./fst-matcher.ts"
-import type { FSTProvenance, PlaceEntry, PlacetypeID } from "./fst-types.ts"
-
-/**
- * Format version that widened the per-state edge and place counters from 16 to 32 bits, growing the state entry from 12
- * to 16 bytes. Readers branch on it to stay backward-compatible with v2/v3 files.
- */
-const VERSION_WIDE_STATE_COUNTERS = 4
-
-/**
- * State-table entry size in bytes at or above {@link VERSION_WIDE_STATE_COUNTERS}.
- */
-const WIDE_STATE_ENTRY_SIZE = 16
-
-/**
- * State-table entry size in bytes below {@link VERSION_WIDE_STATE_COUNTERS}.
- */
-const NARROW_STATE_ENTRY_SIZE = 12
-
-/**
- * First format version carrying the trailing metadata block; older files simply have none.
- */
-const VERSION_WITH_METADATA = 3
-
-const HEADER_SIZE = 32
-const EDGE_ENTRY_SIZE = 8
-
-/**
- * Format version that split the single `importance` float into `referential` + `encyclopedic` (ROAD_TO_V9 §2 R1),
- * growing the place entry from 56 to 60 bytes. Mirrors `fst-serialize.ts`'s constant of the same name.
- */
-const VERSION_TWO_SCORE_SPLIT = 5
-
-/**
- * Place-entry size in bytes at or above {@link VERSION_TWO_SCORE_SPLIT}.
- */
-const SPLIT_PLACE_ENTRY_SIZE = 60
-
-/**
- * Place-entry size in bytes below {@link VERSION_TWO_SCORE_SPLIT}.
- */
-const LEGACY_PLACE_ENTRY_SIZE = 56
-
-/**
- * Byte offset of the encyclopedic float inside a v5 place entry — immediately after the 8-slot parent chain.
- */
-const ENCYCLOPEDIC_OFFSET = 56
-
-/**
- * `placeFlags` bit 0 (byte `pp+7`, v5+): this place carries an encyclopedic score. Per-place because absence is the
- * common case; see `fst-serialize.ts`.
- */
-const PLACE_FLAG_HAS_ENCYCLOPEDIC = 1
-/**
- * "FST\0".
- */
-const MAGIC_BYTES = [0x46, 0x53, 0x54, 0x00]
-/**
- * Must track the serializer's VERSION (fst-serialize.ts, currently 5). The v3 provenance + v4 16-byte-state/u32-count
- * layout logic below already matches the Node deserializer; only this gate was left stale at 2, so the browser FST
- * loader rejected every real (v4) artifact. It was left stale again at 4 by the v5 two-score split until this line
- * moved with it — the gate is a SEPARATE number from the layout branches, which is exactly why it keeps drifting.
- */
-const MAX_VERSION = 5
-
-const PLACETYPE_ORDER: readonly PlacetypeID[] = [
-	"country",
-	"region",
-	"county",
-	"locality",
-	"localadmin",
-	"borough",
-	"neighbourhood",
-	"postalcode",
-	"campus",
-	"dependency",
-	"street_affix",
-]
+import { tryParsingJSON } from "@mailwoman/core/json"
+
+import {
+	EDGE_ENTRY_SIZE,
+	ENCYCLOPEDIC_OFFSET,
+	FST_FORMAT_VERSION,
+	FST_MAGIC_BYTES,
+	HEADER_SIZE,
+	LEGACY_PLACE_ENTRY_SIZE,
+	NARROW_STATE_ENTRY_SIZE,
+	PLACE_FLAG_HAS_ENCYCLOPEDIC,
+	PLACETYPE_ORDER,
+	SPLIT_PLACE_ENTRY_SIZE,
+	VERSION_TWO_SCORE_SPLIT,
+	VERSION_WIDE_STATE_COUNTERS,
+	VERSION_WITH_METADATA,
+	WIDE_STATE_ENTRY_SIZE,
+} from "#fst/format"
+import type { FSTNode } from "#fst/matcher"
+import { FSTMatcher } from "#fst/matcher"
+import type { FSTProvenance, PlaceEntry } from "#fst/types"
 
 export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 	const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : input
@@ -100,18 +40,18 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 	if (bytes.byteLength < HEADER_SIZE) throw new Error("FST buffer too small for header")
 
 	if (
-		bytes[0] !== MAGIC_BYTES[0] ||
-		bytes[1] !== MAGIC_BYTES[1] ||
-		bytes[2] !== MAGIC_BYTES[2] ||
-		bytes[3] !== MAGIC_BYTES[3]
+		bytes[0] !== FST_MAGIC_BYTES[0] ||
+		bytes[1] !== FST_MAGIC_BYTES[1] ||
+		bytes[2] !== FST_MAGIC_BYTES[2] ||
+		bytes[3] !== FST_MAGIC_BYTES[3]
 	) {
 		throw new Error("FST magic mismatch")
 	}
 
 	const version = view.getUint16(4, true)
 
-	if (version < 1 || version > MAX_VERSION) {
-		throw new Error(`FST version ${version} unsupported (expected 1..${MAX_VERSION})`)
+	if (version < 1 || version > FST_FORMAT_VERSION) {
+		throw new Error(`FST version ${version} unsupported (expected 1..${FST_FORMAT_VERSION})`)
 	}
 
 	const isV2 = version >= 2

package/lib/fst/format.ts

@@ -0,0 +1,106 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The FST binary-format constants, shared by the Node serializer/deserializer (`fst-serialize.ts`)
+ *   and the browser deserializer (`fst-deserialize-web.ts`). Platform-free by design — no Buffer at
+ *   module scope; both runtimes convert {@link FST_MAGIC_BYTES} themselves.
+ */
+
+import type { PlacetypeID } from "#fst/types"
+
+/**
+ * Format version this tree WRITES and the maximum either deserializer accepts, published so a freshness guard can call
+ * an older artifact format-stale without re-typing the number (mirrors `REQUIRED_PAIR_INDEX_SCHEMA`'s role for PIX1 —
+ * see `fst-freshness.ts`).
+ *
+ * ONE constant for the writer and both readers, deliberately. The browser reader's acceptance criterion was a SEPARATE
+ * `MAX_VERSION` number from the layout branches, and it drifted twice: left stale at 2 when the v4 wide-state layout
+ * shipped (rejecting every real artifact), and stale again at 4 through the v5 two-score split until the line moved by
+ * hand. A check that is the writer's version cannot drift from it.
+ */
+export const FST_FORMAT_VERSION = 5
+
+/**
+ * Fixed header size in bytes: magic, version, and the section offsets that follow it.
+ */
+export const HEADER_SIZE = 32
+
+/**
+ * Edge-table entry: the transition label and the target state index.
+ */
+export const EDGE_ENTRY_SIZE = 8
+
+/**
+ * Format version that widened the per-state edge and place counters from 16 to 32 bits, growing the state entry from 12
+ * to 16 bytes. Readers branch on it to stay backward-compatible with v2/v3 files.
+ */
+export const VERSION_WIDE_STATE_COUNTERS = 4
+
+/**
+ * State-table entry size in bytes at or above {@link VERSION_WIDE_STATE_COUNTERS}.
+ */
+export const WIDE_STATE_ENTRY_SIZE = 16
+
+/**
+ * State-table entry size in bytes below {@link VERSION_WIDE_STATE_COUNTERS}.
+ */
+export const NARROW_STATE_ENTRY_SIZE = 12
+
+/**
+ * First format version carrying the trailing metadata block; older files simply have none.
+ */
+export const VERSION_WITH_METADATA = 3
+
+/**
+ * Format version that split the single `importance` float into `referential` + `encyclopedic` (ROAD_TO_V9 §2 R1),
+ * growing the place entry from 56 to 60 bytes and claiming the previously-reserved `pp+7` byte as
+ * {@link PLACE_FLAG_HAS_ENCYCLOPEDIC}.
+ */
+export const VERSION_TWO_SCORE_SPLIT = 5
+
+/**
+ * Place-entry size in bytes at or above {@link VERSION_TWO_SCORE_SPLIT}.
+ */
+export const SPLIT_PLACE_ENTRY_SIZE = 60
+
+/**
+ * Place-entry size in bytes below {@link VERSION_TWO_SCORE_SPLIT}.
+ */
+export const LEGACY_PLACE_ENTRY_SIZE = 56
+
+/**
+ * Byte offset of the encyclopedic float inside a v5 place entry — immediately after the 8-slot parent chain.
+ */
+export const ENCYCLOPEDIC_OFFSET = 56
+
+/**
+ * `placeFlags` bit 0 (byte `pp+7`, v5+): this place carries an encyclopedic score. Per-PLACE rather than per-file
+ * because absence is the common case — roughly 89% of the 2026-08-05 gazetteer has no Wikipedia article — and a
+ * file-level flag would force every one of those rows to claim a 0 it never had.
+ */
+export const PLACE_FLAG_HAS_ENCYCLOPEDIC = 1
+
+/**
+ * File magic, "FST\0" as bytes. A reader rejects anything not starting with these four bytes before parsing further.
+ */
+export const FST_MAGIC_BYTES: readonly number[] = [0x46, 0x53, 0x54, 0x00]
+
+/**
+ * Placetypes in hierarchy order, largest first. The index into this array is what gets written into a place entry, so
+ * REORDERING IT BREAKS EVERY EXISTING FILE — append instead, and bump the version.
+ */
+export const PLACETYPE_ORDER: readonly PlacetypeID[] = [
+	"country",
+	"region",
+	"county",
+	"locality",
+	"localadmin",
+	"borough",
+	"neighbourhood",
+	"postalcode",
+	"campus",
+	"dependency",
+	"street_affix",
+]