@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

package/lib/weights-overlay-linker.ts

@@ -2,12 +2,9 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * Shared development tooling for weights overlays: the symlink primitives every overlay linker uses, the
- * placetype-pair index build, and the manifest form ({@link materializeDevOverlay}) each locale's
- * `scripts/link-dev-weights.ts` declares itself in.
  */
 
-import { dataRootPath } from "@mailwoman/core/data-root"
+import { dataRootPath, weightsOverlayPath } from "@mailwoman/core/data-root"
 import {
 	pathExists,
 	readLocalJSONFile,
@@ -25,22 +22,22 @@ import {
 } from "@mailwoman/core/fs/writers"
 import { md5File } from "@mailwoman/core/hash"
 import { parseJSONStrict } from "@mailwoman/core/json"
-import { repoRootPath, workspacePath } from "@mailwoman/core/paths"
+import { repoRootPath, repoRootPathBuilder, workspacePathBuilder } from "@mailwoman/core/paths"
 import { spawnProcessSync } from "@mailwoman/core/process"
 import { readReleaseConfig, repoCommittedSoftFeedSources } from "@mailwoman/core/release-config"
-import { weightsOverlayPath } from "@mailwoman/core/utils"
-import { resolvePath } from "path-ts"
+import type { PathBuilder, PathBuilderLike } from "path-ts"
 
 import { $public } from "#env"
 import { fstFreshnessWarning } from "#fst/freshness"
+import { wofDatabasePath } from "#paths"
 
 /**
- * Replicate `ln -sf SRC DEST` ATOMICALLY: symlink under a temp name, then rename over the destination. A plain
- * unlink-then-symlink leaves a no-file window that concurrent vitest workers can hit mid-suite — bit CI on 2026-07-24.
- * rename(2) replaces the destination atomically.
+ * Replaces `dest` with a symlink to `src` by renaming a temporary link over it.
+ *
+ * The rename is atomic, so concurrent test workers never see `dest` missing.
  */
-export async function linkForce(src: string, dest: string): Promise<void> {
-	const tmp = `${dest}.tmp-link`
+export async function linkForce(src: PathBuilderLike, dest: PathBuilderLike): Promise<void> {
+	const tmp = `${dest.toString()}.tmp-link`
 
 	if (await pathExists(tmp)) {
 		await removePath(tmp)
@@ -51,9 +48,9 @@ export async function linkForce(src: string, dest: string): Promise<void> {
 }
 
 /**
- * Remove a leftover local file/symlink so the #1179 base-weights fallback engages.
+ * Removes a file or symlink at `dest` so that the runtime falls back to the base en-us weights.
  */
-export async function removeIfPresent(dest: string): Promise<void> {
+export async function removeIfPresent(dest: PathBuilder): Promise<void> {
 	try {
 		await statLink(dest)
 	} catch {
@@ -66,15 +63,14 @@ export async function removeIfPresent(dest: string): Promise<void> {
 }
 
 /**
- * Symlink one soft-feed sibling into an overlay, warning rather than failing when the source is absent.
+ * Symlinks one optional soft-feed artifact into an overlay and returns whether the source existed.
  *
- * Every one of these artifacts is OPTIONAL by design — the runtime has a fallback for each, so a fresh worktree that
- * has not built the gazetteer still geocodes. That is why the miss prints the consequence instead of throwing: the
- * operator needs to know which channel just resolved OFF, not to have the link step abort.
+ * A missing source prints `consequenceIfMissing` and does not throw, because the
+ * runtime has a fallback for every soft-feed artifact.
  */
 export async function linkSoftFeedSibling(
-	source: string,
-	destination: string,
+	source: PathBuilderLike,
+	destination: PathBuilder,
 	consequenceIfMissing: string
 ): Promise<boolean> {
 	if (!(await pathExists(source))) {
@@ -91,100 +87,113 @@ export async function linkSoftFeedSibling(
 }
 
 /**
- * The calibrated pair-index emission bias every shipped artifact is built at today — the R5/R6/R9/R10/R11 bars were all
- * measured at δ=10 (each linker's own docstring carries its locale's receipt).
+ * The pair-index emission bias (δ) used by every shipped pair-index artifact.
  */
 export const PAIR_INDEX_DELTA = 10
 
 /**
- * The decoder transition-entry bonus (TRANSITION-BETA build, 2026-07-24 — operator-approved β=5 from the
- * transition-level probe). en-nz deliberately builds WITHOUT one (unmeasured there): the two magnitudes are calibrated
- * independently, and a locale earning one says nothing about the other.
+ * The decoder transition-entry bonus (β).
+ * Only locales that were calibrated with it pass it.
  */
 export const PAIR_INDEX_TRANSITION_BETA = 5
 
 /**
- * The WHOLE-EDGE parent-bias magnitude (#46, default-on 2026-08-04) at the verdict's recommended δ=5 — see
- * `docs/records/evals/2026-08-04-pix1-whole-edge-verdict.md`. Only the measured locales (us/gb/nz/fr) pass it; the
- * D-rule's answer to an unmeasured locale is a per-locale absence, not an inherited magnitude.
+ * The whole-edge parent-bias magnitude.
+ * Only locales that were calibrated with it pass it.
+ *
+ * Other locales omit the flag and do not inherit this value.
  */
 export const PAIR_INDEX_PARENT_DELTA = 5
 
 /**
- * What one pair-index build has to say about itself. Everything else is shared.
+ * Describes one locale's pair-index build.
+ *
+ * When `sources`, `inputs` and `extraArgs` are omitted, the build reads the shared WOF admin database.
  */
 export interface PairIndexOverlay {
 	/**
-	 * Workspace directory name, e.g. `neural-weights-de-de`.
+	 * The weights workspace directory name, such as `neural-weights-de-de`.
+	 * The overlay locale is derived from it.
 	 */
 	packageDir: string
+
 	/**
-	 * ISO country code passed to `gazetteer pair-index --country`, and the suffix of the built artifact (`de` →
-	 * `pair-index-de.bin`). NOT the locale tag: `en-in` builds `pair-index-in.bin`.
+	 * The ISO country code passed to `--country` and used in `pair-index-<country>.bin`.
+	 *
+	 * It can differ from the locale tag.
+	 * For example, `en-in` builds `pair-index-in.bin`.
 	 */
 	country: string
+
 	/**
-	 * Calibrated magnitudes the locale's bars were measured at. Baked into the artifact's PIX1 header, which is how the
-	 * freshness check notices a change to any of them. An ABSENT `transitionBeta`/`parentDelta` means the flag is not
-	 * passed and the header carries no such key — a real state, distinct from zero (see `PairIndexHeader.parentDelta`).
-	 * The whole calibration feeds both the build FLAGS and the staleness EXPECTATION, so the two cannot disagree.
+	 * The child bias magnitude.
+	 *
+	 * The build writes `delta`, `transitionBeta` and `parentDelta` into the PIX1 header.
+	 * The freshness check compares them.
+	 *
+	 * An absent `transitionBeta` or `parentDelta` leaves its key out of the header.
+	 * The freshness check treats an absent key as distinct from zero.
 	 */
 	delta: number
 	transitionBeta?: number
 	parentDelta?: number
+
 	/**
-	 * Source FILES whose md5s the build records, in the order `gazetteer pair-index` records them. The freshness guard
-	 * compares EVERY one against the existing header (#1734): a partial comparison leaves the guard blind to the rest,
-	 * and a stale artifact then keeps reporting itself fresh while the data it was built from has moved. Empty means the
-	 * build's source cannot be file-hashed (fr's BAN directory) and freshness rests on the magnitudes alone. Default: the
-	 * WOF admin DB.
+	 * The source files whose MD5s the build records, in the order that `gazetteer pair-index` records them.
+	 * The default is the WOF admin database.
+	 *
+	 * The freshness check compares each MD5 with the header.
+	 * An empty list makes the check compare the magnitudes only.
 	 */
-	sources?: string[]
+	sources?: PathBuilder[]
+
 	/**
-	 * Inputs that must exist before a build is attempted — a missing one warns and returns, because a fresh clone has no
-	 * data root and `yarn test` invokes the linkers to verify auto-resolve. Default: `sources`.
+	 * Files that must exist before a build runs.
+	 *
+	 * The default is `sources`.
+	 * A missing file prints a warning and skips the build.
 	 */
-	inputs?: string[]
+	inputs?: PathBuilder[]
+
 	/**
-	 * Extra CLI args naming the build's sources (`--source`, `--borough-db`, `--pairs-jsonl`, `--ban-dir`). Default:
-	 * `--borough-db <admin db>`.
+	 * Extra CLI arguments that pass the build's sources.
+	 * The default is `--borough-db <admin db>`.
 	 */
-	extraArgs?: string[]
+	extraArgs?: PathBuilderLike[]
+
 	/**
-	 * Refuse to trust an existing artifact smaller than this. fr-fr's guard: a pair index built from the WRONG source can
-	 * carry matching magnitudes, and size is the one signal the header cannot fake.
+	 * The byte size below which an existing artifact is rebuilt.
+	 *
+	 * A build from the wrong source can have matching header magnitudes but a smaller size.
 	 */
 	minimumPlausibleBytes?: number
 }
 
 /**
- * The header fields a dev-weights freshness guard reads.
+ * The pair-index header fields that the dev-weights freshness check reads.
  */
 export interface PairIndexHeaderFields {
 	delta: number
 	transitionBeta: number | undefined
 	parentDelta: number | undefined
 	schemaVersion: number
+
 	/**
-	 * One md5 per source the build read, in fold order. Empty on a header that recorded none.
+	 * One MD5 per source the build read, in recorded order.
+	 * The list is empty when the header has none.
 	 */
 	sourceMD5s: string[]
 }
 
 /**
- * Minimal PIX1 header reader — magic + header only, reimplemented so a data-only weights package gains no dependency on
- * `@mailwoman/neural` (which pulls onnxruntime-node) to read a few fields. `neural/pair-index-resolver.ts`'s own header
- * parse is the source of truth this must follow.
+ * Reads the calibration fields from a PIX1 pair-index header without depending on `@mailwoman/neural`.
  *
- * Shared by the overlay build below AND by the four hand-written base linkers
- * (`neural-weights-{en-us,en-gb,en-nz,fr-fr}/scripts/link-dev-weights.ts`), which each carried their own near-copy
- * before 2026-08-04 — the ×5 clone the taste audit named, and the reason three of them were schema-blind while this one
- * was not.
+ * The parse must match the reader in `neural/lib/pair/index/resolver.ts`.
  */
-export async function peekPairIndexHeaderFields(path: string): Promise<PairIndexHeaderFields> {
+export async function peekPairIndexHeaderFields(path: PathBuilderLike): Promise<PairIndexHeaderFields> {
 	const bytes = await readLocalBuffer(path)
 	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
-	// "PIX1" little-endian.
+
 	const MAGIC = 0x31_58_49_50
 
 	if (view.getUint32(0, true) !== MAGIC) {
@@ -210,21 +219,17 @@ export async function peekPairIndexHeaderFields(path: string): Promise<PairIndex
 	}
 }
 
-/**
- * Hex characters in an md5 digest.
- */
 const MD5_HEX_LENGTH = 32
 
+// repo-health-ignore export-name-affix -- This variant caches the hash in a sidecar.
+// `md5File` hashes every time.
 /**
- * Md5 of `path`, cached in a standard `md5sum`-format sidecar (`<hash> <filename>`) beside it so a multi-gigabyte
- * source is hashed once per change rather than once per linker run. The sidecar is trusted only when at least as new as
- * the source; a missing or stale sidecar recomputes and rewrites, so the cache self-heals.
+ * Returns the MD5 of `path`, cached in a `<path>.md5` sidecar in `md5sum` format.
  *
- * The shared home for the copies the base linkers (`en-us`, `en-gb`, `en-nz`) each carry — new callers import this one.
+ * The sidecar is used only when it is at least as new as the source.
  */
-// repo-health-ignore export-name-affix -- the sidecar cache IS the added behaviour; `md5File` hashes every time.
-export async function md5FileWithSidecar(path: string): Promise<string> {
-	const sidecarPath = `${path}.md5`
+export async function md5FileWithSidecar(path: PathBuilderLike): Promise<string> {
+	const sidecarPath = `${path.toString()}.md5`
 	const sourceStats = await statPath(path)
 
 	if (await pathExists(sidecarPath)) {
@@ -234,9 +239,7 @@ export async function md5FileWithSidecar(path: string): Promise<string> {
 
 				if (hash && hash.length === MD5_HEX_LENGTH) return hash
 			}
-		} catch {
-			// Unreadable sidecar — recompute below.
-		}
+		} catch {}
 	}
 
 	const hash = await md5File(path)
@@ -248,9 +251,10 @@ export async function md5FileWithSidecar(path: string): Promise<string> {
 }
 
 /**
- * The calibrated magnitudes a linker bakes into its artifact. `undefined` means the flag is NOT passed and the header
- * carries no such key — a real state, distinct from zero (see `PairIndexHeader.parentDelta`), so the comparison below
- * is `!==` against `undefined` rather than a truthiness test.
+ * The calibrated magnitudes that a linker writes into its pair-index artifact.
+ *
+ * An `undefined` magnitude means the header has no such key.
+ * It is distinct from zero.
  */
 export interface PairIndexCalibration {
 	delta: number
@@ -259,12 +263,10 @@ export interface PairIndexCalibration {
 }
 
 /**
- * Why an existing `pair-index-*.bin` is stale against `expected`, or `undefined` when its header matches. Covers the
- * FORMAT (schemaVersion) and every calibrated magnitude; source-md5 freshness stays with the caller, because each base
- * linker passes a different set of sources and only it knows what they are.
+ * Returns why a pair-index header's schema or magnitudes differ from `expected`,
+ * or `undefined` when they match.
  *
- * One place so a magnitude added to the header cannot be checked by some linkers and not others — which is exactly how
- * three of the four base linkers ended up unable to notice a schema bump.
+ * The caller checks the source MD5s because only the caller knows its sources.
  */
 export function pairIndexStaleReason(
 	header: PairIndexHeaderFields,
@@ -288,38 +290,24 @@ export function pairIndexStaleReason(
 }
 
 /**
- * The PIX1 schema this tree's reader requires. MUST equal `KNOWN_SCHEMA_VERSION` in `neural/pair-index-resolver.ts` —
- * they are two ends of one fact, and this copy exists only because a data-only overlay must not gain a dependency on
- * `@mailwoman/neural` (onnxruntime-node) to read one header field. Bump BOTH in the same commit; a schema bump that
- * leaves this behind makes every dev checkout rebuild-loop or serve an artifact the runtime refuses.
+ * The PIX1 schema version the pair-index reader requires.
  *
- * The freshness guard must compare it: a guard that checks only delta + source md5 reads a format-obsolete binary as
- * "current" and leaves every dev checkout with artifacts the runtime refuses — the R5 freshness-guard lesson, format
- * edition. Also compared by the four hand-written base linkers (`neural-weights-{en-us,en-gb,en-nz,fr-fr}`), which
- * import this constant rather than re-typing the number.
+ * It must equal `KNOWN_SCHEMA_VERSION` in `neural/lib/pair/index/resolver.ts`.
+ * A mismatch makes dev checkouts rebuild on every run or link an artifact that the runtime refuses.
  */
 export const REQUIRED_PAIR_INDEX_SCHEMA = 3
 
 /**
- * Warn when the per-locale FST a linker just symlinked was built from a DIFFERENT admin database than the one on disk
- * now.
+ * Warns when a linked per-locale FST was built from a different admin database than the one on disk.
  *
- * WHY IT WARNS RATHER THAN REBUILDS, unlike its pair-index sibling above. A pair index is seconds of work and the
- * linker owns its whole recipe. A locale FST is a multi-minute build whose output goes to a STAGING dir on purpose —
- * the swap into `fst-per-locale/` is operator-approved after the battery, because an FST changes decoder behaviour and
- * the D-rule does not let that land unmeasured. So the guard's job is to make the drift impossible to miss, and to name
- * the command that starts fixing it. It is also why a stale FST is never fatal: the artifact is a decode-time bias
- * list, and a dev tree must still run.
- *
- * The source-side half of the comparison lives here rather than in `fst-freshness.ts` for the same reason
- * `pairIndexStaleReason` splits: only the caller knows which database it built against. All three FST-linking base
- * packages build against the same one, so they share this rather than each pinning it.
+ * It does not rebuild, because an FST rebuild writes to a staging directory
+ * and an operator swaps it in after evaluation.
  */
-export async function warnIfFSTStale(fstPath: string, locale: string): Promise<void> {
+export async function warnIfFSTStale(fstPath: PathBuilder, locale: string): Promise<void> {
 	const warning = await fstFreshnessWarning({
 		fstPath,
-		sourceDBPath: String(dataRootPath("wof", "admin-global-priority.db")),
-		rebuildCommand: `node packages/mailwoman/out/cli.js gazetteer build fst --locales ${locale}  (writes to a staging dir; swap is operator-conditional)`,
+		sourceDBPath: wofDatabasePath("admin-global-priority.db"),
+		rebuildCommand: `node packages/mailwoman/out/cli/main.js gazetteer build fst --locales ${locale}  (writes to a staging dir; swap is operator-conditional)`,
 	})
 
 	if (warning) {
@@ -328,17 +316,15 @@ export async function warnIfFSTStale(fstPath: string, locale: string): Promise<v
 }
 
 /**
- * Symlink the per-locale FST gazetteer (`fst-<locale>.bin`) from the shared build area
- * (`$MAILWOMAN_DATA_ROOT/wof/fst-per-locale/`) into an overlay so `resolveWeights` surfaces `fstPath` in dev and the
- * runtime pipeline can auto-wire the gazetteer + street-context check, then run {@link warnIfFSTStale} on the linked
- * artifact. The publish flow stages the real binary (release-sequenced).
+ * Symlinks the per-locale FST gazetteer `fst-<locale>.bin` into an overlay
+ * and checks it with {@link warnIfFSTStale}.
  */
-export async function linkLocaleFST(destDir: string, locale: string): Promise<void> {
-	const source = String(dataRootPath("wof", "fst-per-locale", `fst-${locale}.bin`))
+export async function linkLocaleFST(destDir: PathBuilder, locale: string): Promise<void> {
+	const source = wofDatabasePath("fst-per-locale", `fst-${locale}.bin`)
 
 	const linked = await linkSoftFeedSibling(
 		source,
-		resolvePath(destDir, `fst-${locale}.bin`),
+		destDir(`fst-${locale}.bin`),
 		"the FST gazetteer default will resolve OFF for this locale."
 	)
 
@@ -348,32 +334,22 @@ export async function linkLocaleFST(destDir: string, locale: string): Promise<vo
 }
 
 /**
- * Symlink the sealed locale-general street-morphology FST (`$MAILWOMAN_DATA_ROOT/wof/fst-street-morphology.bin`,
- * `mailwoman gazetteer build street-morphology`) into an overlay so `resolveWeights` surfaces `streetMorphologyPath` in
- * dev and the street-context check (#1315) deserializes the artifact instead of rebuilding from the libpostal
- * dictionaries per process. Missing is non-fatal — the runtime loader's dictionary-build fallback covers it.
+ * Symlinks the prebuilt street-morphology FST into an overlay so that the
+ * street-context check does not rebuild it from dictionaries.
  */
-export async function linkStreetMorphologyFST(destDir: string): Promise<void> {
+export async function linkStreetMorphologyFST(destDir: PathBuilder): Promise<void> {
 	await linkSoftFeedSibling(
-		String(dataRootPath("wof", "fst-street-morphology.bin")),
-		resolvePath(destDir, "fst-street-morphology.bin"),
+		wofDatabasePath("fst-street-morphology.bin"),
+		destDir("fst-street-morphology.bin"),
 		"the street-context check falls back to the per-process dictionary build."
 	)
 }
 
-/**
- * Why an existing artifact may be TRUSTED without a rebuild, or `undefined` when it must be rebuilt (with the reason
- * already printed). The skip requires both halves (#1734): the header magnitudes + format (`pairIndexStaleReason`) AND
- * the header's `sourceMD5s` against the current sources' md5s. Magnitudes alone read a source change as "current"
- * whenever pair counts happen not to move the calibrated numbers — the R5 freshness-guard lesson, which resurfaced in
- * the 2026-08-18 admin swap. A source that is not on disk to re-hash leaves the magnitudes as the best available answer
- * (the "missing source, can't build" branch below would fire anyway if a rebuild were needed).
- */
 async function pairIndexIsFresh(
-	dest: string,
+	dest: PathBuilder,
 	artifact: string,
 	expected: PairIndexCalibration,
-	sources: string[],
+	sources: PathBuilder[],
 	minimumPlausibleBytes: number | undefined
 ): Promise<boolean> {
 	try {
@@ -447,30 +423,23 @@ async function pairIndexIsFresh(
 }
 
 /**
- * Build `pair-index-<country>.bin` into the overlay, skipping the work when the artifact on disk was already built at
- * these magnitudes FROM the sources on disk (see {@link pairIndexIsFresh}). The calibration object drives both the
- * staleness expectation and the CLI flags, so a magnitude cannot be checked by the guard and dropped from the build.
+ * Builds `pair-index-<country>.bin` into the overlay unless the existing artifact
+ * already matches these magnitudes and sources.
  *
- * Exits non-zero on a failed build. Missing INPUTS (an unbuilt CLI, an absent source) warn and return instead: a fresh
- * clone has neither, and `yarn test` invokes this to verify auto-resolve, so a hard failure there would be a failure to
- * have run a build yet rather than a real fault.
+ * A failed build exits the process.
+ * A missing CLI or input only prints a warning, because a fresh clone has neither.
  */
 export async function buildPairIndexOverlay(overlay: PairIndexOverlay): Promise<void> {
 	const { packageDir, country, delta, transitionBeta, parentDelta } = overlay
-	const CLI = String(workspacePath("mailwoman", "out", "cli.js"))
+	const CLI = workspacePathBuilder("mailwoman", "out", "cli", "main.js")
 	const ARTIFACT = `pair-index-${country}.bin`
-	// Built into the data-root OVERLAY, not into the tracked package. The locale is recovered from the
-	// workspace name (`neural-weights-en-gb` → `en-gb`) so callers keep passing the one identifier they
-	// already had.
-	const PKG_DIR = String(weightsOverlayPath(packageDir.replace(/^neural-weights-/, "")))
-	const DEST = resolvePath(PKG_DIR, ARTIFACT)
+
+	const PKG_DIR = weightsOverlayPath(packageDir.replace(/^neural-weights-/, ""))
+	const DEST = PKG_DIR(ARTIFACT)
 
 	await makeDirectories(PKG_DIR)
 
-	/**
-	 * Checked-in WOF-derived admin pairs — the default source, and the whole source list for the small overlays.
-	 */
-	const WOF_ADMIN_DB = String(dataRootPath("wof", "admin-global-priority.db"))
+	const WOF_ADMIN_DB = wofDatabasePath("admin-global-priority.db")
 	const sources = overlay.sources ?? [WOF_ADMIN_DB]
 	const inputs = overlay.inputs ?? sources
 	const extraArgs = overlay.extraArgs ?? ["--borough-db", WOF_ADMIN_DB]
@@ -532,11 +501,8 @@ export async function buildPairIndexOverlay(overlay: PairIndexOverlay): Promise<
 	console.log(`built ${ARTIFACT}`)
 }
 
-// --- the manifest form ----------------------------------------------------------------------------------------------
-
 /**
- * A soft-feed sibling an overlay links: where it comes from, the name it takes in the overlay, and the consequence line
- * printed when the source is missing (the link is warn-and-continue; the channel resolves OFF).
+ * A soft-feed artifact that an overlay links, with the warning to print when its source is missing.
  */
 export interface SoftFeedLink {
 	source: string
@@ -545,9 +511,9 @@ export interface SoftFeedLink {
 }
 
 /**
- * The committed soft-feed lexicons as links, by channel, read from `release.config.json` so the filename a manifest
- * links is the one the release ships. `streetType` is offered for completeness; the manifests link the evidence
- * lexicons by the generation their CARD names instead (`evidenceLexiconsFromCard`).
+ * Returns the committed soft-feed lexicons as links.
+ *
+ * The filenames come from `release.config.json` so that dev links match the release.
  */
 export async function committedSoftFeedLinks(): Promise<{
 	anchor: SoftFeedLink
@@ -578,8 +544,7 @@ export async function committedSoftFeedLinks(): Promise<{
 }
 
 /**
- * The slice of a weights package's committed `model-card.json` the dev materialization reads: the shipped digests the
- * release re-verifies against the published tarball, and the channel requirements that name evidence lexicons.
+ * The fields of a weights package's `model-card.json` that dev materialization reads.
  */
 export interface WeightsCard {
 	files_md5?: Record<string, string>
@@ -587,134 +552,138 @@ export interface WeightsCard {
 }
 
 /**
- * What one locale's `scripts/link-dev-weights.ts` declares, so an overlay is a manifest plus a call rather than a
- * script cloned from a sibling. Every step is optional and runs only when named, in a fixed order: model pair,
- * soft-feed siblings, card-named evidence lexicons, postcode binary, pair index, FSTs.
+ * Declares what one locale's dev overlay contains. {@link materializeDevOverlay}
+ * runs the steps in the order the fields are listed.
  */
 export interface DevOverlayManifest {
 	/**
-	 * The overlay's locale tag, lower-case. The workspace is `neural-weights-<locale>` and the artifacts land in
-	 * `$MAILWOMAN_DATA_ROOT/weights/<locale>/`, never in the tracked package: the binaries are not in git, so
-	 * materializing them there made a fresh worktree unable to geocode, made `yarn test` mutate a tracked directory, and
-	 * put a symlink into a publish tarball (`YN0035`).
+	 * The overlay's lowercase locale tag.
+	 * The workspace is `neural-weights-<locale>`.
+	 *
+	 * Artifacts go to the data root's `weights/<locale>/` overlay because the binaries are kept out of git.
 	 */
 	locale: string
+
 	/**
-	 * What happens to `model.onnx` + `tokenizer.model`. `link`: the pair is symlinked from the paths
-	 * `release.config.json`'s `weights` block names under the data root (`$MAILWOMAN_DEV_MODEL` /
-	 * `$MAILWOMAN_DEV_TOKENIZER` override them), and when `digestCard` names a workspace the linked default bytes must
-	 * match that workspace's card `files_md5` — the #397 drift guard, which fails loud instead of grading the wrong
-	 * model; an override skips the check and says so. `inherit`: the package declares `mailwoman.baseWeights`, so any
-	 * local pair is REMOVED — a stale local file shadows the base fallback and silently serves outdated bytes. Omitted:
-	 * the pair is left to `packages/release-kit/lib/weights/link-weights-overlay.ts`, the recipe writer.
+	 * How the overlay gets its model files.
+	 *
+	 * When it is omitted, `link-weights-overlay.ts` in release-kit handles them.
+	 *
+	 * The `link` kind symlinks `model.onnx` and `tokenizer.model` from the
+	 * `release.config.json` weights paths under the data root.
+	 * The `$MAILWOMAN_DEV_MODEL` and `$MAILWOMAN_DEV_TOKENIZER` variables override those paths.
+	 *
+	 * With `digestCard`, the linked default files must match the `files_md5` of that workspace's card.
+	 * An override skips this check.
+	 *
+	 * The `inherit` kind removes any local pair, because the package declares
+	 * `mailwoman.baseWeights` and a local file would shadow the base.
+	 *
+	 * The `char` kind links the `charWeights.<family>` model, character vocabulary and model card.
+	 * It removes any tokenizer.
 	 */
 	model?: { kind: "link"; digestCard?: string } | { kind: "inherit" } | { kind: "char"; family: string }
+
 	/**
-	 * Soft-feed siblings linked warn-and-continue, in order.
+	 * Soft-feed siblings to link in order.
+	 * A missing source prints a warning and the step continues.
 	 */
 	softFeed?: ReadonlyArray<SoftFeedLink>
+
 	/**
-	 * Link the evidence lexicons the overlay's own card names under `requires.<channel>.lexicon`, so the generation comes
-	 * from the card the loader reads and a card bump moves the artifact with it. `street-type-lexicon-v*.json` is
-	 * committed under `data/gazetteer/`; `locality-surface-lexicon-v*.json` is 7–13 MB and lives in the data root.
+	 * Whether to link the evidence lexicons listed under `requires.<channel>.lexicon`
+	 * in the overlay's model card.
+	 * A card update then changes the linked file too.
+	 *
+	 * The street-type lexicon comes from the repo's `data/gazetteer/`.
+	 * The locality-surface lexicon comes from the data root.
 	 */
 	evidenceLexiconsFromCard?: boolean
+
 	/**
-	 * Build `postcode-<country>.bin` from a WOF postcode extract through the compiled `gazetteer postcode-binary` CLI,
-	 * skipped when already present (it rebuilds in seconds, and the extract is versionless on disk).
+	 * Builds `postcode-<country>.bin` from a WOF postcode extract with the compiled CLI.
+	 * The step is skipped when the file already exists.
 	 */
-	postcodeBinary?: { country: string; database: string }
+	postcodeBinary?: { country: string; database: PathBuilder }
+
 	/**
-	 * The placetype-pair index build, minus `packageDir`, which follows from `locale`.
+	 * The placetype-pair index build.
+	 * Its `packageDir` is derived from `locale`.
 	 */
 	pairIndex?: Omit<PairIndexOverlay, "packageDir">
+
 	/**
-	 * Link `fst-<locale>.bin` with its freshness warning.
+	 * Whether to link `fst-<locale>.bin` and warn when it is stale.
 	 */
 	localeFST?: boolean
+
 	/**
-	 * Link the shared street-morphology FST.
+	 * Whether to link the shared street-morphology FST.
 	 */
 	streetMorphologyFST?: boolean
 }
 
 /**
- * What a materialized overlay hands back for the locale-specific step a manifest cannot express (en-gb's
- * card-conditional postcode binary is the one that exists).
+ * The overlay directory, CLI path and model card that {@link materializeDevOverlay} returns.
+ *
+ * Callers use them for locale-specific steps that a manifest cannot express.
  */
 export interface DevOverlay {
-	destDir: string
-	cli: string
+	destDir: PathBuilder
+	cli: PathBuilder
 	card: WeightsCard | undefined
 }
 
-/**
- * Where each evidence channel's lexicon is found, by the name the card declares.
- */
 const EVIDENCE_LEXICON_SOURCES: ReadonlyArray<{
 	channel: "street_type" | "locality_surface"
-	source: (name: string) => string
+	source: (name: string) => PathBuilder
 }> = [
-	{ channel: "street_type", source: (name) => String(repoRootPath("data", "gazetteer", name)) },
-	{ channel: "locality_surface", source: (name) => String(dataRootPath("gazetteer", name)) },
+	{ channel: "street_type", source: (name) => repoRootPathBuilder("data", "gazetteer", name) },
+	{ channel: "locality_surface", source: (name) => dataRootPath("gazetteer", name) },
 ]
 
-/**
- * Read a weights workspace's committed card, or `undefined` when the workspace carries none.
- */
 async function readWeightsCard(workspace: string): Promise<WeightsCard | undefined> {
-	const path = resolvePath(String(workspacePath(workspace)), "model-card.json")
+	const path = workspacePathBuilder(workspace, "model-card.json")
 
 	if (!(await pathExists(path))) return undefined
 
 	return readLocalJSONFile<WeightsCard>(path)
 }
 
-/**
- * Link the base model pair from the release recipe and, when a digest card is named, hold the linked default bytes to
- * that card's `files_md5`. The recipe and the card are the two registers a ship bumps in lockstep; a path bumped
- * without the card, or the reverse, fails here rather than after an eval shift graded against the wrong weights.
- */
-/**
- * A char-path base (#2164): the graph and its sealed vocabulary from `release.config.json`'s `charWeights[family]`, no
- * tokenizer. The dev overlay carries both so `resolveWeights` finds the package whole.
- */
-async function linkCharModel(destDir: string, family: string): Promise<void> {
+async function linkCharModel(destDir: PathBuilder, family: string): Promise<void> {
 	const recipe = (await readReleaseConfig()).charWeights?.[family]
 
 	if (!recipe) {
 		throw new Error(`release.config.json declares no charWeights.${family} — nothing to link for the ${family} base`)
 	}
 
-	const dataRoot = String(dataRootPath())
+	const dataRoot = dataRootPath()
 
 	for (const [name, relative] of [
 		["model.onnx", recipe.model],
 		["char-vocab.json", recipe.charVocab],
 	] as const) {
-		const source = resolvePath(dataRoot, relative)
+		const source = dataRoot(relative)
 
 		if (!(await pathExists(source))) {
 			throw new Error(`missing char-path source ${name} for ${family}: ${source}`)
 		}
 
-		await linkForce(source, resolvePath(destDir, name))
+		await linkForce(source, destDir(name))
 
-		console.log(`linked ${resolvePath(destDir, name)} ← ${source}`)
+		console.log(`linked ${destDir(name)} ← ${source}`)
 	}
 
-	// The card is what tells `resolveWeights` this package owes a vocabulary rather than a tokenizer (its `encoder`
-	// block), so the overlay carries the workspace's committed card beside the two binaries.
-	const card = resolvePath(String(workspacePath(`neural-weights-${family}`)), "model-card.json")
+	const card = workspacePathBuilder(`neural-weights-${family}`, "model-card.json")
 
-	await linkForce(card, resolvePath(destDir, "model-card.json"))
-	await removeIfPresent(resolvePath(destDir, "tokenizer.model"))
+	await linkForce(card, destDir("model-card.json"))
+	await removeIfPresent(destDir("tokenizer.model"))
 }
 
-async function linkBaseModelPair(destDir: string, digestCard: string | undefined): Promise<void> {
+async function linkBaseModelPair(destDir: PathBuilder, digestCard: string | undefined): Promise<void> {
 	const recipe = await readReleaseConfig()
 
-	const dataRoot = String(dataRootPath())
+	const dataRoot = dataRootPath()
 	const digests = digestCard ? (await readWeightsCard(digestCard))?.files_md5 : undefined
 
 	const pair = [
@@ -728,13 +697,13 @@ async function linkBaseModelPair(destDir: string, digestCard: string | undefined
 	]
 
 	for (const { label, name, override, recipe: recipePath } of pair) {
-		const source = override || resolvePath(dataRoot, recipePath)
+		const source = override || dataRoot(recipePath)
 
 		if (!(await pathExists(source))) {
 			throw new Error(`missing source ${label}: ${source} — set MAILWOMAN_DEV_${label.toUpperCase()} to override`)
 		}
 
-		const dest = resolvePath(destDir, name)
+		const dest = destDir(name)
 
 		await linkForce(source, dest)
 
@@ -770,17 +739,13 @@ async function linkBaseModelPair(destDir: string, digestCard: string | undefined
 	}
 }
 
-/**
- * Build a postcode binary from a WOF postcode extract, skip-if-present. A missing CLI or extract is a warning (the
- * anchor channel resolves OFF for that country); a build that runs and fails is an error.
- */
 async function buildPostcodeBinary(
-	destDir: string,
-	cli: string,
-	{ country, database }: { country: string; database: string }
+	destDir: PathBuilder,
+	cli: PathBuilder,
+	{ country, database }: { country: string; database: PathBuilder }
 ): Promise<void> {
 	const artifact = `postcode-${country.toLowerCase()}.bin`
-	const dest = resolvePath(destDir, artifact)
+	const dest = destDir(artifact)
 
 	if (await pathExists(dest)) {
 		console.log(`skipped ${artifact} build — ${dest} already present`)
@@ -806,7 +771,15 @@ async function buildPostcodeBinary(
 
 	const result = spawnProcessSync(
 		process.execPath,
-		[cli, "gazetteer", "postcode-binary", "--out", destDir, "--locale", `${country.toUpperCase()}:${database}`],
+		[
+			cli,
+			"gazetteer",
+			"postcode-binary",
+			"--out",
+			destDir,
+			"--locale",
+			`${country.toUpperCase()}:${database.toString()}`,
+		],
 		{ stdio: "inherit" }
 	)
 
@@ -818,19 +791,18 @@ async function buildPostcodeBinary(
 }
 
 /**
- * Materialize one locale's dev overlay from its manifest. The steps run in the order {@link DevOverlayManifest}
- * documents, each independent on disk, and the result carries what a locale-specific step needs afterwards.
+ * Materializes one locale's dev weights overlay from its manifest.
  */
 export async function materializeDevOverlay(manifest: DevOverlayManifest): Promise<DevOverlay> {
-	const destDir = String(weightsOverlayPath(manifest.locale))
-	const cli = String(workspacePath("mailwoman", "out", "cli.js"))
+	const destDir = weightsOverlayPath(manifest.locale)
+	const cli = workspacePathBuilder("mailwoman", "out", "cli", "main.js")
 	const card = await readWeightsCard(`neural-weights-${manifest.locale}`)
 
 	await makeDirectories(destDir)
 
 	if (manifest.model?.kind === "inherit") {
-		await removeIfPresent(resolvePath(destDir, "model.onnx"))
-		await removeIfPresent(resolvePath(destDir, "tokenizer.model"))
+		await removeIfPresent(destDir("model.onnx"))
+		await removeIfPresent(destDir("tokenizer.model"))
 	} else if (manifest.model?.kind === "link") {
 		await linkBaseModelPair(destDir, manifest.model.digestCard)
 	} else if (manifest.model?.kind === "char") {
@@ -838,7 +810,7 @@ export async function materializeDevOverlay(manifest: DevOverlayManifest): Promi
 	}
 
 	for (const { source, name, consequenceIfMissing } of manifest.softFeed ?? []) {
-		await linkSoftFeedSibling(source, resolvePath(destDir, name), consequenceIfMissing)
+		await linkSoftFeedSibling(source, destDir(name), consequenceIfMissing)
 	}
 
 	if (manifest.evidenceLexiconsFromCard) {
@@ -853,7 +825,7 @@ export async function materializeDevOverlay(manifest: DevOverlayManifest): Promi
 
 			await linkSoftFeedSibling(
 				source(declared),
-				resolvePath(destDir, declared),
+				destDir(declared),
 				`the ${channel} channel will resolve OFF in this worktree.`
 			)
 		}