mailwoman 9.3.0 → 9.4.0

package/README.md

@@ -14,14 +14,15 @@ npx mailwoman parse "1600 Amphitheatre Parkway, Mountain View, CA 94043"
 
 ```ts
 // Library — parse programmatically
-import { createRuntimePipeline, decodeAsJson } from "mailwoman"
+import { decodeAsJSON } from "@mailwoman/core/decoder"
+import { createRuntimePipeline } from "mailwoman"
 import { NeuralAddressClassifier } from "@mailwoman/neural"
 
 const classifier = await NeuralAddressClassifier.loadFromWeights({ locale: "en-US" })
 const parse = createRuntimePipeline({ classifier })
 
 const { tree } = await parse("1600 Amphitheatre Parkway, Mountain View, CA 94043")
-console.log(decodeAsJson(tree))
+console.log(decodeAsJSON(tree))
 // { region: "CA", locality: "Mountain View", street: "Amphitheatre",
 //   house_number: "1600", street_suffix: "Parkway", postcode: "94043" }
 ```
@@ -89,7 +90,8 @@ up normalization, locale detection, kind classification, phrase grouping, and to
 classification with production-ready defaults.
 
 ```ts
-import { createRuntimePipeline, decodeAsJson, decodeAsTuples } from "mailwoman"
+import { decodeAsJSON, decodeAsTuples } from "@mailwoman/core/decoder"
+import { createRuntimePipeline } from "mailwoman"
 import { NeuralAddressClassifier } from "@mailwoman/neural"
 
 const classifier = await NeuralAddressClassifier.loadFromWeights({ locale: "en-US" })
@@ -111,7 +113,7 @@ result.timing // per-stage wall-clock breakdown
 Project the tree into the shape you need:
 
 ```ts
-decodeAsJson(result.tree)
+decodeAsJSON(result.tree)
 // { region: "NY", locality: "New York", street: "5th",
 //   house_number: "350", street_suffix: "Ave", postcode: "10118" }
 

package/lib/api-engine.ts

@@ -40,9 +40,11 @@ import { pathExists, readDirectory, readLocalTextFile } from "@mailwoman/core/fs
 import { tryParsingJSON } from "@mailwoman/core/json"
 import { resolveModulePath } from "@mailwoman/core/module/resolvers"
 import { deriveInputMode } from "@mailwoman/core/pipeline"
+import type { Resolver, ResolveOpts } from "@mailwoman/core/resolver"
+import { mailwomanDataRoot } from "@mailwoman/core/utils"
 import { classifyKindSync } from "@mailwoman/kind-classifier"
 import { computeQueryShape } from "@mailwoman/query-shape"
-import { createWOFResolver, type Resolver, type ResolveOpts } from "@mailwoman/resolver"
+import { createWOFResolver } from "@mailwoman/resolver"
 
 import { readReleaseManifest } from "#data/release"
 import { $public } from "#env"
@@ -53,10 +55,8 @@ import {
 	buildNoGazetteerMessage,
 	createResolverBackend,
 	existingWOFDatabasePaths,
-	mailwomanDataRoot,
 	resolveCandidateDBPath,
 } from "#resolver-backend"
-
 /**
  * Default per-state database root + interp calibration — mirrors the express server's defaults (`GeocodeRouter.ts`).
  */

package/lib/browser-runtime/classify.ts

@@ -0,0 +1,262 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The classify stage of the browser runtime: query shape, kind, the neural pipeline and the tree flatten, with the
+ *   two front-half timings captured, plus the dual-role resolution and the projections a renderer takes. The caller
+ *   owns resolution (`runCascade`, a street tier, an anchor fallback) and the staged progress ticks.
+ */
+
+// STATIC on purpose: a dynamic-import destructure of this barrel gets tree-shaken by webpack's
+// usedExports analysis, which once shipped the WOF cascade as `TypeError: i is not a function`.
+// Static named imports are fully analyzable; do not re-dynamize.
+import { type FlatTreeNode, flattenTreeNodes } from "@mailwoman/core/decoder"
+import type { AddressTree } from "@mailwoman/core/decoder/types"
+import type { ParseResult, ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
+import type { DualRole, MailwomanLookupLike } from "@mailwoman/resolver-wof-wasm/browser-cascade"
+
+import type { FSTMatcherLike, MailwomanClassifierLike } from "#browser-runtime/types"
+
+/**
+ * Project the cascade's hits onto the package's {@link ResolvedPlaceView} — the shape `useParsePipeline` and the result
+ * panels consume. Shared by both demo parse paths so the projection cannot drift.
+ */
+export function projectCascadeHits(
+	hits: ReadonlyArray<{ id: number; name: string; placetype: string; lat: number; lon: number; score: number }>
+): ResolvedPlaceView[] {
+	return hits.map((c) => ({ id: c.id, name: c.name, placetype: c.placetype, lat: c.lat, lon: c.lon, score: c.score }))
+}
+
+/**
+ * Per-parse progress labels, keyed on whether a gazetteer lookup is wired for the selected release.
+ */
+export function parseStageLabelsFor(hasResolver: boolean): string[] {
+	return hasResolver
+		? ["Analyzing input shape…", "Running neural classifier…", "Resolving in gazetteer…"]
+		: ["Analyzing input shape…", "Running neural classifier…"]
+}
+
+//#region Constants
+
+/**
+ * Locale the demo opens on.
+ */
+export const DEFAULT_LOCALE = "en-us"
+
+/**
+ * Address the demo opens on — it exercises house number, street, directional, locality and region in one line.
+ */
+export const DEFAULT_ADDRESS = "1600 Pennsylvania Ave NW, Washington, DC 20500"
+
+/**
+ * Demo preset addresses. Each carries its `country` (ISO code) — the placetype-pair-prior country pin (#1278 phase 2's
+ * `{country}` override): structural routing (locale-check) genuinely can't detect every locale from text shape (NZ's
+ * 4-digit postcode isn't distinctive), so a preset PINS its country and {@link pairCountryForInput} hands it to
+ * `selectPairIndexForText` when the input still equals the preset text. Free-typed input (no exact preset match) falls
+ * back to structural detection — GB-with-postcode auto-fires; NZ free-text stays unfired (the accepted consequence of
+ * structural routing, the #1308-sibling reality).
+ *
+ * See also `PIPELINE_PRESETS` in `@mailwoman/react` (pipeline/presets.ts) — the package carries its own preset list;
+ * reconciling the two lists is tracked outside this file.
+ */
+export const EXAMPLE_ADDRESSES: Array<{ label: string; address: string; country: string }> = [
+	{ label: "White House", address: "1600 Pennsylvania Ave NW, Washington, DC 20500", country: "us" },
+	{ label: "Apple Park", address: "1 Apple Park Way, Cupertino, CA 95014", country: "us" },
+	{ label: "30 Rockefeller Plaza", address: "30 Rockefeller Plaza, New York, NY 10112", country: "us" },
+	{ label: "Pier 39 SF", address: "Pier 39, San Francisco, CA 94133", country: "us" },
+	{ label: "Wrigley Field", address: "1060 W Addison St, Chicago, IL 60613", country: "us" },
+	{ label: "Space Needle", address: "400 Broad St, Seattle, WA 98109", country: "us" },
+	{ label: "ZIP only", address: "90210", country: "us" },
+	{ label: "Berlin (native order)", address: "Straußstraße 27, 12623 Berlin", country: "de" },
+	{ label: "Berlin city-state (int'l order)", address: "5 Hauptstraße, Berlin, Berlin 10115", country: "de" },
+	{ label: "Paris (street fall-through)", address: "181 Rue du Chevaleret, Paris", country: "fr" },
+	// GB dependent_locality (placetype-pair-prior arc) — a verified `gb-golden` board row
+	// (mailwoman/eval-harness/fixtures/gb-golden.jsonl). "Henbury" flips to dependent_locality via the en-gb pair-index
+	// prior; the `country: "gb"` pin selects it even if the user edits away the postcode (and structural detection also
+	// picks gb while the UK postcode is present).
+	{
+		label: "Macclesfield (GB dependent_locality)",
+		address: "41 Hightree Drive, Henbury, Macclesfield, SK11 9PD",
+		country: "gb",
+	},
+	// NZ dependent_locality (en-nz pair-prior arc) — Plimmerton is a suburb (dependent_locality) of Porirua. Postcode
+	// DELIBERATELY OMITTED: a trailing "Porirua 5026" puts the postcode in the parent's comma-field, so segment mode
+	// folds "porirua 5026" and misses the index's bare "porirua" key (the shipped GB artifact misses the same way) —
+	// tracked as #1308. The `country: "nz"` pin is required here: locale-check can't structurally detect NZ (4-digit
+	// postcode isn't a distinctive format), so ONLY the preset pin selects the nz index — free-typed NZ stays unfired.
+	{ label: "Plimmerton (NZ dependent_locality)", address: "35 Steyne Avenue, Plimmerton, Porirua", country: "nz" },
+]
+
+/**
+ * The placetype-pair country PIN for one input (#1278 phase 2's `{country}` override). Returns a preset's `country`
+ * when `input` still exactly equals that preset's text (trimmed), else `undefined` → the caller lets structural
+ * detection decide. This is the stale-pin rule: the pin is tied to the preset's IDENTITY (its text), so the instant the
+ * user edits the input it no longer matches and the parse drops to structural locale-check detection — clean and
+ * stateless (no "active preset" tracking to drift). GB-with-postcode still auto-fires structurally; NZ free-text stays
+ * unfired.
+ */
+export function pairCountryForInput(input: string): string | undefined {
+	const trimmed = input.trim()
+
+	return EXAMPLE_ADDRESSES.find((ex) => ex.address.trim() === trimmed)?.country
+}
+
+//#endregion
+
+//#region Parse orchestration
+
+/**
+ * A source-order parsed node, as {@link flattenTreeNodes} yields it.
+ */
+export type FlatNode = FlatTreeNode
+
+/**
+ * What both demo parse paths need out of the neural classify stage before resolution.
+ */
+export interface ClassifyStageResult {
+	/**
+	 * The decoded solver tree (opaque to the caller beyond `runCascade` / `flattenTreeNodes`).
+	 */
+	tree: AddressTree
+	/**
+	 * Source-order flattened nodes.
+	 */
+	nodes: FlatNode[]
+	/**
+	 * The query-shape kind hypothesis (`postcode_only` / `structured_address` / …).
+	 */
+	kindResult: ParseResult["kindResult"]
+	/**
+	 * Wall-clock timing for the two front-half stages, in ms.
+	 */
+	timing: { shape: number; classify: number }
+}
+
+/**
+ * The neural classify front-half, shared by BOTH demo parse paths (the `/demo` map's `runParseWithBias` and the
+ * MDX-embed `PipelineExplorer`'s `runParse`): the 4-way pipeline import, the query-shape + kind pass, the neural
+ * `runPipeline`, and the tree flatten — with the two front-half timings captured. The caller owns resolution
+ * (`runCascade`, plus the map path's street tier / anchor fallback) and the staged `onStage` progress ticks.
+ *
+ * #1278: this is the single point the locale-check pre-parse plugs into. A future per-parse country / conventions hint
+ * is threaded through {@link ClassifyStageDeps} into the `runPipeline` call HERE — one insertion point for both paths.
+ */
+/**
+ * Per-parse placetype-pair prior selector (placetype-pair-prior arc, #1278), the shape the web loader's
+ * `LoadResult.selectPairIndexForText` exposes. Given the input text it runs locale-check over the text SHAPE (postcode
+ * format / script, never place names) and returns the matching loaded index wrapped as an opaque `placetypePair` opt —
+ * or `undefined` when no loaded index matches (byte-stable no-prior). Typed opaquely here because the docs bundle
+ * carries no neural type dependency; `runClassifyStage` threads the result verbatim into the pipeline's `placetypePair`
+ * opt.
+ */
+export type SelectPairIndex = (text: string, opts?: { country?: string }) => object | undefined
+
+export interface ClassifyStageDeps {
+	/**
+	 * The loaded neural classifier (must be ready — the caller guards `null`).
+	 */
+	classifier: MailwomanClassifierLike
+	/**
+	 * The optional FST gazetteer prior.
+	 */
+	fst?: FSTMatcherLike | null
+	/**
+	 * The optional street-morphology matcher — the #1315 street-context check's signal source. The check only fires when
+	 * BOTH this and `fst` are wired (core's `streetContextRequirementFor`), matching the node runtime pipeline's default;
+	 * a `null`/omitted matcher parses with the check off, exactly the pre-artifact demo behavior.
+	 */
+	streetMorphology?: FSTMatcherLike | null
+	/**
+	 * The per-parse placetype-pair prior selector (#1278) — the loaded {@link SelectPairIndex}, or `null`/omitted when no
+	 * pair index was staged for this release. When present, `runClassifyStage` calls it on the input and passes the
+	 * result as the pipeline's `placetypePair` opt; the GB/NZ dependent_locality prior fires while US/FR inputs stay
+	 * byte-stable.
+	 */
+	selectPairIndex?: SelectPairIndex | null
+}
+
+export interface ClassifyStageHooks {
+	/**
+	 * Fired after the (synchronous) query-shape + kind pass, immediately before the neural pipeline runs. Drives the
+	 * staged progress UI's "Running neural classifier…" transition. Both callers wire it to their `onStage(1)`.
+	 */
+	onClassifierStart?: () => void
+}
+
+/**
+ * Run the shared classify front-half. See {@link ClassifyStageResult} / {@link ClassifyStageDeps}.
+ */
+export async function runClassifyStage(
+	input: string,
+	deps: ClassifyStageDeps,
+	hooks: ClassifyStageHooks = {}
+): Promise<ClassifyStageResult> {
+	const [{ computeQueryShape }, { classifyKindSync }, { runPipeline }, { groupPhrases }] = await Promise.all([
+		import("@mailwoman/query-shape"),
+		import("@mailwoman/kind-classifier"),
+		import("@mailwoman/core/pipeline"),
+		import("@mailwoman/phrase-grouper"),
+	])
+
+	const tStart = performance.now()
+	const queryShape = computeQueryShape(input)
+	const kindResult = classifyKindSync({ raw: input, normalized: input }, queryShape)
+	const tShape = performance.now()
+
+	hooks.onClassifierStart?.()
+
+	// Placetype-pair prior (#1278): pick the per-parse index. A preset PINS its country (pairCountryForInput) — the
+	// phase-2 `{country}` override — so a locale structural routing can't detect from text (NZ: 4-digit postcode isn't
+	// distinctive) still fires while the input equals the preset text; the moment the user edits, the pin drops and we
+	// fall back to structural locale-check detection (GB-with-postcode auto-fires; NZ free-text stays unfired, the
+	// accepted #1308-sibling consequence of structural routing). No index / no match → undefined → byte-stable.
+	const pinnedCountry = pairCountryForInput(input)
+	const placetypePair = deps.selectPairIndex?.(input, pinnedCountry ? { country: pinnedCountry } : undefined)
+
+	const { tree } = await runPipeline(
+		input,
+		{
+			computeQueryShape,
+			groupPhrases,
+			classifier: deps.classifier as Parameters<typeof runPipeline>[1]["classifier"],
+			fst: (deps.fst ?? undefined) as Parameters<typeof runPipeline>[1]["fst"],
+			streetMorphology: (deps.streetMorphology ?? undefined) as Parameters<typeof runPipeline>[1]["streetMorphology"],
+		},
+		// Decision A endpoint default: the demo search box is a human typing fragments — the
+		// fragmented register, so the evidence-bundle channels feed (once a bundle model ships).
+		{ inputMode: "fragmented", ...(placetypePair !== undefined ? { placetypePair } : {}) }
+	)
+
+	const tClassify = performance.now()
+
+	return {
+		tree,
+		nodes: flattenTreeNodes(tree),
+		kindResult: kindResult as ParseResult["kindResult"],
+		timing: { shape: tShape - tStart, classify: tClassify - tShape },
+	}
+}
+
+/**
+ * Dual-role (#402) resolution, shared by both parse paths: whether the resolved pin doubles as another admin tier.
+ * Best-effort + optional — a placeless pin (`id === 0`, e.g. the map path's anchor/street synthesized hits), a lookup
+ * with no `coincidentRolesFor`, an empty relation, or a failed query all resolve to `undefined` (no dual-role badge).
+ */
+export async function resolveDualRoles(
+	lookup: MailwomanLookupLike,
+	primaryHit: { id: number } | undefined
+): Promise<DualRole[] | undefined> {
+	if (!primaryHit || !primaryHit.id || !lookup.coincidentRolesFor) return undefined
+
+	try {
+		const roles = await lookup.coincidentRolesFor(primaryHit.id)
+
+		return roles.length ? roles : undefined
+	} catch {
+		// relation absent / query failed → no dual-role badge
+		return undefined
+	}
+}
+
+//#endregion

package/lib/browser-runtime/fetch.ts

@@ -0,0 +1,89 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The fetch the browser runtime loads its artifacts through. The data origin resets a long download now and then
+ *   (measured: 1 of 18 cold loads lost the 38 MB model to `net::ERR_CONNECTION_RESET` 4.9 s in, and 2 of 16 loads
+ *   failed under a two-attempt retry that covered the connection alone), and a reset that far in rejects the BODY
+ *   read, not the `fetch()` call. So the body is buffered here, inside the retry, and the loader receives a response
+ *   whose bytes are already complete. An HTTP status is never retried: a 404 is an answer, and the loaders decide what
+ *   an absent artifact means.
+ */
+
+/**
+ * The number of attempts a network failure gets, the first included.
+ */
+const ATTEMPTS = 3
+
+/**
+ * The pause before the second attempt; each later attempt doubles it.
+ */
+const FIRST_RETRY_DELAY_MS = 500
+
+/**
+ * `fetch` rejects with a `TypeError` for a network failure (a reset, a refused connection, a CORS refusal) and never
+ * for an HTTP status; a body read that loses its connection rejects the same way. Anything else (an abort, a bad URL)
+ * is not retried.
+ */
+function isNetworkFailure(error: unknown): boolean {
+	return error instanceof TypeError
+}
+
+/**
+ * One attempt: the request, and for a successful status the whole body, so a connection lost mid-download is this
+ * attempt's failure and not the caller's.
+ */
+async function fetchComplete(
+	input: Parameters<typeof fetch>[0],
+	init?: Parameters<typeof fetch>[1]
+): Promise<Response> {
+	const response = await fetch(input, init)
+
+	if (!response.ok || !response.body) return response
+
+	return new Response(await response.arrayBuffer(), {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers,
+	})
+}
+
+function pause(ms: number, signal: AbortSignal | null | undefined): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort)
+			resolve()
+		}, ms)
+
+		function onAbort(): void {
+			clearTimeout(timer)
+			reject(signal?.reason instanceof Error ? signal.reason : new DOMException("aborted", "AbortError"))
+		}
+
+		signal?.addEventListener("abort", onAbort, { once: true })
+	})
+}
+
+/**
+ * `fetch` with the body already read, retried on a network failure. Same signature, so a loader takes it as its
+ * `fetchImpl`; the response it answers with can be read as bytes, text or JSON exactly as a live one.
+ */
+export async function fetchWithRetry(
+	input: Parameters<typeof fetch>[0],
+	init?: Parameters<typeof fetch>[1]
+): Promise<Response> {
+	let attempt = 1
+
+	for (;;) {
+		try {
+			return await fetchComplete(input, init)
+		} catch (error) {
+			if (attempt >= ATTEMPTS || !isNetworkFailure(error) || init?.signal?.aborted) throw error
+
+			await pause(FIRST_RETRY_DELAY_MS * 2 ** (attempt - 1), init?.signal)
+
+			attempt++
+		}
+	}
+}

package/lib/browser-runtime/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The browser runtime: what a host needs to load one published release into a working geocoder in a browser, from
+ *   the public data origin. The Node counterpart is `createRuntimePipeline`; this composes the same packages for the
+ *   client, and it is the one module here that a bundler must be able to build under the `browser` condition.
+ */
+
+export { loadReleaseAssets } from "#browser-runtime/load-assets"
+export { fetchReleasesManifest } from "#browser-runtime/manifest"

package/lib/browser-runtime/load-assets.ts

@@ -0,0 +1,218 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The per-release asset loader: the classifier, the calibration table, the FST gazetteer and street-morphology
+ *   matchers, the pair indexes, and the byte-range gazetteer lookup for one published release, reporting staged
+ *   progress through {@link AssetLoadProgress}. The host owns the terminal ready/error state and reveals the returned
+ *   bundle atomically. The onnxruntime-web and sql.js-httpvfs imports stay dynamic so a host that never loads a
+ *   release never pays for them.
+ */
+
+import type { CalibrationTable, Calibrator } from "@mailwoman/core/decoder/calibration"
+import { createCalibrator } from "@mailwoman/core/decoder/calibration"
+import type { MailwomanLookupLike } from "@mailwoman/resolver-wof-wasm/browser-cascade"
+
+import type { SelectPairIndex } from "#browser-runtime/classify"
+import { DEFAULT_LOCALE } from "#browser-runtime/classify"
+import { fetchWithRetry } from "#browser-runtime/fetch"
+import type { ReleaseInfo } from "#browser-runtime/manifest"
+import {
+	adminGazetteerURL,
+	assetURL,
+	loadFSTGazetteer,
+	loadStreetMorphologyFST,
+	neuralClassifierLoadURLs,
+	PAIR_INDEX_VERSION,
+	pairIndexBaseURL,
+	pairIndexURLs,
+} from "#browser-runtime/resources"
+import type {
+	AssetLoadProgress,
+	FSTMatcherLike,
+	FSTProvenanceLike,
+	MailwomanClassifierLike,
+} from "#browser-runtime/types"
+
+/**
+ * What one release loads to: every field a host may read. A host that resolves admin-only ignores `anchorLookup`, and
+ * loading it is free because the anchor binaries are already fetched by the classifier load for an anchor-trained
+ * bundle.
+ */
+export interface ReleaseAssets {
+	classifier: MailwomanClassifierLike
+	/**
+	 * Postcode-anchor centroid lookup (US ZIP → real centroid), for the postcode-only dead-end fallback.
+	 */
+	anchorLookup: Map<string, { lat: number; lon: number }> | null
+	fstMatcher: FSTMatcherLike | null
+	fstProvenance: FSTProvenanceLike | null
+	/**
+	 * The street-morphology matcher — the #1315 street-context check's signal source, the node/browser parity fix (SCOPE
+	 * invariant 2: node runtimes wire this by default; the browser previously never could). Loaded with the FST gazetteer
+	 * because the check needs BOTH (core's `streetContextRequirementFor` only fires when the two stages are present).
+	 * `null` when the release ships no `fst-street-morphology.bin` (pre-artifact bundles) — the demo then parses without
+	 * the check, byte-identical to before.
+	 */
+	streetMorphologyMatcher: FSTMatcherLike | null
+	/**
+	 * The byte-range gazetteer lookup. `null` when the release ships no gazetteer, when the host asked for none, or when
+	 * the load failed.
+	 */
+	lookup: MailwomanLookupLike | null
+	calibrator: Calibrator | null
+	/**
+	 * Per-parse placetype-pair prior selection (placetype-pair-prior arc, #1278). Runs locale-check over the input text
+	 * and returns the loaded index whose header country matches (or `undefined` → byte-stable no-prior). Both demo parse
+	 * paths thread this into `runClassifyStage` so a GB/NZ input gets its dependent_locality-resurrecting prior. `null`
+	 * when no pair index was staged/loaded for this release (older bundles) — the loader then behaves exactly as before.
+	 */
+	selectPairIndex: SelectPairIndex | null
+}
+
+export interface LoadReleaseAssetsOptions {
+	/**
+	 * Load the byte-range gazetteer lookup, given the same-origin base for the sql.js-httpvfs worker and wasm (for
+	 * example `/mailwoman/sqljs`). Omit it and `lookup` is `null` without a gazetteer step.
+	 */
+	gazetteer?: { sqljsBaseURL: string }
+}
+
+/**
+ * Load the classifier, calibration, FST and gazetteer bundle for one release. Reports staged progress through
+ * `progress`; the host owns the terminal ready/error state and reveals the returned bundle atomically.
+ *
+ * @param release The selected release descriptor (drives which optional assets are fetched).
+ * @param progress The host's progress and abort surface.
+ * @param options Which optional assets the host wants beyond the release's own.
+ */
+export async function loadReleaseAssets(
+	release: ReleaseInfo,
+	progress: AssetLoadProgress,
+	options: LoadReleaseAssetsOptions = {}
+): Promise<ReleaseAssets> {
+	const gazetteer = release.hasWOFDB ? options.gazetteer : undefined
+
+	progress.setProgress(`Loading ${release.version} model (~${release.modelSize ?? "?"})…`)
+
+	// Build staged step labels based on what this release includes.
+	const steps: string[] = ["Loading classifier"]
+
+	if (release.hasFST) {
+		steps.push("Loading FST gazetteer")
+	}
+
+	if (gazetteer) {
+		steps.push("Loading WOF database")
+	}
+
+	progress.setStepLabels(steps)
+
+	// The pair indexes live on the public bucket beside every other model asset, under a dated generation: the objects
+	// ship an immutable Cache-Control, so a rebuilt index is readable only from a fresh path.
+	const pairIndexBase = pairIndexBaseURL(PAIR_INDEX_VERSION)
+
+	// Dynamic so the onnxruntime-web chunk loads only when a release does. The result is narrowed to the structural
+	// classifier contract this module exposes, so the neural package's own classifier type never enters a host bundle.
+	const { loadNeuralClassifierFromURLs } = await import("@mailwoman/neural/web-loader")
+
+	const { classifier, diagnostics, postcodeAnchorLookup, selectPairIndexForText } = (await loadNeuralClassifierFromURLs(
+		{
+			...neuralClassifierLoadURLs(DEFAULT_LOCALE, release.version, {
+				hasAnchor: release.hasAnchor,
+				forceWASM: progress.forceWASM,
+			}),
+			fetchImpl: fetchWithRetry,
+			// Every published pair index is loaded; the loader keeps each live and `selectPairIndexForText` picks per
+			// parse. Fetched tolerantly: a 404 is skipped, so a missing binary means no prior, never a failed load.
+			pairIndexURLs: pairIndexURLs(pairIndexBase),
+		}
+	)) as {
+		classifier: MailwomanClassifierLike
+		diagnostics?: { backend: string; modelBytes: number } | null
+		postcodeAnchorLookup?: Map<string, { lat: number; lon: number }> | null
+		selectPairIndexForText?: SelectPairIndex | null
+	}
+
+	progress.setBackend(
+		diagnostics ? `${diagnostics.backend} (${(diagnostics.modelBytes / 1024 / 1024).toFixed(0)} MB int8)` : "unknown"
+	)
+
+	progress.setStepIndex(0)
+
+	// The calibration table is the model's own held-out reliability, so it must match the loaded version. A release
+	// without one leaves `calibrator` null and the host shows raw softmax scores.
+	let calibrator: Calibrator | null = null
+
+	try {
+		const calRes = await fetchWithRetry(assetURL(DEFAULT_LOCALE, release.version, "calibration.json"))
+
+		if (calRes.ok) {
+			calibrator = createCalibrator((await calRes.json()) as CalibrationTable)
+		}
+	} catch {
+		// No calibration table for this version — raw scores it is.
+	}
+
+	let fstMatcher: FSTMatcherLike | null = null
+	let fstProvenance: FSTProvenanceLike | null = null
+	let streetMorphologyMatcher: FSTMatcherLike | null = null
+
+	if (release.hasFST) {
+		try {
+			const fstResult = await loadFSTGazetteer(DEFAULT_LOCALE, release.version)
+			fstMatcher = fstResult.matcher
+			fstProvenance = fstResult.provenance ?? null
+		} catch {
+			// FST not available for this version.
+		}
+
+		// The street-context check needs both matchers, so the morphology matcher is loaded only once the gazetteer FST
+		// is; a release that predates the artifact answers null and the parse runs with the check off.
+		if (fstMatcher) {
+			try {
+				streetMorphologyMatcher = await loadStreetMorphologyFST(DEFAULT_LOCALE, release.version)
+			} catch {
+				// Corrupt/unfetchable artifact — treat as absent (check off).
+			}
+		}
+	}
+
+	progress.setStepIndex(1)
+
+	let lookup: MailwomanLookupLike | null = null
+
+	if (gazetteer) {
+		try {
+			const { loadHTTPVFSDatabase, WOFCandidateTableLookup } =
+				await import("@mailwoman/resolver-wof-wasm/httpvfs/resolver")
+
+			const worker = await loadHTTPVFSDatabase(adminGazetteerURL(), gazetteer.sqljsBaseURL)
+
+			if (!progress.signal.aborted) {
+				const wofLookup = new WOFCandidateTableLookup(worker)
+				// Fire-and-forget: pull the schema/FTS/dual-role pages through the VFS now so the first interactive query
+				// starts warm. The worker serializes execs, so a user query issued mid-warm-up simply queues behind pages
+				// it was going to need anyway.
+				void wofLookup.warmUp().catch(() => {})
+				lookup = wofLookup
+			}
+		} catch {
+			// WOF DB not available for this version.
+		}
+	}
+
+	progress.setStepIndex(2)
+
+	return {
+		classifier,
+		anchorLookup: postcodeAnchorLookup ?? null,
+		fstMatcher,
+		fstProvenance,
+		streetMorphologyMatcher,
+		lookup,
+		calibrator,
+		selectPairIndex: selectPairIndexForText ?? null,
+	}
+}