@mailwoman/corpus 10.0.0 → 10.2.0

package/out/subvenue/table.d.ts

@@ -0,0 +1,212 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * @file The sub-venue lexicon's record schema and the shipped vocabulary it is seeded from.
+ *
+ * The seeds mirror `neural/venue/structure.ts`. `@mailwoman/corpus` has no dependency on `@mailwoman/neural`,
+ * so this file declares the shipped vocabulary locally. `sub-venue-lexicon.test.ts` pins the seed values
+ * and fails when either copy changes.
+ */
+import type { SubVenuePromotion } from "#subvenue/promotions";
+/**
+ * This table's own data version.
+ *
+ * Bump when the source vintages or the build semantics change.
+ */
+export declare const SUBVENUE_LEXICON_VERSION = "0.2.0";
+/**
+ * Which side of the containment relation a designator names.
+ *
+ * It mirrors `@mailwoman/osm/sdk`'s `SubVenueTier`, re-declared for the same
+ * dependency-direction reason as the seed.
+ */
+export declare const LexiconTier: {
+    readonly SubVenue: "subvenue";
+    readonly Venue: "venue";
+};
+export type LexiconTier = (typeof LexiconTier)[keyof typeof LexiconTier];
+/**
+ * One designator record — a venue-interior (or containing-venue) structural noun.
+ */
+export interface SubVenueDesignator {
+    /**
+     * Canonical id, lowercase English.
+     *
+     * It matches `neural/venue/structure.ts`'s `VENUE_STRUCTURE_DESIGNATORS` wherever the two overlap.
+     */
+    id: string;
+    tier: LexiconTier;
+    /**
+     * Whether this designator may be preceded by a {@link SubVenueModifier} — the `North Terminal` shape;
+     * `gate` and `building` are excluded because `<modifier> <id>` is also an ordinary street
+     * name ("East Gate"), so admitting them turns a correct street parse into a sub-venue one.
+     */
+    modifierEligible: boolean;
+    /**
+     * Whether the shipped span proposer recognizes this designator; `false` means no consumer reads it yet.
+     */
+    shipped: boolean;
+    /**
+     * Where the term comes from, one entry per attesting source (`wof:placetype`, `osm:aeroway=terminal`,
+     * `wikidata:Q849706`, `overture:airport_terminal`), sorted so a regenerate is stable.
+     */
+    provenance: string[];
+}
+/**
+ * One positional modifier — the `North`/`Upper`/`Main` half of `North Terminal`.
+ */
+export interface SubVenueModifier {
+    id: string;
+    shipped: boolean;
+    provenance: string[];
+}
+/**
+ * One surface form stores a phrase.
+ *
+ * It records the corresponding entity and where the source attested it.
+ */
+export interface SubVenueSurface {
+    /**
+     * The phrase, lowercased for Latin script and left as written otherwise.
+     *
+     * The Turkish `İ` (U+0130) is `\p{Script=Latin}` and folds to `i` plus a combining dot above, so it
+     * round-trips through a form its own locale would not write (no shipped code depends on that today).
+     */
+    phrase: string;
+    recordID: string;
+    recordKind: "designator" | "modifier";
+    /**
+     * BCP-47-ish language subtag as the source wrote it (`en`, `ja`, `zh-Hant`, `pt-BR`),
+     * or `und` when the source gave an untagged default name.
+     */
+    lang: string;
+    /**
+     * ISO 3166-1 alpha-2 of the data the phrase was attested in, `""` for vocabulary
+     * sources that attest a term's existence rather than its use.
+     *
+     * This is the axis promotion is decided on (`hall` is attested 3,274 times in `GB`), never a global census.
+     */
+    region: string;
+    /**
+     * `wikidata:label`, `wikidata:alt`, `osm:name`, `osm:name:<lang>`, `overture:name`,
+     * `derived:head-noun`, or `seed`.
+     */
+    source: string;
+    /**
+     * Whether a human has approved this surface for parsing use in its region.
+     *
+     * Machine-derived entries start `false`; only a matching {@link SubVenuePromotion}
+     * flips it, so a consumer that gates a parse must filter on this.
+     */
+    curated: boolean;
+    /**
+     * How many source features attested this exact phrase when the source counts (OSM, Overture);
+     * Vocabulary sources attest phrase existence and use a count of `0`.
+     * OSM and Overture sources count occurrences.
+     */
+    observations: number;
+    /**
+     * The rule-assigned designator of the features that had this phrase, with a count each
+     * (`platform:3205 campus:49` for GB's `hall`); empty for vocabulary sources.
+     *
+     * Without it an `observations` count is a magnitude with no sign (`hall` on a `platform` row is a
+     * British bus stop called after a village hall. On a `terminal` row it is a real German departure hall).
+     */
+    context: Record<string, number>;
+}
+/**
+ * The measured shape of a designator's identifier half — what follows `Gate`/`Terminal` in real data.
+ *
+ * Derived from OSM `ref` values.
+ * Each of Berlin's 26 `aeroway=gate` features has a `ref` and no name.
+ *
+ * The extractor renders `Gate A12` from `<designator> <ref>`.
+ * Generation requires the identifier distribution.
+ */
+export interface IdentifierShape {
+    designatorID: string;
+    /**
+     * ISO 3166-1 alpha-2 of the extract this distribution was measured in.
+     *
+     * It is per-region because the shapes differ (GB gates are 70% bare digits, Japanese platform
+     * refs a different range), so a recipe for a French address should sample France's distribution.
+     */
+    region: string;
+    /**
+     * A coarse class: `digit` (`5`), `letter` (`B`), `letter-digit` (`A12`),
+     * `digit-letter` (`2F`), `range` (`16-18`, `0/1`), or `other`.
+     */
+    shape: string;
+    observations: number;
+    /**
+     * Up to eight real values, sorted.
+     */
+    examples: string[];
+}
+/**
+ * One input source's provenance, copied off its fetch manifest.
+ */
+export interface SubVenueLexiconSource {
+    id: string;
+    origin: string;
+    license: string;
+    retrieved: string;
+    rows: number;
+}
+/**
+ * The committed table.
+ */
+export interface SubVenueLexiconTable {
+    version: string;
+    sources: SubVenueLexiconSource[];
+    designators: SubVenueDesignator[];
+    modifiers: SubVenueModifier[];
+    surfaces: SubVenueSurface[];
+    identifierShapes: IdentifierShape[];
+    /**
+     * Every curation decision taken against this table, promotion and rejection,
+     * each with the census that backs it.
+     *
+     * A rejection is as required as a promotion because it stops the next reader
+     * re-proposing `hall` for en-GB.
+     */
+    promotions: SubVenuePromotion[];
+}
+/**
+ * The vocabulary that already ships in `neural/venue/structure.ts`, re-declared
+ * below for the module docstring's dependency-direction reason.
+ *
+ * `tier` is added here: the seven WOF placetypes plus `terminal`/`gate` are all venue-interior,
+ * while `campus` and `building` name a whole venue as often as a part of one
+ * but are marked `subvenue` because that is the role the span proposer uses them in.
+ */
+export declare const SHIPPED_DESIGNATOR_SEED: ReadonlyArray<{
+    id: string;
+    modifierEligible: boolean;
+    provenance: string[];
+}>;
+/**
+ * The shipped positional modifiers, re-declared from `neural/venue/structure.ts`'s `VENUE_STRUCTURE_MODIFIERS`.
+ */
+export declare const SHIPPED_MODIFIER_SEED: readonly string[];
+/**
+ * Designators the lexicon adds beyond what ships, each with the source that attests it.
+ *
+ * None is `modifierEligible` because that claim requires a confound board for each term and locale.
+ * A promotion marks a surface usable while preserving the modifier grammar.
+ */
+export declare const PROPOSED_DESIGNATORS: ReadonlyArray<{
+    id: string;
+    tier: LexiconTier;
+    provenance: string[];
+}>;
+/**
+ * `designatorID` → Wikidata QID, matching `fetch/wikidata-subvenue.ts`'s `SUBVENUE_CONCEPTS`.
+ *
+ * The builder remains a pure function over parsed input.
+ * The test compares both maps.
+ */
+export declare const CONCEPT_QIDS: Readonly<Record<string, string>>;
+//# sourceMappingURL=table.d.ts.map

package/out/subvenue/table.d.ts.map

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

package/out/subvenue/table.js

@@ -0,0 +1,94 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * @file The sub-venue lexicon's record schema and the shipped vocabulary it is seeded from.
+ *
+ * The seeds mirror `neural/venue/structure.ts`. `@mailwoman/corpus` has no dependency on `@mailwoman/neural`,
+ * so this file declares the shipped vocabulary locally. `sub-venue-lexicon.test.ts` pins the seed values
+ * and fails when either copy changes.
+ */
+/**
+ * This table's own data version.
+ *
+ * Bump when the source vintages or the build semantics change.
+ */
+export const SUBVENUE_LEXICON_VERSION = "0.2.0";
+/**
+ * Which side of the containment relation a designator names.
+ *
+ * It mirrors `@mailwoman/osm/sdk`'s `SubVenueTier`, re-declared for the same
+ * dependency-direction reason as the seed.
+ */
+export const LexiconTier = {
+    SubVenue: "subvenue",
+    Venue: "venue",
+};
+/**
+ * The vocabulary that already ships in `neural/venue/structure.ts`, re-declared
+ * below for the module docstring's dependency-direction reason.
+ *
+ * `tier` is added here: the seven WOF placetypes plus `terminal`/`gate` are all venue-interior,
+ * while `campus` and `building` name a whole venue as often as a part of one
+ * but are marked `subvenue` because that is the role the span proposer uses them in.
+ */
+export const SHIPPED_DESIGNATOR_SEED = [
+    { id: "arcade", modifierEligible: true, provenance: ["wof:placetype"] },
+    { id: "building", modifierEligible: false, provenance: ["wof:placetype"] },
+    { id: "campus", modifierEligible: true, provenance: ["wof:placetype"] },
+    { id: "concourse", modifierEligible: true, provenance: ["wof:placetype"] },
+    { id: "enclosure", modifierEligible: false, provenance: ["wof:placetype"] },
+    { id: "gate", modifierEligible: false, provenance: ["osm:aeroway=gate"] },
+    { id: "installation", modifierEligible: false, provenance: ["wof:placetype"] },
+    { id: "terminal", modifierEligible: true, provenance: ["osm:aeroway=terminal"] },
+    { id: "wing", modifierEligible: true, provenance: ["wof:placetype"] },
+];
+/**
+ * The shipped positional modifiers, re-declared from `neural/venue/structure.ts`'s `VENUE_STRUCTURE_MODIFIERS`.
+ */
+export const SHIPPED_MODIFIER_SEED = [
+    "central",
+    "east",
+    "front",
+    "inner",
+    "lower",
+    "main",
+    "north",
+    "outer",
+    "rear",
+    "south",
+    "upper",
+    "west",
+];
+/**
+ * Designators the lexicon adds beyond what ships, each with the source that attests it.
+ *
+ * None is `modifierEligible` because that claim requires a confound board for each term and locale.
+ * A promotion marks a surface usable while preserving the modifier grammar.
+ */
+export const PROPOSED_DESIGNATORS = [
+    { id: "airport", tier: LexiconTier.Venue, provenance: ["osm:aeroway=aerodrome"] },
+    { id: "hall", tier: LexiconTier.SubVenue, provenance: ["wikidata:Q240854"] },
+    { id: "pier", tier: LexiconTier.SubVenue, provenance: ["overture:pier"] },
+    { id: "platform", tier: LexiconTier.SubVenue, provenance: ["osm:public_transport=platform", "osm:railway=platform"] },
+    { id: "satellite", tier: LexiconTier.SubVenue, provenance: ["wikidata:Q15990706"] },
+    { id: "station", tier: LexiconTier.Venue, provenance: ["osm:railway=station"] },
+];
+/**
+ * `designatorID` → Wikidata QID, matching `fetch/wikidata-subvenue.ts`'s `SUBVENUE_CONCEPTS`.
+ *
+ * The builder remains a pure function over parsed input.
+ * The test compares both maps.
+ */
+export const CONCEPT_QIDS = {
+    terminal: "Q849706",
+    gate: "Q247739",
+    concourse: "Q862212",
+    campus: "Q209465",
+    building: "Q41176",
+    arcade: "Q186637",
+    hall: "Q240854",
+    satellite: "Q15990706",
+};
+//# sourceMappingURL=table.js.map

package/out/subvenue/table.js.map

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

package/out/surfaces/locale.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render real address tuples into locale-specific surface strings.
+ *
+ *   Public address registers supply inputs such as OA, HM Land Registry and CNIG.
+ *   LINZ-derived extracts also supply inputs. The module applies OpenCage templates to
+ *   choose ordering and punctuation by country.
+ *
+ *   Keep the emitted source ids stable: they are persisted in built corpora and referenced by
+ *   training configs. `recipes/sources.ts` records each one under its operation spelling
+ *   (`rendered-de`) and the `synth-*` spelling it retired on 2026-09-26.
+ */
+import type { CanonicalRow } from "#types";
+/**
+ * Real address tuple (for example one OpenAddresses row).
+ *
+ * Street and locality are required.
+ * Other tuple fields are optional.
+ */
+export interface LocaleBaseTuple {
+    house_number?: string;
+    street: string;
+    locality: string;
+    /**
+     * Sub-locality below locality (for example suburb/district).
+     * When present, it is rendered between street and locality.
+     */
+    dependent_locality?: string;
+    region?: string;
+    postcode?: string;
+}
+/**
+ * @deprecated Alias — use LocaleBaseTuple.
+ */
+export type GermanBaseTuple = LocaleBaseTuple;
+export interface RenderedLocaleRow {
+    raw: string;
+    components: CanonicalRow["components"];
+    locale: string;
+}
+/**
+ * @deprecated Alias — use RenderedLocaleRow.
+ */
+export type RenderedGermanRow = RenderedLocaleRow;
+export interface LocaleRenderOpts {
+    random?: () => number;
+    /**
+     * The order used to render the same components.
+     *
+     * `"native"` (default) uses the country's own template (DE → house-after-street, postcode-before-city).
+     * `"international"` renders house-first and postcode-after-city.
+     */
+    order?: "native" | "international";
+    /**
+     * Postcode surface shape.
+     *
+     * `"conventional"` (default) canonicalizes to the country's rendered form
+     * (NL: OA's glued `1011AB` → the spaced `1011 AB`).
+     * `"as-source"` keeps the source's own surface.
+     *
+     * Today, only NL differs between these modes.
+     */
+    postcodeShape?: "conventional" | "as-source";
+    /**
+     * How the native-order render joins street and house number.
+     *
+     * The OpenCage ES template comma-joins (`Calle Mayor, 12`, the official Spanish convention).
+     * OA-derived feeds and our ES eval space-join (`calle mayor 12`, the observed form on all 3,000 eval rows).
+     *
+     * `"template"` (default) keeps the template's own join.
+     * `"space"` collapses `<street>, <house_number>` → `<street> <house_number>` after rendering.
+     * International order ignores this.
+     */
+    nativeHouseJoin?: "template" | "space";
+    /**
+     * The string between rendered address lines.
+     *
+     * `", "` (default) is the template's own join.
+     * `" "` renders the comma-free single-line register for dictation or a copy out of a
+     * one-field form, as in `Neusser Str. 12 Nippes 50733 Köln` for the same components.
+     *
+     * Only native order uses this option.
+     */
+    separator?: ", " | " ";
+}
+/**
+ * @deprecated Alias — use LocaleRenderOpts.
+ */
+export type GermanRenderOpts = LocaleRenderOpts;
+/**
+ * Render one tuple into a locale-ordered `{raw, components}` row via OpenCage templates,
+ * with light variation (house number and postcode may be dropped).
+ *
+ * Returns `null` when the tuple is too thin or a component would not align cleanly.
+ *
+ * Region handling depends on order:
+ * - native omits region for alignment reliability
+ * - international includes region in the tail
+ *
+ * Pass `opts.order: "international"` to render the same components house-first and postcode-after-city
+ * instead (see {@link LocaleRenderOpts.order}), matching common feed-style layouts.
+ */
+export declare function renderLocaleRow(base: LocaleBaseTuple, country: string, opts?: LocaleRenderOpts): RenderedLocaleRow | null;
+/**
+ * German wrapper over {@link renderLocaleRow}.
+ *
+ * Kept for the `german` recipe (`de/recipes/locale.ts`) and tests.
+ */
+export declare function renderGermanRow(base: LocaleBaseTuple, opts?: LocaleRenderOpts): RenderedLocaleRow | null;
+//# sourceMappingURL=locale.d.ts.map

package/out/surfaces/locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../lib/surfaces/locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAK1C;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,eAAe,CAAA;AAE7C,MAAM,WAAW,iBAAiB;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,CAAA;IACtC,MAAM,EAAE,MAAM,CAAA;CACd;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,CAAA;AAEjD,MAAM,WAAW,gBAAgB;IAChC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAA;IACrB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,eAAe,CAAA;IAClC;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,cAAc,GAAG,WAAW,CAAA;IAC5C;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,UAAU,GAAG,OAAO,CAAA;IACtC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,IAAI,GAAG,GAAG,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,CAAA;AAmD/C;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC9B,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,gBAAqB,GACzB,iBAAiB,GAAG,IAAI,CAmE1B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,GAAE,gBAAqB,GAAG,iBAAiB,GAAG,IAAI,CAE5G"}

package/out/surfaces/locale.js

@@ -0,0 +1,138 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render real address tuples into locale-specific surface strings.
+ *
+ *   Public address registers supply inputs such as OA, HM Land Registry and CNIG.
+ *   LINZ-derived extracts also supply inputs. The module applies OpenCage templates to
+ *   choose ordering and punctuation by country.
+ *
+ *   Keep the emitted source ids stable: they are persisted in built corpora and referenced by
+ *   training configs. `recipes/sources.ts` records each one under its operation spelling
+ *   (`rendered-de`) and the `synth-*` spelling it retired on 2026-09-26.
+ */
+import { formatAddress } from "@mailwoman/codex/address/format";
+/**
+ * ISO-3166 alpha-2 → BCP-47 tag for the emitted rows (primary language per country).
+ */
+const LOCALE_TAG = {
+    DE: "de-DE",
+    ES: "es-ES",
+    IT: "it-IT",
+    NL: "nl-NL",
+    GB: "en-GB",
+    FR: "fr-FR",
+    US: "en-US",
+    NZ: "en-NZ",
+};
+/**
+ * Canonicalize a postcode to the form the country's template renders,
+ * so the stored component aligns verbatim against `raw`.
+ *
+ * NL is the main case: OA may store `1011AB`, while the NL template emits `1011 AB`.
+ * Other countries pass through unchanged.
+ */
+function normalizePostcode(postcode, country) {
+    // country-branch: the NL postcode is the one whose source spells it without the space the layout writes.
+    // The codex postal regimes' canonical spacing per country would replace this.
+    if (country === "NL") {
+        const m = /^(\d{4})\s*([A-Za-z]{2})$/.exec(postcode);
+        if (m)
+            return `${m[1]} ${m[2].toUpperCase()}`;
+    }
+    return postcode;
+}
+/**
+ * True when `value` appears verbatim and as a standalone token.
+ */
+function tokenPresent(raw, value) {
+    if (!raw.includes(value))
+        return false;
+    // Reject numeric substring collisions (for example house "2" inside postcode "12623").
+    const i = raw.indexOf(value);
+    const before = raw[i - 1];
+    const after = raw[i + value.length];
+    const isDigit = (c) => c !== undefined && c >= "0" && c <= "9";
+    if (/^\d+$/.test(value) && (isDigit(before) || isDigit(after)))
+        return false;
+    return true;
+}
+/**
+ * Render one tuple into a locale-ordered `{raw, components}` row via OpenCage templates,
+ * with light variation (house number and postcode may be dropped).
+ *
+ * Returns `null` when the tuple is too thin or a component would not align cleanly.
+ *
+ * Region handling depends on order:
+ * - native omits region for alignment reliability
+ * - international includes region in the tail
+ *
+ * Pass `opts.order: "international"` to render the same components house-first and postcode-after-city
+ * instead (see {@link LocaleRenderOpts.order}), matching common feed-style layouts.
+ */
+export function renderLocaleRow(base, country, opts = {}) {
+    const random = opts.random ?? Math.random;
+    const order = opts.order ?? "native";
+    if (!base.street || !base.locality)
+        return null;
+    const components = { street: base.street, locality: base.locality };
+    // Sub-locality is part of the address body in both orders.
+    // If the template does not surface it verbatim, the row is dropped below.
+    if (base.dependent_locality) {
+        components.dependent_locality = base.dependent_locality;
+    }
+    // The sampler keeps the house number in about 80% of rows.
+    // The remaining rows use street-only forms.
+    if (base.house_number && random() < 0.8) {
+        components.house_number = base.house_number;
+    }
+    // ~85% keep postcode.
+    // Canonicalization uses the country's rendered form.
+    // `postcodeShape: "as-source"` is applied after rendering.
+    if (base.postcode && random() < 0.85) {
+        components.postcode = normalizePostcode(base.postcode, country);
+    }
+    // International order places region in the tail.
+    // Native order omits it for alignment.
+    if (order === "international" && base.region) {
+        components.region = base.region;
+    }
+    // Native order uses the country's template.
+    // International order uses the US template.
+    // No random draw here, keeping RNG sequence stable.
+    const renderCountry = order === "international" ? "US" : country;
+    const separator = order === "native" ? (opts.separator ?? ", ") : ", ";
+    let raw = formatAddress(components, renderCountry, { separator });
+    if (!raw)
+        return null;
+    // Optional native-order rewrite: `<street>, <hn>` -> `<street> <hn>`.
+    if (order === "native" && separator === ", " && opts.nativeHouseJoin === "space" && components.house_number) {
+        raw = raw.replace(`${components.street}, ${components.house_number}`, `${components.street} ${components.house_number}`);
+    }
+    // `postcodeShape: "as-source"`: rewrite both raw and component to source form.
+    // Done post-render because templates may normalize the postcode.
+    if (opts.postcodeShape === "as-source" && components.postcode && base.postcode) {
+        const sourceForm = base.postcode.trim();
+        if (sourceForm && sourceForm !== components.postcode && raw.includes(components.postcode)) {
+            raw = raw.replace(components.postcode, sourceForm);
+            components.postcode = sourceForm;
+        }
+    }
+    // The row is dropped if any component is absent from the rendered address.
+    for (const value of Object.values(components)) {
+        if (!value || !tokenPresent(raw, value))
+            return null;
+    }
+    return { raw, components, locale: LOCALE_TAG[country] ?? country.toLowerCase() };
+}
+/**
+ * German wrapper over {@link renderLocaleRow}.
+ *
+ * Kept for the `german` recipe (`de/recipes/locale.ts`) and tests.
+ */
+export function renderGermanRow(base, opts = {}) {
+    return renderLocaleRow(base, "DE", opts);
+}
+//# sourceMappingURL=locale.js.map

package/out/surfaces/locale.js.map

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

package/out/synthesizers/anchor-absorption.d.ts

@@ -3,48 +3,41 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Anchor-absorption counter-augmentation (#220/#723, Probe A1). Teaches the model the CONTEXT-
- *   DEPENDENT leading-5-digit disambiguation that the killed #723 override was faking, AND that the
- *   `anchor_paint_mode=shaped` WHERE fix alone over-corrected on (Probe A0: it flipped the default
- *   to house_number, recovering CASE-H but ERODING CASE-P — postcode F1 99.3→86.5 on
- *   leading-postcode rows like "05764 Finel Hollow Road, VT").
- *
- *   THE DISCRIMINATOR the model must learn (from the CASE-H vs CASE-P contrast, NOT a flipped
- *   default):
- *
- *   - A leading 5-digit WITH a trailing postcode + street context → it is the HOUSE NUMBER (CASE-H)
- *   - A leading 5-digit with NO trailing postcode (US-rural / DE) → it IS the POSTCODE (CASE-P) Both
- *       leading tokens are real ZIPs (so the painted anchor fires on both); only the surrounding
- *       context separates them. The model attends to the trailing token to decide the leading one.
- *
- *   Slice mix (the A0 learning sets a HEAVY CASE-P floor so the default doesn't flip — DeepSeek's
- *   ≥35% CASE-P; here CASE-P total = 35%): H-adversarial 30% US street, leading real-ZIP house# +
- *   TRAILING postcode → house_number P-us-rural 20% US rural, leading postcode, NO trailing →
- *   postcode (the A0-erosion fix) P-de 15% German leading postcode "{pc} {city}, {street} {hn}" →
- *   postcode anchor-fp 10% leading 5-digit that is NOT a real ZIP + trailing postcode →
- *   house_number locale-ambig 15% minimal context; the local token (street-type vs none) decides
- *   standard 10% normal small house# + trailing postcode → house_number (baseline)
- *
- *   Real ZIPs for the leading-5-digit are sampled from the postcode anchor lookup at build time
- *   (passed via opts.realZips) so the shaped anchor fires on them exactly as at inference; fake
- *   ZIPs (anchor-fp) are 5-digit strings deliberately absent from the lookup.
+ *   Generates address pairs in which context decides whether a leading five-digit token is a house number or a postcode.
  */
 import type { ComponentTag } from "@mailwoman/codex/component";
+/**
+ * A US locality, region and postcode used as an address tail.
+ */
 export interface AnchorAbsorptionBaseTuple {
     locality: string;
     region: string;
     postcode: string;
 }
+/**
+ * The row templates.
+ *
+ * Names that start with `h-` produce a house number and names that start with `p-` a postcode.
+ */
 export type AnchorAbsorptionTemplate = "h-adversarial" | "h-no-trailing-locality" | "p-us-rural" | "p-de" | "anchor-fp" | "locale-ambig" | "standard";
+/**
+ * Options for {@link synthesizeAnchorAbsorptionRow}.
+ */
 export interface AnchorAbsorptionSynthesisOpts {
     random?: () => number;
     forceTemplate?: AnchorAbsorptionTemplate;
     /**
-     * Real US ZIPs (in the anchor lookup) to use as the LEADING 5-digit house number — so the painted anchor fires on it,
-     * the CASE-H/anchor-fp trigger. Builder loads these from pilot-anchor-lookup.json.
+     * Real US ZIP codes from the postcode-anchor lookup.
+     *
+     * The templates place them where the anchor fires on a token that is really a house number.
+     *
+     * @defaultValue the postcodes of the built-in US tuples.
      */
     realZips?: ReadonlyArray<string>;
 }
+/**
+ * One synthesized row with its template.
+ */
 export interface SynthesizedAnchorAbsorptionRow {
     raw: string;
     components: Partial<Record<ComponentTag, string>>;
@@ -52,12 +45,11 @@ export interface SynthesizedAnchorAbsorptionRow {
     template: AnchorAbsorptionTemplate;
 }
 /**
- * Build one anchor-absorption counter-augmentation row.
+ * Builds one row from a sampled or forced template.
  */
 export declare function synthesizeAnchorAbsorptionRow(opts?: AnchorAbsorptionSynthesisOpts): SynthesizedAnchorAbsorptionRow;
 /**
- * Every anchor-absorption template, in one list for the slice runner to sample from. Each covers a way a venue or
- * landmark name can swallow the street token that follows it.
+ * The template sampling pool, in which each template's repeat count is its weight.
  */
 export declare const ALL_TEMPLATES: ReadonlyArray<AnchorAbsorptionTemplate>;
 //# sourceMappingURL=anchor-absorption.d.ts.map