@mailwoman/neural-weights-it-it 8.6.0

package/README.md

@@ -0,0 +1,10 @@
+# @mailwoman/neural-weights-it-it
+
+it-IT weights overlay for [mailwoman](https://mailwoman.sister.software).
+
+**Data-only.** Declares `mailwoman.baseWeights` and shares the base model and tokenizer with
+`@mailwoman/neural-weights-en-us`; what it adds is `pair-index-it.bin`.
+
+```sh
+npm install @mailwoman/neural-weights-it-it
+```

package/model-card.json

@@ -0,0 +1,25 @@
+{
+	"name": "@mailwoman/neural-weights-it-it",
+	"version": "7.0.0",
+	"locale": "it-IT",
+	"license": "AGPL-3.0",
+	"$comment": "Data-only overlay. Shares model.onnx + tokenizer.model with en-us via mailwoman.baseWeights.",
+	"files": {
+		"model_card": "model-card.json",
+		"pair_index": "pair-index-it.bin"
+	},
+	"it_artifacts": {
+		"$comment": "Hierarchy campaign R11 (2026-08-02). The Italian instance of the dependent-locality prior.",
+		"pair_index_it_bin": {
+			"format": "PIX1 placetype-pair index \u2014 a retrieval-augmented (quartiere, comune) dependent_locality prior, e.g. (\"Trastevere\", \"Roma\")",
+			"source": "Who's On First admin hierarchy. No postal register carries the sub-city line for this country, so WOF is the source \u2014 the same call the US, DE and IN instances made.",
+			"pairs": 4026,
+			"bytes": 103515,
+			"delta_calibration": "\u03b4=10, transitionBeta=5 \u2014 inherited from GB per R5's uniform-deficit finding.",
+			"country_gate": "hard-gated on the header's country (it).",
+			"requires_leading_postcode_strip": "INERT without the `it` entries in SEGMENT_PARENT_POSTCODE_SHAPES and LEADING_POSTCODE_COUNTRIES (neural/placetype-pair-prior.ts) \u2014 Italian addresses write the postcode first.",
+			"parent_alias_expansion": "ENABLED. WOF stores `Rome` (its English preferred name) for a city Italians write `Roma`, carried as the `ita` preferred name. Aliases are drawn from names whose language is OFFICIAL for the country (codex isOfficialLanguage) plus English, and must be LATIN-SCRIPT \u2014 the model never sees other scripts.",
+			"not_committed": "derived artifact, .gitignore'd \u2014 rebuilt via `mailwoman gazetteer pair-index --out neural-weights-it-it --country it --delta 10 --transition-beta 5 --borough-db <wof/admin-global-priority.db>`"
+		}
+	}
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@mailwoman/neural-weights-it-it",
+  "version": "8.6.0",
+  "description": "it-IT weights overlay for mailwoman — data-only; shares the base model with @mailwoman/neural-weights-en-us.",
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "neural-weights-it-it"
+  },
+  "files": [
+    "model-card.json",
+    "pair-index-it.bin",
+    "README.md",
+    "*.ts",
+    "**/*.ts",
+    "!*.test.ts",
+    "!**/*.test.ts"
+  ],
+  "type": "module",
+  "dependencies": {
+    "@mailwoman/neural-weights-en-us": "8.6.0"
+  },
+  "mailwoman": {
+    "baseWeights": "@mailwoman/neural-weights-en-us"
+  }
+}

package/scripts/link-dev-weights.ts

@@ -0,0 +1,117 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Dev-weights linker for `@mailwoman/neural-weights-it-it` (hierarchy campaign R11).
+ *
+ *   This overlay ships exactly ONE artifact — `pair-index-it.bin` — because it declares
+ *   `mailwoman.baseWeights` and shares the base model/tokenizer with the en-us package. There is
+ *   nothing to symlink; the only job is building the index so `resolveWeights({locale: "de-de"})`
+ *   surfaces `pairIndexPath` in local dev.
+ *
+ *   The index is INERT without the `de` entries in `SEGMENT_PARENT_POSTCODE_SHAPES` and
+ *   `LEADING_POSTCODE_COUNTRIES` (`neural/placetype-pair-prior.ts`): German addresses write
+ *   "50733 Köln", so a parent segment folds to a key no bare-Gemeinde entry matches. Measured
+ *   during R9 — the artifact alone changed nothing until both landed.
+ */
+
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync } from "node:fs"
+import { resolve } from "node:path"
+
+import { dataRootPath, repoRootPath } from "@mailwoman/core/utils"
+
+const PKG_DIR = String(repoRootPath("neural-weights-it-it"))
+const CLI = String(repoRootPath("mailwoman", "out", "cli.js"))
+const PAIR_INDEX_BIN_DEST = resolve(PKG_DIR, "pair-index-it.bin")
+/**
+ * Checked-in WOF-derived (Ortsteil, Gemeinde) pairs — the same posture as the GB secondary sources.
+ */
+const WOF_ADMIN_DB = String(dataRootPath("wof", "admin-global-priority.db"))
+/**
+ * Calibrated magnitudes — the pair the R11 bars were measured at (0/60 confound FPs).
+ */
+const PAIR_INDEX_DELTA = 10
+const PAIR_INDEX_TRANSITION_BETA = 5
+
+/**
+ * Minimal PIX1 header reader — magic + header only, reimplemented so this data-only package gains no dependency on
+ * `@mailwoman/neural` (which pulls onnxruntime-node) to read two fields.
+ */
+function peekPairIndexHeaderFields(path: string): { delta: number; transitionBeta: number | undefined } {
+	const bytes = readFileSync(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) {
+		throw new Error(`pair index: bad magic reading ${path}`)
+	}
+
+	const headerLen = view.getUint32(4, true)
+	const header = JSON.parse(Buffer.from(bytes.subarray(8, 8 + headerLen)).toString("utf8")) as {
+		delta: number
+		transitionBeta?: number
+	}
+
+	return { delta: header.delta, transitionBeta: header.transitionBeta }
+}
+
+if (!existsSync(CLI)) {
+	console.error(`WARNING: ${CLI} not built — run \`yarn compile\` first, then re-run for pair-index-it.bin.`)
+} else if (!existsSync(WOF_ADMIN_DB)) {
+	console.error(`WARNING: missing ${WOF_ADMIN_DB} — pair-index-it.bin not built.`)
+} else {
+	let needsRebuild = true
+
+	if (existsSync(PAIR_INDEX_BIN_DEST)) {
+		try {
+			const header = peekPairIndexHeaderFields(PAIR_INDEX_BIN_DEST)
+
+			if (header.delta !== PAIR_INDEX_DELTA) {
+				console.log(`rebuilding pair-index-it.bin — delta ${header.delta} → ${PAIR_INDEX_DELTA}`)
+			} else if (header.transitionBeta !== PAIR_INDEX_TRANSITION_BETA) {
+				console.log(
+					`rebuilding pair-index-it.bin — transitionBeta ${header.transitionBeta} → ${PAIR_INDEX_TRANSITION_BETA}`
+				)
+			} else {
+				needsRebuild = false
+			}
+		} catch (error) {
+			console.log(`rebuilding pair-index-it.bin — header unreadable (${(error as Error).message})`)
+		}
+	}
+
+	if (!needsRebuild) {
+		console.log(`skipped pair-index-it.bin build — ${PAIR_INDEX_BIN_DEST} is current`)
+	} else {
+		const result = spawnSync(
+			process.execPath,
+			[
+				CLI,
+				"gazetteer",
+				"pair-index",
+				"--out",
+				PKG_DIR,
+				"--country",
+				"it",
+				"--delta",
+				String(PAIR_INDEX_DELTA),
+				"--transition-beta",
+				String(PAIR_INDEX_TRANSITION_BETA),
+				"--borough-db",
+				WOF_ADMIN_DB,
+			],
+			{ stdio: "inherit" }
+		)
+
+		if (result.status !== 0 || !existsSync(PAIR_INDEX_BIN_DEST)) {
+			console.error(`FAILED: gazetteer pair-index --country it (exit ${result.status})`)
+
+			process.exit(1)
+		}
+
+		console.log(`built pair-index-it.bin ← ${WOF_ADMIN_DB}`)
+	}
+}