mailwoman 10.2.2 → 10.4.0

package/README.md

@@ -31,7 +31,7 @@ console.log(decodeAsJSON(tree))
 
 Mailwoman is **not** an LLM and none of it is generative. It is a small
 transformer encoder (~30M params) doing BIO token classification over a 33-label
-address schema — boring NER, which is a feature for short, structured strings.
+address schema. That plain NER design suits short, structured strings.
 
 The design splits the problem in two:
 
@@ -121,7 +121,7 @@ decodeAsTuples(result.tree)
 // [["house_number", "350"], ["street", "5th"], …]
 ```
 
-The tree is hierarchical and carries calibrated confidence per node:
+The tree is hierarchical and records a calibrated confidence on each node:
 
 ```ts
 for (const root of result.tree.roots) {
@@ -136,7 +136,7 @@ right about 88% of the time) rather than raw scores.
 
 ### Options
 
-Factory options configure the pipeline; per-call `PipelineOpts` tune a single parse. The
+Factory options configure the pipeline, and per-call `PipelineOpts` tune a single parse. The
 ones you'll reach for most:
 
 ```ts
@@ -169,7 +169,7 @@ mailwoman geocode "1600 Amphitheatre Pkwy, Mountain View, CA 94043"
 Programmatically, build a `WOFSQLitePlaceLookup` backend (from
 `@mailwoman/resolver-wof-sqlite`), pass it to `createWOFResolver` (from `@mailwoman/resolver`),
 and hand the resolver to `createRuntimePipeline({ classifier, resolver })`. The resolved
-`result.tree` roots then carry a `wof:id` and coordinate. See
+`result.tree` roots then have a `wof:id` and coordinate. See
 [Getting started → Adding resolution](https://mailwoman.ai/docs/developers/get-started/install-and-first-parse)
 for the worked example.
 

package/cli/commands/corpus/golden/relabel.tsx

@@ -6,8 +6,8 @@
  *   `mailwoman corpus golden-relabel` — move a golden answer-key version onto the corpus's US
  *   street-suffix convention (folded `street` → `street` + `street_suffix`). Writes a new version
  *   dir plus a review deck. the parent version is read-only. See
- *   `corpus/src/tools/golden-relabel-street.ts` for what it changes and, more importantly, what it
- *   refuses to.
+ *   `corpus/src/tools/golden-relabel-street.ts` for what it changes and what it
+ *   refuses to change.
  */
 
 import { type CommandSpec, CommandTaskResult, type CommandComponent, useCommandTask } from "#cli-kit"

package/cli/commands/corpus/migrate/overlays.tsx

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   `mailwoman corpus migrate-overlays` — rewrite every overlay parquet of a corpus onto the current row
- *   schema, where an overlay slice is one the corpus manifest lists and its base manifest does not, compared
+ *   schema, where an overlay parquet is a file the corpus manifest lists and its base manifest does not, compared
  *   by `sha256`.
  *
  *   Each migrated file is written beside its original as `<name>.migrated.parquet` and no file is swapped, so the
@@ -40,7 +40,7 @@ const Cmd: CommandComponent<typeof spec> = ({ options }) => {
 
 		type Manifest = Parameters<typeof baseManifestFiles>[0]
 
-		// A slice without a hash could match another unhashed slice.
+		// A manifest file without a hash could match another unhashed file.
 		// The migration could then skip an overlay as a base.
 		const readHashedFiles = async (path: string) => {
 			const files = baseManifestFiles(await readLocalJSONFile<Manifest>(path))

package/cli/commands/corpus/overlay-manifest.tsx

@@ -46,6 +46,11 @@ export const spec = {
 				"Split per parquet, comma-separated. Unset puts every file in train. val or test is accepted only for a file `corpus split-slice` wrote, whose name ends .val.parquet or .test.parquet.",
 		},
 		note: { type: "string", required: true, description: "Manifest note" },
+		"replace-source": {
+			type: "string",
+			description:
+				"Base sources to drop, comma-separated. The base's files with each source leave the manifest and its counts, so the added files take their place.",
+		},
 	},
 } as const satisfies CommandSpec
 
@@ -86,6 +91,7 @@ const Cmd: CommandComponent<typeof spec> = ({ options }) => {
 				split: (splits[index] ?? "train") as "train" | "val" | "test",
 			})),
 			note: options.note,
+			replaceSources: options.replaceSource ? extractDelimited(options.replaceSource) : [],
 		})
 
 		return "done"

package/cli/commands/corpus/split-slice.tsx

@@ -6,7 +6,7 @@
  *   `mailwoman corpus split-slice --input <parquet> --out-dir <dir>` — route one overlay parquet
  *   through the holdout policy the base build applies, writing a parquet per split it reaches.
  *
- *   An overlay is appended to a manifest as a train file, so a country whose only rows of a given
+ *   A corpus overlay is appended to a manifest as a train file, so a country whose only rows of a given
  *   kind live in an overlay has no held-out row of that kind. Pass the per-split outputs to
  *   `mailwoman corpus overlay-manifest --split` so the manifest records where each one belongs.
  */

package/cli/commands/corpus/upload.tsx

@@ -84,7 +84,7 @@ type UploadedCorpusManifest = Partial<
  * `overlay-manifest` rewrites this count on each merge.
  *
  * `total_rows` here counts the same labeled rows as the build manifest's `total_aligned_rows`,
- * so the two are comparable and their difference is what the overlays added.
+ * so the two are comparable and their difference is what the corpus overlays added.
  */
 interface AssembledCorpusManifest {
 	total_rows?: number

package/cli/commands/data/bom.tsx

@@ -39,7 +39,7 @@ export const spec = {
 			type: "boolean",
 			default: false,
 			description:
-				"Leave out the data root's manifested databases. The document then carries the four bundles alone, " +
+				"Leave out the data root's manifested databases. The document then lists only the four bundles, " +
 				"and no component records attribution, source vintage or build revision",
 		},
 	},

package/cli/commands/data/inventory.tsx

@@ -25,7 +25,7 @@ import {
 
 export const description =
 	"Report every database in the data root and whether it records how it was built. `layer_manifest` is " +
-	"the interface (docs/engineering/reference/layer-interface.mdx); this says how much of the root implements it."
+	"the interface (docs/engineering/reference/layer-interface.mdx). This report shows how much of the root implements it."
 
 /**
  * Native command-line interface consumed by the filesystem command router.
@@ -36,14 +36,14 @@ export const spec = {
 	options: {
 		"data-root": { type: "string", description: "Override the data root" },
 		depth: { type: "string", description: "Directory levels to walk. Default 2" },
-		all: { type: "boolean", default: false, description: "List every artifact; the default shows only the summary" },
+		all: { type: "boolean", default: false, description: "List every artifact. The default shows only the summary" },
 		json: { type: "boolean", default: false, description: "Emit the report as JSON" },
 	},
 } as const satisfies CommandSpec
 
 /**
- * The rollup is the actionable view: one builder's identical defect across many artifacts
- * reads as one problem per directory rather than one problem per file.
+ * The rollup is the actionable view: one builder's identical defect across several
+ * artifacts reads as one problem per directory rather than one problem per file.
  */
 function rollup(entries: readonly InventoryEntry[]): string[] {
 	const by = new Map<string, { total: number; manifested: number; bytes: number }>()

package/cli/commands/data/pull.tsx

@@ -76,7 +76,7 @@ export const spec = {
 		"dry-run": {
 			type: "boolean",
 			default: false,
-			description: "Print the download plan; touch no network and write no data",
+			description: "Print the download plan without network access or data writes",
 		},
 		only: {
 			type: "string",
@@ -102,8 +102,8 @@ export const spec = {
 			multiple: true,
 			choices: OBLIGATION_REFUSALS,
 			description:
-				`Decline a bundle whose recorded expression carries this class of obligation (${OBLIGATION_REFUSALS.join(", ")}); ` +
-				"repeatable. Default: $MAILWOMAN_REFUSE_OBLIGATIONS",
+				`Decline a bundle whose recorded expression has this class of obligation (${OBLIGATION_REFUSALS.join(", ")}). ` +
+				"Repeatable. Default: $MAILWOMAN_REFUSE_OBLIGATIONS",
 		},
 	},
 } as const satisfies CommandSpec

package/cli/commands/eval/oracle-k.tsx

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   `mailwoman eval oracle-k`: oracle-recall@k over segment-level k-best decodes (stage-2
- *   instrumentation). Measures the k-best rerank headroom the top-1 checks can't see: how often the
+ *   instrumentation). Measures the k-best rerank headroom the top-1 checks can't see: the rate at which the
  *   gold value appears anywhere in the top-k whole-segmentation hypotheses decoded from the current
  *   model's emissions. Informational (always exits 0). The standing floors stay on `eval parity`.
  */

package/cli/commands/gazetteer/anchor-lexicon.tsx

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   `mailwoman gazetteer anchor-lexicon`: build the gazetteer-anchor lexicon (knowledge-ladder rung
- *   3.2). One generated artifact, codex as the single source of truth, consumed by both the
+ *   3.2). One generated artifact, built only from codex, consumed by both the
  *   Python trainer (gazetteer_anchor.py) and the TS inference side, so the two matchers cannot
  *   drift (the PLACETYPE_ORDER lesson: dual implementations silently corrupt).
  *
@@ -134,7 +134,7 @@ const GazetteerAnchorLexicon: CommandComponent<typeof spec> = ({ options }) => {
 		for (const map of [entries, codeEntries]) {
 			for (const [key, bits] of map) {
 				if (bits & BIT.country && bits & BIT.region) {
-					// oxlint-disable-next-line oxc/bad-bitwise-operator -- genuine bit-set union rather than a mistyped logical or
+					// oxlint-disable-next-line oxc/bad-bitwise-operator -- an intended bit-set union rather than a mistyped logical or
 					map.set(key, bits | BIT.homograph)
 				}
 			}

package/cli/commands/gazetteer/build/coastal.tsx

@@ -4,8 +4,8 @@
  * @author Teffen Ellis, et al.
  *
  *   `mailwoman gazetteer build coastal` — acquire the Environment Agency's `Mapping (England, 2024)` dataset
- *   for National Coastal Erosion Risk and build the sealed `coastal-england.db` layer. Thin wiring only: catalogue read
- *   → download → build → verify all live in `@mailwoman/coastal/sdk`, so each stays unit-testable without Ink
+ *   for National Coastal Erosion Risk and build the sealed `coastal-england.db` layer. This file only wires steps: the catalogue
+ *   read, download, build and verify steps all live in `@mailwoman/coastal/sdk`, so each stays unit-testable without Ink
  *   or the network in the loop. Mirrors `flood.tsx`'s progress (stderr) / summary (stdout) split.
  *
  *   `--measure-resolutions` does not build. The index resolution is measured for this layer.

package/cli/commands/gazetteer/build/poi/index.tsx

@@ -120,7 +120,7 @@ const GazetteerBuildPOI: CommandComponent<typeof spec> = ({ options }) => {
 			// only on the selected build path, so a top-level import breaks the whole published
 			// CLI on a clean install — the smoke test's clean-install leg is what catches it.
 			// The osm source branch is build-local by design.
-			// It may only resolve its SDK when actually invoked.
+			// It may only resolve its SDK when a run selects it.
 			const { extractOSMPOIs } = await import("@mailwoman/osm/sdk/extract/poi")
 
 			for await (const row of extractOSMPOIs(pbf)) {

package/cli/commands/gazetteer/build/venue-heads.tsx

@@ -49,7 +49,7 @@ const GazetteerBuildVenueHeads: CommandComponent<typeof spec> = ({ options }) =>
 			await ingestPlaceNames({ release: options.release, onPhase: (_, detail) => log(detail ?? "") })
 		}
 
-		// Manifest slice paths start with the training host's `/data` root.
+		// Manifest file paths start with the training host's `/data` root.
 		// This host keeps them under the data root.
 		const dataRoot = dataRootPath().toString()
 

package/cli/commands/gazetteer/census.tsx

@@ -123,7 +123,7 @@ const GazetteerCensus: CommandComponent<typeof spec> = ({ options }) => {
 
 		await writeLocalFile(bytes, outPath)
 
-		// Self-verifying readback over the bytes just written rather than the in-memory nodes.
+		// Self-verifying readback over the bytes this run wrote rather than the in-memory nodes.
 		const resolver = new PlacetypeCensusResolver(bytes)
 		const probeParents = PROBE_PARENTS_BY_COUNTRY[country]
 

package/cli/commands/gazetteer/inspect/graph.tsx

@@ -6,7 +6,7 @@
  *   `mailwoman wof graph <localRepoDir> <placetype>` — emit a node-link graph of the WOF placetype
  *   hierarchy rooted at the given placetype.
  *
- *   Use this instead of `wof tree` when the root has many shared descendants, because the graph shape
+ *   Use this instead of `wof tree` when the root has shared descendants, because the graph shape
  *   stays compact regardless of DAG topology — each node and edge appears exactly once. The output
  *   follows the d3-force / react-flow convention (`nodes`, `links` with `source`/`target`) so it drops
  *   into common html graph viewers without translation.

package/cli/commands/gazetteer/inspect/mermaid.tsx

@@ -3,10 +3,11 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `mailwoman wof mermaid <localRepoDir> <placetype>` — render a Mermaid flowchart of the WOF
- *   placetype hierarchy rooted at the given placetype.
+ *   `mailwoman gazetteer inspect mermaid <localRepoDir> <placetype>` renders a Mermaid flowchart of
+ *   the WOF placetype hierarchy rooted at the given placetype.
  *
- *   Reads from the local `whosonfirst-placetypes` clone that `mailwoman wof sync` produces.
+ *   It reads `<localRepoDir>/whosonfirst/whosonfirst-placetypes`, the clone that
+ *   `mailwoman gazetteer inspect sync` produces.
  */
 
 import { Spinner } from "@inkjs/ui"
@@ -102,7 +103,7 @@ const WOFMermaid: CommandComponent<typeof spec, [string, string]> = ({ args, opt
 
 		if (!placetype) {
 			throw new CommandError(
-				`No placetype named '${placetypeName}' found. Ensure '${localRepoDirectory.toString()}' contains a clone of whosonfirst/whosonfirst-placetypes (run \`mailwoman wof sync\` first).`
+				`No placetype named '${placetypeName}' found. Ensure '${localRepoDirectory.toString()}' contains a whosonfirst/whosonfirst-placetypes clone (run \`mailwoman gazetteer inspect sync\` first).`
 			)
 		}
 

package/cli/commands/gazetteer/inspect/sync/index.tsx

@@ -52,7 +52,7 @@ import {
 const CONCURRENCY = 8
 
 /**
- * Above this many repositories the final list is summarized instead of printed in full.
+ * Above this repository count the final list is summarized instead of printed in full.
  *
  * The `▸` lines above it are complete either way.
  * This bounds the closing frame rather than the record.

package/cli/commands/gazetteer/overture-ingest.tsx

@@ -16,10 +16,7 @@ import {
 	splitCountryCodes,
 	useCommandTask,
 } from "#cli-kit"
-
-// Overture prunes old releases from its bucket, so a stale pin makes the default ingest fail.
-// Keep this pin in step with `DEFAULT_RELEASE` in `gazetteer-pipeline/poi/defaults.ts`.
-const DEFAULT_RELEASE = "2026-07-22.0"
+import { DEFAULT_RELEASE } from "#gazetteer/poi/defaults"
 
 const S3_GLOB = (release: string) =>
 	`s3://overturemaps-us-west-2/release/${release}/theme=addresses/type=address/*.parquet`

package/cli/commands/gazetteer/postcode/intl.tsx

@@ -205,8 +205,8 @@ async function buildDatabase(
 	}
 
 	using kdb = new DatabaseClient<WOFDatabase>(outPath)
-	// Regenerated artifact: drop any prior table so a re-run with a different country set
-	// fully replaces it and synthetic ids restart cleanly without colliding with stale rows.
+	// Regenerated artifact: drop any prior table so a re-run with a different country set fully
+	// replaces it and synthetic ids restart from the first id without colliding with stale rows.
 	await kdb.schema.dropTable("spr").ifExists().execute()
 
 	// Schema mirrors postalcode-intl.db's `spr` exactly, as a drop-in `--postcodes` input for build-candidate.

package/cli/commands/poi.tsx

@@ -133,7 +133,7 @@ async function formatOverpassBlock(intent: POIIntent): Promise<string> {
 	if (intent.subject.kind === "category") {
 		const { getPOICategory } = await import("@mailwoman/poi-taxonomy")
 		const { categoryIDs } = intent.subject
-		// Every member needs a tag rather than just one: a union emitted from the subset that
+		// Every member needs a tag rather than only one: a union emitted from the subset that
 		// happens to include `osmTag` is a narrower query than the one the POI branch ran.
 		// The printed result would hide that difference.
 		const untagged = categoryIDs.filter((id) => !getPOICategory(id)?.osmTag)

package/cli/commands/registry/run.tsx

@@ -290,8 +290,8 @@ interface MultiSourceSpec {
 	 */
 	role?: "eligibility" | "funding"
 	/**
-	 * Read at most this many rows (the head of the file), so a huge source can
-	 * be sampled without pre-filtering.
+	 * Read at most this number of rows (the head of the file), so a huge source
+	 * can be sampled without pre-filtering.
 	 */
 	limit?: number
 }

package/cli/commands/serve.tsx

@@ -54,8 +54,8 @@ const ClusterManager: ParsedCommandComponent<ServerConfig> = ({ options: { cpus
 		setWorkers(Array.from({ length: cpus }, () => cluster.fork()))
 
 		// Tracks whether any worker has ever reached "listening" — distinguishes a
-		// genuine boot failure (every worker died before one of them opened the port)
-		// from an ordinary shutdown after a healthy run.
+		// boot failure (every worker died before one of them opened the port) from
+		// an ordinary shutdown after a healthy run.
 		// `cluster.on("listening", …)` mirrors the per-worker wiring in WorkerStatus,
 		// but at the primary, where the exit handler below can see it.
 		let anyListened = false
@@ -85,8 +85,8 @@ const ClusterManager: ParsedCommandComponent<ServerConfig> = ({ options: { cpus
 
 		// Graceful shutdown: a term/INT delivered to the primary pid (docker stop, systemctl stop)
 		// never reaches worker JS handlers — Node's cluster teardown bypasses them.
-		// Forward the signal explicitly so each worker's serveNode drain actually runs,
-		// then exit once they're gone (bounded — a hung worker must not wedge the shutdown).
+		// Forward the signal explicitly so each worker's serveNode drain runs, then exit
+		// once they're gone (bounded — a hung worker must not wedge the shutdown).
 		const forward = (signal: NodeJS.Signals) => {
 			const alive = Object.values(cluster.workers ?? {}).filter(isPresent)
 
@@ -224,7 +224,7 @@ const ChildThread: ParsedCommandComponent<ServerConfig> = ({ options: { port, ho
 				// The rest exit silently.
 				// Chosen over a primary-side pre-fork check
 				// (the primary doesn't otherwise call createServeEngine() at all. An import
-				// and database-existence check there just to avoid forking would change more code)
+				// and database-existence check there only to avoid forking would change more code)
 				// and over routing the message back through the primary's cluster "exit" handler
 				// (would require an IPC round-trip for what's a one-line dedupe).
 				if (cluster.worker?.id === 1) {

package/cli/commands/situs/build.tsx

@@ -76,7 +76,7 @@ export const spec = {
  *
  * NH + HI have zero Overture address coverage in this release, so they're absent —
  * interpolation-only states.
- * VI (territory) included for completeness.
+ * VI (territory) is also included.
  * Harmless if the parser's region→slug map skips it.
  */
 const STATES_BY_COVERAGE = [

package/cli/commands/tiger/fetch.tsx

@@ -8,7 +8,7 @@
  *   SpatiaLite).
  *
  *   A valid cached ZIP is reused. Re-running a state replaces its rows. Pass
- *   `--county <FIPS3>` to load just one county (handy for downstream per-county work).
+ *   `--county <FIPS3>` to load one county (handy for downstream per-county work).
  */
 
 import { Spinner } from "@inkjs/ui"

package/cli/debug-view/DebugFrame.tsx

@@ -112,7 +112,7 @@ export function mapPaneCellSize(columns: number, rows: number): { columns: numbe
 }
 
 /**
- * How many output lines are visible at once, exported so a caller clamping its scroll
+ * The number of output lines visible at once, exported so a caller clamping its scroll
  * offset uses the pane's own arithmetic rather than a second copy.
  */
 export function outputPaneCapacity(rows: number): number {

package/cli/debug-view/output-lines.ts

@@ -58,7 +58,7 @@ function formatMsFixed(ms: number): string {
 }
 
 /**
- * Whether the per-span script is worth printing: the tree holds more than one writing system,
+ * Whether to print the per-span script: true when the tree holds more than one writing system,
  * with `Zyyy` excluded because a house number or postcode answers it.
  */
 function scriptsWorthShowing(tree: AddressTree): boolean {

package/cli/debug-view/trace-rows.ts

@@ -12,7 +12,7 @@ import type { GeocodeTrace } from "#geocode/session"
 // #region Shared
 
 /**
- * What a row shows where the datum genuinely does not exist, kept as a single constant
+ * What a row shows where the datum does not exist, kept as a single constant
  * so every kind of absence reads the same.
  */
 export const ABSENT = "—"
@@ -90,8 +90,8 @@ export function tokensRow(trace: GeocodeTrace | null): string {
 }
 
 /**
- * Per channel, how many pieces contributed a nonzero clue and which ones: `not fed` is
- * an unwired source while `0/12` is a wired channel that matched no entry.
+ * Per channel, the count of pieces that contributed a nonzero clue and which ones:
+ * `not fed` is an unwired source while `0/12` is a wired channel that matched no entry.
  */
 export function channelsRow(trace: GeocodeTrace | null): string {
 	if (!trace) return ABSENT
@@ -121,7 +121,7 @@ export function channelsRow(trace: GeocodeTrace | null): string {
 
 /**
  * What the decode did: algorithm, mean per-token confidence, component sequence,
- * priors that actually contributed a nonzero bias and repair passes that changed a label.
+ * priors that contributed a nonzero bias and repair passes that changed a label.
  */
 export function decodeRow(trace: GeocodeTrace | null): string {
 	if (!trace) return ABSENT

package/cli/doctor/checks.ts

@@ -639,7 +639,7 @@ export interface LayerLicenseObservation {
 	/**
 	 * Lists other `.db` files in the layer's directory when the expected file is absent.
 	 *
-	 * These usually come from a build written under a name the session does not attach.
+	 * A listed file can come from a build written under a name the session does not attach.
 	 */
 	alternates: string[] | null
 }

package/cli/doctor/runner.ts

@@ -76,7 +76,7 @@ export interface DoctorDeps {
 	weightsPackageName(locale: string): string
 	dataRoot(): { path: string; fromEnv: boolean }
 	/**
-	 * The candidate.db the tools would actually use, with no convention-path fallback —
+	 * The candidate.db the tools would open, with no convention-path fallback —
 	 * the same precedence geocode and serve apply.
 	 */
 	envCandidatePath(): Promise<string | null>

package/cli/kit/weights-guard.tsx

@@ -10,7 +10,7 @@
  *
  *   Results handed to the render prop:
  *
- *   - `"neural"` — weights resolve (pre-existing, or just downloaded); render the real command.
+ *   - `"neural"` — weights resolve (pre-existing, or downloaded by this guard); render the real command.
  *   - `"declined"` — the user said no, the download failed, or `--degraded` was passed. the caller
  *       renders its degraded (encoder-less) mode.
  *   - `"unavailable"` — weights absent + non-interactive stdin and no flag. the caller keeps its

package/cli/native/commands/autocomplete.ts

@@ -31,7 +31,7 @@ export const spec = {
 			validate: (value) => Number.isInteger(value) && value >= 1 && value <= 100,
 			validationMessage: "--limit must be an integer between 1 and 100.",
 		},
-		fst: { type: "string", hint: "path", description: "FST binary; defaults from $MAILWOMAN_FST_BIN." },
+		fst: { type: "string", hint: "path", description: "FST binary. The default comes from $MAILWOMAN_FST_BIN." },
 		json: {
 			type: "boolean",
 			default: false,

package/cli/native/commands/doctor.ts

@@ -14,7 +14,7 @@ import { booleanValue, type CommandSpec, runNativeCommand } from "#cli/native/sp
 export const spec = {
 	name: "doctor",
 	description:
-		"Check whether this machine can run mailwoman, and what each gap costs you. Runtime first (node, ONNX), then the model weights, then the optional data layers geocoding needs. A missing layer is reported, never fatal, and every failing line carries the one command that closes it. Then the license posture: the branch of mailwoman's license that applies to this installation, and the obligations each attached layer's recorded license carries (attribution, share-alike, source offer).",
+		"Check whether this machine can run mailwoman, and what each gap costs you. Runtime first (node, ONNX), then the model weights, then the optional data layers geocoding needs. A missing layer is reported, never fatal, and every failing line prints the one command that closes it. Then the license posture: the branch of mailwoman's license that applies to this installation, and the obligations each attached layer's recorded license imposes (attribution, share-alike, source offer).",
 	options: {
 		json: {
 			type: "boolean",

package/cli/native/commands/geocode.ts

@@ -9,6 +9,7 @@
 import { type GeocodeResult, VariantAliasExemptionSchema } from "@mailwoman/core/geocode"
 import { prettyJSON, stringifyJSON } from "@mailwoman/core/json"
 import type { PipelineTiming } from "@mailwoman/core/pipeline"
+import { DEFAULT_VENUE_HEAD_BIAS_SCALE } from "@mailwoman/neural/venue/head-prior"
 
 import { resolveEngineStamp } from "#cli/kit/engine-stamp"
 import {
@@ -54,7 +55,7 @@ export const spec = {
 		"default-country": {
 			type: "string",
 			hint: "country",
-			description: "ISO-3166 resolver country scope; pass none to disable it.",
+			description: "ISO-3166 resolver country scope. Pass none to disable it.",
 		},
 		"country-scope": {
 			type: "string",
@@ -102,10 +103,16 @@ export const spec = {
 		},
 		"venue-head-bias-scale": {
 			type: "number",
-			default: 1,
+			default: DEFAULT_VENUE_HEAD_BIAS_SCALE,
 			hint: "multiplier",
 			description: "Multiplier on the venue-head table's biases.",
 		},
+		"street-morphology-prior": {
+			type: "boolean",
+			default: true,
+			description:
+				"Bias a trailing street-type affix toward the street labels when its segment opens with a house number; --no-street-morphology-prior disables it.",
+		},
 		"place-country": {
 			type: "boolean",
 			default: true,
@@ -215,6 +222,7 @@ async function optionsOf(values: Record<string, unknown>): Promise<GeocodeOption
 		gazetteerPrior: booleanValue(values, "gazetteer-prior"),
 		venueHeadPrior: booleanValue(values, "venue-head-prior"),
 		venueHeadBiasScale: numberValue(values, "venue-head-bias-scale")!,
+		streetMorphologyPrior: booleanValue(values, "street-morphology-prior"),
 		placeCountry: booleanValue(values, "place-country"),
 		postcodeCountryCoherence: booleanValue(values, "postcode-country-coherence"),
 		forkEntity: booleanValue(values, "fork-entity"),

package/cli/native/commands/license.ts

@@ -60,7 +60,7 @@ import { readMailwomanManifest } from "#metadata"
 export const spec = {
 	name: "license",
 	description:
-		"Mint, issue, verify, adopt and refresh commercial license keys. `keygen` writes an Ed25519 signing pair under $MAILWOMAN_CONFIG_ROOT/license and prints the public key with its id; `issue` signs a key for a licensee; `verify` checks a token offline against the public keys this build trusts; `register` prints the well-known key file the shipped register derives; `adopt <token> --secret <s>` writes a purchased key to $MAILWOMAN_CONFIG_ROOT/license/key and its refresh secret beside it; `refresh` fetches the current key after a renewal. Without a key the AGPL-3.0-only branch applies — `mailwoman doctor` says which branch applies and why.",
+		"Mint, issue, verify, adopt and refresh commercial license keys. `keygen` writes an Ed25519 signing pair under $MAILWOMAN_CONFIG_ROOT/license and prints the public key with its id. `issue` signs a key for a licensee. `verify` checks a token offline against the public keys this build trusts. `register` prints the well-known key file the shipped register derives. `adopt <token> --secret <s>` writes a purchased key to $MAILWOMAN_CONFIG_ROOT/license/key and its refresh secret beside it. `refresh` fetches the current key after a renewal. Without a key the AGPL-3.0-only branch applies — `mailwoman doctor` reports which branch applies and why.",
 	positionals: [
 		{
 			name: "action",
@@ -79,7 +79,7 @@ export const spec = {
 			type: "string",
 			hint: "secret",
 			description:
-				"adopt: the refresh secret from the purchase page or the first email, stored beside the key; refresh: the secret, when not reading the credentials file.",
+				"adopt: the refresh secret from the purchase page or the first email, stored beside the key. refresh: the secret, when not reading the credentials file.",
 		},
 		licensee: {
 			type: "string",
@@ -257,9 +257,9 @@ function refusalFor(verification: LicenseKeyVerification): string | null {
 /**
  * The `lid` in a token, when the self-service worker issued it.
  *
- * For a token this build cannot verify the payload is read as written:
- * the license's public status is the one thing worth asking about such a token,
- * since it identifies whether the action is an upgrade or a purchase.
+ * For a token this build cannot verify the payload is read as written: the command
+ * asks only for the license's public status for such a token, since it identifies
+ * whether the action is an upgrade or a purchase.
  */
 function licenseIDOf(verification: LicenseKeyVerification, token: string): string | null {
 	const payload = "payload" in verification ? verification.payload : decodeLicenseKeyPayload(token)

package/cli/native/commands/reverse.ts

@@ -36,7 +36,7 @@ export const spec = {
 		"polygons-db": {
 			type: "string",
 			hint: "path",
-			description: "Optional polygon sidecar; without it containment is approximate.",
+			description: "Optional polygon sidecar. Without it, containment is approximate.",
 		},
 		format: {
 			type: "string",

package/lib/ablation/expectation.ts

@@ -137,7 +137,7 @@ export const RUNG_RADIUS_FLOOR_KM: Readonly<Record<string, number>> = {
 export const COINCIDENT_PLACE_KM = 10
 
 /**
- * Decisive log10 population margin for names.
+ * The log10 population margin by which a name's top candidate must lead the runner-up.
  */
 export const DECISIVE_MARGIN_LOG10 = 0.5
 
@@ -317,7 +317,7 @@ export function dominanceMarginLog10(places: readonly AblationPlace[]): number {
 }
 
 /**
- * True if top candidate is decisive.
+ * True if the top candidate leads the runner-up by at least the log10 population margin.
  */
 export function isDecisive(places: readonly AblationPlace[]): boolean {
 	return places.length > 0 && dominanceMarginLog10(places) >= DECISIVE_MARGIN_LOG10
@@ -821,8 +821,8 @@ export function collapseCoincident(places: readonly AblationPlace[]): AblationPl
 /**
  * Coarseness rank: higher is more precise.
  *
- * The tier ladder is `address_point → interpolated → street → admin`, and a deletion that
- * walks down it has cost the user precision even when the coordinate barely moved.
+ * The tier ladder is `address_point → interpolated → street → postcode → admin`, and a deletion
+ * that walks down it has cost the user precision even when the coordinate barely moved.
  */
 export function tierRank(tier: ResolutionTier): number {
 	switch (tier) {
@@ -830,10 +830,12 @@ export function tierRank(tier: ResolutionTier): number {
 		case "venue":
 		case "address_point":
 		case "plus_code":
-			return 4
+			return 5
 		case "interpolated":
-			return 3
+			return 4
 		case "street":
+			return 3
+		case "postcode":
 			return 2
 		case "admin":
 			return 1

package/lib/admin-coherence.ts

@@ -211,7 +211,8 @@ export interface AdminCoherenceTreeNode extends AdminCoherenceSourceNode {
 /**
  * Builds the `admin_coherence` field for a forked-entity answer.
  *
- * The entity has a country but no ancestry, so a parsed region is usually `unverifiable`.
+ * The entity has a country but no ancestry, so a parsed region has no ancestor to match
+ * and can come back `unverifiable`.
  */
 export function forkedEntityCoherenceField(
 	roots: readonly AdminCoherenceTreeNode[],