@mailwoman/neural 2.1.0 → 4.0.0

package/out/postcode-anchor.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Postcode anchor — the first member of the "anchor-based parsing" family (Direction D, #240). See
+ *   `docs/articles/plan/2026-06-03-anchor-based-parsing.md`.
+ *
+ *   A postcode is the most information-dense token in an address: a hierarchical geo-encoding that
+ *   places a query on Earth far more cheaply than the rest of the parse. This module lifts the
+ *   postcode out of the BIO sequence-labelling problem and treats it as a structured anchor. It
+ *   runs the same per-country shape regexes the decoder repair pass uses ({@link collectMatches}),
+ *   resolves each shaped span against a postcode gazetteer, and returns a SOFT signal: a country
+ *   posterior plus a calibrated confidence. It never decides a postcode's identity on its own — it
+ *   reports "this string is (or is not) a real postcode, in these countries, near here", and leaves
+ *   the parser to weigh that against the surrounding tokens.
+ *
+ *   Two design rules carried from the DeepSeek consult
+ *   (`.agents/skills/deepseek-consult/ds-pc-turn{1,2}-postcode-anchor.txt`):
+ *
+ *   - The country posterior is UNIFORM over the countries a string actually exists in. We never weight
+ *       by per-country postcode volume, because that skews "75001" toward whichever country owns
+ *       more 5-digit codes — the exact bias the anchor exists to avoid. Disambiguation is the
+ *       parser's job, using script, city tokens, and user locale.
+ *   - Confidence combines gazetteer MEMBERSHIP with country AMBIGUITY. A string that matches a postcode
+ *       regex but exists in no gazetteer (a bare `27`, or a 5-digit house number that is not a real
+ *       code) gets confidence 0, so the parser treats it as a house number. A real-but-ambiguous
+ *       code (`75001` in FR and US) gets moderate confidence. A real, single-country code gets
+ *       1.0.
+ */
+/** A gazetteer hit for a postcode string. `lat`/`lon` of 0 means "known postcode, no centroid yet". */
+export interface PostcodePlace {
+    country: string;
+    lat: number;
+    lon: number;
+}
+/**
+ * The minimal surface the anchor needs from a gazetteer. Implementations: an in-memory fake (tests)
+ * or a SQLite-backed lookup over the `postalcode-*.db` shards (`@mailwoman/resolver-wof-sqlite`).
+ * Keeping the seam this narrow lets a future FST/WASM resolver drop in without touching the anchor
+ * logic.
+ */
+export interface PostcodeResolver {
+    /** Exact-match lookup of a normalized postcode string across every country shard. */
+    lookup(postcode: string): PostcodePlace[];
+}
+export interface PostcodeAnchor {
+    /** The shaped substring as it appeared in the raw text, with char offsets. */
+    span: {
+        text: string;
+        start: number;
+        end: number;
+    };
+    /** The normalized form actually queried (uppercased, `D-` prefix stripped, whitespace collapsed). */
+    normalized: string;
+    /** Coordinate-bearing gazetteer hits — best-effort centroid(s), one representative per country. */
+    candidates: PostcodePlace[];
+    /**
+     * Uniform distribution over the countries the postcode exists in (membership,
+     * coordinate-independent).
+     */
+    posterior: Record<string, number>;
+    /** `1 - normalizedEntropy(posterior)` when the postcode exists; `0` when it is in no gazetteer. */
+    confidence: number;
+    /**
+     * `exact` — the string is a real postcode; `outward` — a GB unit (`SO4 3RX`) resolved to its
+     * outward district (`SO4`), the granularity the GB gazetteer is aggregated at (no penalty — it is
+     * a real, confident GB match); `fuzzy` — only an edit-distance-1 variant exists (a likely typo /
+     * OCR slip), so the confidence carries a penalty; `none` — in no gazetteer.
+     */
+    matchType: "exact" | "outward" | "fuzzy" | "none";
+    /**
+     * Structural house-number prior in [0, 1]: `1` for a code that cannot be a house number, and
+     * below `1` for a digit-only code sharing its comma-delimited segment with a street word (so it
+     * reads as a house number rather than a postcode). Already folded into {@link confidence}; exposed
+     * so a consumer can rank competing spans, or see why one was down-weighted, without re-deriving
+     * it.
+     */
+    positionFactor: number;
+}
+export interface ExtractPostcodeAnchorsOpts {
+    /**
+     * When an exact lookup finds nothing, retry Damerau–Levenshtein ≤1 variants to absorb typos and
+     * OCR slips (`75OO8` → `75008`). Off by default so existing callers keep exact-match behaviour.
+     */
+    fuzzy?: boolean;
+}
+/**
+ * Class-aware edit-distance-1 variants of a postcode string: deletions, same-class substitutions
+ * (digit↔digit, letter↔letter), same-class insertions, and adjacent transpositions. Restricting
+ * substitutions/insertions to the character's class mirrors how humans mistype or OCR a postcode (a
+ * digit becomes another digit, not a letter) and keeps the candidate set small.
+ */
+export declare function editDistance1Variants(s: string): string[];
+/**
+ * Normalize a shaped span to the canonical gazetteer key: uppercase, collapse internal whitespace
+ * to a single space, and strip the German `D-` courtesy prefix (the shards store `68161`, not
+ * `D-68161`).
+ */
+export declare function normalizePostcode(raw: string): string;
+/**
+ * The GB outward code of a normalized unit postcode — the part before the space when the inward
+ * half is `\d[A-Z]{2}` (`SO4 3RX` → `SO4`). The GB gazetteer is aggregated to outward codes (2.7M
+ * units is too large + too fine for an anchor), so the extractor retries the outward code when a
+ * full GB unit misses. Returns `null` for any string that isn't a GB unit postcode (so it never
+ * fires elsewhere).
+ */
+export declare function gbOutwardCode(normalized: string): string | null;
+/**
+ * Extract postcode anchors from raw text. For each postcode-shaped span, resolve it against the
+ * gazetteer and emit a soft anchor (country posterior + confidence). Spans that match a shape but
+ * exist in no gazetteer are still returned, with an empty posterior and confidence 0 — an explicit
+ * "looks like a postcode, but isn't one" so the caller can see the extractor fired and chose not to
+ * anchor.
+ */
+export declare function extractPostcodeAnchors(text: string, resolver: PostcodeResolver, opts?: ExtractPostcodeAnchorsOpts): PostcodeAnchor[];
+//# sourceMappingURL=postcode-anchor.d.ts.map

package/out/postcode-anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode-anchor.d.ts","sourceRoot":"","sources":["../postcode-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAQH,uGAAuG;AACvG,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACX;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,qFAAqF;IACrF,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE,CAAA;CACzC;AAED,MAAM,WAAW,cAAc;IAC9B,8EAA8E;IAC9E,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,qGAAqG;IACrG,UAAU,EAAE,MAAM,CAAA;IAClB,mGAAmG;IACnG,UAAU,EAAE,aAAa,EAAE,CAAA;IAC3B;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,mGAAmG;IACnG,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,SAAS,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAA;IACjD;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,0BAA0B;IAC1C;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CACf;AAWD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAczD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI/D;AAuGD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,GAAE,0BAA+B,GACnC,cAAc,EAAE,CAmElB"}

package/out/postcode-anchor.js

@@ -0,0 +1,269 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Postcode anchor — the first member of the "anchor-based parsing" family (Direction D, #240). See
+ *   `docs/articles/plan/2026-06-03-anchor-based-parsing.md`.
+ *
+ *   A postcode is the most information-dense token in an address: a hierarchical geo-encoding that
+ *   places a query on Earth far more cheaply than the rest of the parse. This module lifts the
+ *   postcode out of the BIO sequence-labelling problem and treats it as a structured anchor. It
+ *   runs the same per-country shape regexes the decoder repair pass uses ({@link collectMatches}),
+ *   resolves each shaped span against a postcode gazetteer, and returns a SOFT signal: a country
+ *   posterior plus a calibrated confidence. It never decides a postcode's identity on its own — it
+ *   reports "this string is (or is not) a real postcode, in these countries, near here", and leaves
+ *   the parser to weigh that against the surrounding tokens.
+ *
+ *   Two design rules carried from the DeepSeek consult
+ *   (`.agents/skills/deepseek-consult/ds-pc-turn{1,2}-postcode-anchor.txt`):
+ *
+ *   - The country posterior is UNIFORM over the countries a string actually exists in. We never weight
+ *       by per-country postcode volume, because that skews "75001" toward whichever country owns
+ *       more 5-digit codes — the exact bias the anchor exists to avoid. Disambiguation is the
+ *       parser's job, using script, city tokens, and user locale.
+ *   - Confidence combines gazetteer MEMBERSHIP with country AMBIGUITY. A string that matches a postcode
+ *       regex but exists in no gazetteer (a bare `27`, or a 5-digit house number that is not a real
+ *       code) gets confidence 0, so the parser treats it as a house number. A real-but-ambiguous
+ *       code (`75001` in FR and US) gets moderate confidence. A real, single-country code gets
+ *       1.0.
+ */
+import { candidateSystemsForPostcode } from "@mailwoman/codex";
+import { isGermanStreetToken } from "@mailwoman/codex/de";
+import { isFrenchStreetWord } from "@mailwoman/codex/fr";
+import { isStreetSuffixToken, isUsStateAbbreviation } from "@mailwoman/codex/us";
+import { collectMatches } from "./postcode-repair.js";
+/**
+ * Entropy cap for the confidence formula: a k-way country split saturates toward 0 confidence at
+ * k=10.
+ */
+const MAX_COUNTRIES = 10;
+/** A fuzzy (typo-corrected) match is less certain than an exact one — scale its confidence down. */
+const FUZZY_PENALTY = 0.6;
+/**
+ * Class-aware edit-distance-1 variants of a postcode string: deletions, same-class substitutions
+ * (digit↔digit, letter↔letter), same-class insertions, and adjacent transpositions. Restricting
+ * substitutions/insertions to the character's class mirrors how humans mistype or OCR a postcode (a
+ * digit becomes another digit, not a letter) and keeps the candidate set small.
+ */
+export function editDistance1Variants(s) {
+    const classOf = (ch) => /[0-9]/.test(ch) ? "0123456789" : /[A-Z]/.test(ch) ? "ABCDEFGHIJKLMNOPQRSTUVWXYZ" : "";
+    const variants = new Set();
+    for (let i = 0; i < s.length; i++)
+        variants.add(s.slice(0, i) + s.slice(i + 1)); // deletions
+    for (let i = 0; i < s.length; i++) {
+        for (const c of classOf(s[i]))
+            if (c !== s[i])
+                variants.add(s.slice(0, i) + c + s.slice(i + 1)); // substitutions
+    }
+    for (let i = 0; i <= s.length; i++) {
+        for (const c of classOf(s[i] ?? s[i - 1] ?? ""))
+            variants.add(s.slice(0, i) + c + s.slice(i)); // insertions
+    }
+    for (let i = 0; i + 1 < s.length; i++)
+        variants.add(s.slice(0, i) + s[i + 1] + s[i] + s.slice(i + 2)); // transpositions
+    variants.delete(s);
+    return [...variants];
+}
+/**
+ * Normalize a shaped span to the canonical gazetteer key: uppercase, collapse internal whitespace
+ * to a single space, and strip the German `D-` courtesy prefix (the shards store `68161`, not
+ * `D-68161`).
+ */
+export function normalizePostcode(raw) {
+    let s = raw.trim().toUpperCase().replace(/\s+/g, " ");
+    if (/^D-\d{5}$/.test(s))
+        s = s.slice(2); // German courtesy prefix: D-68161 → 68161
+    if (/^\d{4} [A-Z]{2}$/.test(s))
+        s = s.replace(" ", ""); // Dutch: gazetteer stores 1012LM, not 1012 LM
+    return s;
+}
+/**
+ * The GB outward code of a normalized unit postcode — the part before the space when the inward
+ * half is `\d[A-Z]{2}` (`SO4 3RX` → `SO4`). The GB gazetteer is aggregated to outward codes (2.7M
+ * units is too large + too fine for an anchor), so the extractor retries the outward code when a
+ * full GB unit misses. Returns `null` for any string that isn't a GB unit postcode (so it never
+ * fires elsewhere).
+ */
+export function gbOutwardCode(normalized) {
+    const sp = normalized.indexOf(" ");
+    if (sp < 1)
+        return null;
+    return /^\d[A-Z]{2}$/.test(normalized.slice(sp + 1)) ? normalized.slice(0, sp) : null;
+}
+/**
+ * `1 - log2(k)/log2(MAX_COUNTRIES)`, clamped to [0, 1]. k=1 → 1.0; k=2 → ~0.70; k≥MAX_COUNTRIES →
+ * 0.
+ */
+function confidenceFromCountryCount(k) {
+    if (k <= 0)
+        return 0;
+    if (k === 1)
+        return 1;
+    const c = 1 - Math.log2(k) / Math.log2(MAX_COUNTRIES);
+    return Math.max(0, Math.min(1, c));
+}
+/**
+ * Confidence scale for a digit-only code that shares its segment with a street word. A house number
+ * and a 5-digit postcode are the same shape, so membership alone can't separate `12345 Main St`
+ * (house number that happens to be a real ZIP elsewhere) from `San Francisco 94105` (postcode). The
+ * structural tell is cheap and locale-general: house numbers sit beside the street, postcodes
+ * beside the city. We scale rather than zero — the gazetteer still vouches for the shape, so a lone
+ * code in a street-only line stays usable; the penalty just lets a real trailing postcode out-rank
+ * it.
+ */
+const HOUSE_NUMBER_PENALTY = 0.2;
+/**
+ * Standalone street-type words for the locales without a codex slice yet (ES/IT). US comes from
+ * `@mailwoman/codex/us`, German from `@mailwoman/codex/de`, French from `@mailwoman/codex/fr`; the
+ * Dutch compound suffixes are still inline below pending a `codex/nl` slice.
+ */
+const NON_US_STREET_WORDS = new Set([
+    // Spanish
+    "calle",
+    "avenida",
+    "avda",
+    "plaza",
+    "paseo",
+    "camino",
+    "carrera",
+    "ronda",
+    // Italian
+    "via",
+    "viale",
+    "piazza",
+    "corso",
+    "largo",
+    "vicolo",
+    "strada",
+    "contrada",
+]);
+/** Dutch compound street suffixes — matched against a token's tail (pending a `codex/nl` slice). */
+const NL_STREET_SUFFIXES = ["straat", "laan", "plein", "gracht", "kade", "dijk", "steeg", "dreef"];
+/**
+ * True when a token denotes a street. US suffixes come from the USPS Pub-28 table in
+ * `@mailwoman/codex/us` (complete, so `Trl`/`Holw`/`Xing` all match), EXCEPT the abbreviations that
+ * collide with a state code — `KY` (Key vs Kentucky), `PR` (Prairie vs Puerto Rico) — which sit in
+ * the postcode's own `City, ST ZIP` segment. German compounds come from `@mailwoman/codex/de`
+ * ({@link isGermanStreetToken}), whose suffix set already excludes the place-name endings (`-berg`,
+ * `-burg`, `-dorf`) that would otherwise flag a city token. French voie words come from
+ * `@mailwoman/codex/fr` ({@link isFrenchStreetWord}). ES/IT and Dutch fall back to the inline
+ * lists.
+ *
+ * `systems` GATES which vocabularies are consulted — only the systems the postcode plausibly
+ * belongs to (its gazetteer membership, e.g. a US-only ZIP gates to `{us}` and never checks the
+ * German or French vocab). This is what lets the check scale to 15-20 systems without a
+ * cross-locale collision (German `-ring` vs English `spring`): an unrelated system's vocabulary is
+ * simply never asked. The gate carries lowercase system/locale tags (`us`, `de`, `fr`, `es`, `it`,
+ * `nl`).
+ */
+function looksLikeStreetWord(token, systems) {
+    const t = token.toLowerCase().replace(/[^\p{L}]/gu, "");
+    if (t.length < 2)
+        return false;
+    if (systems.has("us") && isStreetSuffixToken(t) && !isUsStateAbbreviation(t))
+        return true;
+    if (systems.has("de") && isGermanStreetToken(t))
+        return true;
+    if (systems.has("fr") && isFrenchStreetWord(t))
+        return true;
+    if ((systems.has("es") || systems.has("it")) && NON_US_STREET_WORDS.has(t))
+        return true;
+    if (systems.has("nl"))
+        return NL_STREET_SUFFIXES.some((s) => t.length > s.length && t.endsWith(s));
+    return false;
+}
+/**
+ * Position-aware confidence factor for a postcode span: `1` for anything that cannot be confused
+ * with a house number, and {@link HOUSE_NUMBER_PENALTY} for a digit-only code sharing its
+ * comma-delimited segment with a street word. This is the structural prior that lets the anchor
+ * tell a leading `12345 Main St` house number from a trailing `San Francisco 94105` postcode with
+ * no model in the loop — and lets a consumer pick the right span by confidence instead of by raw
+ * position.
+ *
+ * `systems` narrows the street vocabularies to the ones this code plausibly belongs to (its
+ * gazetteer membership, or — for a code in no gazetteer — the format-shape candidates from codex).
+ */
+function positionFactor(text, start, normalized, systems) {
+    if (!/^\d+$/.test(normalized))
+        return 1; // only digit-only codes collide with house numbers
+    const segStart = text.lastIndexOf(",", start - 1) + 1;
+    let segEnd = text.indexOf(",", start);
+    if (segEnd < 0)
+        segEnd = text.length;
+    for (const token of text.slice(segStart, segEnd).split(/\s+/)) {
+        if (looksLikeStreetWord(token, systems))
+            return HOUSE_NUMBER_PENALTY;
+    }
+    return 1;
+}
+/**
+ * Extract postcode anchors from raw text. For each postcode-shaped span, resolve it against the
+ * gazetteer and emit a soft anchor (country posterior + confidence). Spans that match a shape but
+ * exist in no gazetteer are still returned, with an empty posterior and confidence 0 — an explicit
+ * "looks like a postcode, but isn't one" so the caller can see the extractor fired and chose not to
+ * anchor.
+ */
+export function extractPostcodeAnchors(text, resolver, opts = {}) {
+    const anchors = [];
+    for (const match of collectMatches(text)) {
+        const spanText = text.slice(match.start, match.end);
+        const normalized = normalizePostcode(spanText);
+        // Exact first; then the GB outward fallback (structural, not a guess); then edit-distance-1.
+        let hits = resolver.lookup(normalized);
+        let matchType = hits.length > 0 ? "exact" : "none";
+        if (matchType === "none") {
+            const outward = gbOutwardCode(normalized);
+            if (outward) {
+                const outwardHits = resolver.lookup(outward);
+                if (outwardHits.length > 0) {
+                    hits = outwardHits;
+                    matchType = "outward";
+                }
+            }
+        }
+        if (matchType === "none" && opts.fuzzy) {
+            const fuzzyHits = [];
+            for (const variant of editDistance1Variants(normalized)) {
+                for (const h of resolver.lookup(variant))
+                    fuzzyHits.push(h);
+            }
+            if (fuzzyHits.length > 0) {
+                hits = fuzzyHits;
+                matchType = "fuzzy";
+            }
+        }
+        // Membership: distinct countries the postcode exists in (regardless of whether we have a centroid).
+        const countries = [...new Set(hits.map((h) => h.country))].sort();
+        const k = countries.length;
+        const posterior = {};
+        for (const c of countries)
+            posterior[c] = 1 / k;
+        // Placement: one representative coordinate-bearing hit per country (the first with real coords).
+        const candidates = [];
+        for (const c of countries) {
+            const placed = hits.find((h) => h.country === c && h.lat !== 0 && h.lon !== 0);
+            if (placed)
+                candidates.push(placed);
+        }
+        // Gate the street-word check to the systems this code plausibly belongs to: its gazetteer
+        // membership when known (precise — a US-only ZIP never checks the German vocab), else the
+        // format-shape candidates from codex (for a code in no gazetteer; its confidence is 0 anyway).
+        const systems = countries.length > 0
+            ? new Set(countries.map((c) => c.toLowerCase()))
+            : new Set(candidateSystemsForPostcode(normalized));
+        const position = positionFactor(text, match.start, normalized, systems);
+        const confidence = confidenceFromCountryCount(k) * (matchType === "fuzzy" ? FUZZY_PENALTY : 1) * position;
+        anchors.push({
+            span: { text: spanText, start: match.start, end: match.end },
+            normalized,
+            candidates,
+            posterior,
+            confidence,
+            matchType,
+            positionFactor: position,
+        });
+    }
+    return anchors;
+}
+//# sourceMappingURL=postcode-anchor.js.map

package/out/postcode-anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode-anchor.js","sourceRoot":"","sources":["../postcode-anchor.ts"],"names":[],"mappings":"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"}

package/out/postcode-binary-resolver.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Browser-side postcode resolver for the anchor (#240). A pure-JS, zero-dependency
+ *   `PostcodeResolver` backed by a compact flat binary instead of SQLite, so the postcode anchor
+ *   runs in the WASM/browser parser behind the same `lookup()` seam as the server-side
+ *   `WofPostcodeLookup`.
+ *
+ *   This file owns BOTH ends of the format — `serializePostcodeBinary` (run in Node by
+ *   `scripts/build-postcode-binary.ts`) and `PostcodeBinaryResolver` (run in the browser) — so the
+ *   layout can never drift between writer and reader.
+ *
+ *   Binary layout (little-endian): magic "PCB1" (4 bytes) u32 recordCount u8 countryCount, then
+ *   countryCount × 2 ASCII bytes (the country table) u8 keyWidth (max postcode length in bytes)
+ *   records recordCount × { key[keyWidth] ASCII right-padded with 0x00, u8 countryIdx, i16 latQ,
+ *   i16 lonQ }, sorted by key bytes ascending. A postcode present in two countries appears as two
+ *   adjacent records (same key, different countryIdx).
+ *
+ *   Coordinates are quantized to i16: latQ = round(lat/90 × 32767), lonQ = round(lon/180 × 32767),
+ *   giving ~300 m resolution — ample for a "which city/region" anchor. A record with latQ = lonQ =
+ *   0 means "known postcode, no centroid" (membership only), matching the SQLite resolver's
+ *   convention.
+ */
+import type { AnchorLookup } from "./anchor-inference.js";
+import type { PostcodePlace } from "./postcode-anchor.js";
+export interface PostcodeBinaryEntry {
+    postcode: string;
+    country: string;
+    lat: number;
+    lon: number;
+}
+/**
+ * Serialize postcode entries into the flat binary. Entries are sorted by (postcode, country) so
+ * equal postcodes land in adjacent records. Run in Node; consumed by
+ * {@link PostcodeBinaryResolver}.
+ */
+export declare function serializePostcodeBinary(entries: readonly PostcodeBinaryEntry[]): Uint8Array;
+/**
+ * Pure-JS, browser-safe postcode resolver over the flat binary. Implements the same `lookup()` seam
+ * as the SQLite `WofPostcodeLookup`, so `extractPostcodeAnchors` is agnostic to which backs it.
+ */
+export declare class PostcodeBinaryResolver {
+    #private;
+    constructor(bytes: Uint8Array);
+    lookup(postcode: string): PostcodePlace[];
+    /**
+     * Decode the whole binary into an {@link AnchorLookup} (`Map<postcode, AnchorEntry>`) for the
+     * neural anchor channel (#239/#240): each postcode → a uniform posterior over its member
+     * countries
+     *
+     * - The mean of its non-zero centroids. This is the browser-side equivalent of the pilot
+     *   postcode→anchor lookup the model trained against, built live from the shipped binary instead
+     *   of a precomputed JSON. Records are stored sorted by (postcode, country), so equal keys are
+     *   contiguous.
+     */
+    toAnchorLookup(): AnchorLookup;
+}
+//# sourceMappingURL=postcode-binary-resolver.d.ts.map

package/out/postcode-binary-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode-binary-resolver.d.ts","sourceRoot":"","sources":["../postcode-binary-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAOzD,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACX;AAUD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,GAAG,UAAU,CA2C3F;AAED;;;GAGG;AACH,qBAAa,sBAAsB;;gBAStB,KAAK,EAAE,UAAU;IA2B7B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE;IA2BzC;;;;;;;;;OASG;IACH,cAAc,IAAI,YAAY;CA+C9B"}