@mailwoman/corpus 10.0.0 → 10.2.0

package/out/cz/recipes/pcfirst-preposition.js

@@ -3,27 +3,26 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `cz-pcfirst-preposition` — the Czech pc-first prepositional-locality slice, fourth orthography
- *   of the #901 leading-name-boundary family. The #897 close-out read all 8 residual CZ rows as one
- *   class: a LEADING postcode mis-assigned as house_number while the multi-word "nad/pod/u X"
- *   locality shatters ("51244 Rokytnice nad Jizerou, Dolní Rokytnice 111" → street
- *   'RokytnicenadJizerou' + house_number '51244'). That leading-5-digit confusion is the
- *   anchor-pollution class whose decode-time OVERRIDE was correctly killed in #723 — this slice is
- *   the model-first fix as DATA: real prepositional localities in the order that breaks, so the
- *   model learns that a leading postcode before a multi-word name is a postcode. pc-first leads the
- *   cycle (the lesson); canonical and city-first keep the polarity balanced (the v1.9.9 lesson).
+ * `cz-pcfirst-preposition`: the Czech pc-first prepositional-locality recipe.
+ *
+ * A leading postcode is mis-assigned as a house number while a multi-word "nad/pod/u X" locality
+ * shatters. This recipe supplies real prepositional localities in the order that breaks, so the
+ * model learns that a leading postcode before a multi-word name is a postcode. pc-first leads the
+ * cycle and the canonical and city-first orders keep the polarity balanced.
  */
 import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils";
-import { alignAndWrite, readTuples, sliceSourceID } from "#recipes/scaffold";
+import { alignAndWrite, readTuples, requireRegister, recipeSourceID } from "#recipes/scaffold";
+import { defaultRecipeSource } from "#recipes/sources";
+import { SurfaceOrigin } from "#types";
 /**
- * The order-cycle slot for the STREET-LESS form (`«city» «pc», Česko`) — the exact surface of the
- * `cz-full-praha-100-00` board row, whose absence from the street-bearing orders was the v4.5.0 no-promote's measured
- * gap.
+ * The order-cycle slot for the street-less form (`«city» «pc», Česko`).
+ *
+ * This is the surface of the `cz-full-praha-100-00` board row.
+ * The street-containing orders do not cover it.
  */
 const STREETLESS_ORDER = 3;
 /**
- * Slice recipe registered with the corpus builder — see the file header for the parse behaviour it exists to exercise,
- * and `description` below for the surface form it generates.
+ * Recipe registered with the corpus builder.
  */
 export const czPcFirstPrepositionRecipe = {
     name: "cz-pcfirst-preposition",
@@ -34,6 +33,10 @@ export const czPcFirstPrepositionRecipe = {
         let read = 0;
         let emitted = 0;
         let skipped = 0;
+        const CZ_PCFIRST_PROVENANCE = {
+            register: requireRegister(opts, "cz-pcfirst-preposition"),
+            surface: SurfaceOrigin.Composed,
+        };
         for await (const t of readTuples(opts.input)) {
             read++;
             const street = String(t.street ?? "").trim();
@@ -45,10 +48,10 @@ export const czPcFirstPrepositionRecipe = {
                 continue;
             }
             const order = read % 4;
-            // The OFFICIAL Czech rendering spaces the PSČ as `NNN NN` ('512 44'); OpenAddresses stores it
-            // unspaced ('51244'), and a model trained only on the source form reads the spaced surface as
-            // house_number + garbage (the 'Praha 100 00' mangle). Alternate the two renderings so both
-            // orthographies are attested — the LABEL is the postcode either way.
+            // The official Czech rendering spaces the PSČ as `NNN NN` ('512 44')
+            // while OpenAddresses stores it unspaced ('51244').
+            // Alternate the two renderings so both orthographies are attested.
+            // Label the postcode in either form.
             const spaced = read % 2 === 0 && /^\d{5}$/.test(postcode);
             const postcodeSurface = spaced ? `${postcode.slice(0, 3)} ${postcode.slice(3)}` : postcode;
             let raw;
@@ -65,14 +68,14 @@ export const czPcFirstPrepositionRecipe = {
                 raw = `${city}, ${postcodeSurface}, ${street} ${number}`;
             }
             else {
-                // order === STREETLESS_ORDER: the street-less form — `«city» «pc», Česko` — the exact surface of the
-                // cz-full-praha-100-00 board row. The v4.5.0 no-promote receipt measured the gap: every
-                // prior order was street-bearing, so the model never saw a spaced PSČ beside a bare
-                // locality and mangled 'Praha 100 00, Czechia' into house_number spans. Street/number
-                // stay OUT of the components for this form (they are not in the surface).
+                // The street-less form `«city» «pc», Česko` omits street and number from the
+                // components because the surface does not include them.
                 raw = `${city} ${postcodeSurface}, Česko`;
             }
-            const source_id = sliceSourceID("synth-cz-pcfirst-preposition", {
+            // One resolution for both, because `source_id` includes the source as its prefix
+            // and a pair that disagreed would name a source no row of this output declares.
+            const source = defaultRecipeSource("synth-cz-pcfirst-preposition");
+            const source_id = recipeSourceID(source, {
                 ...components,
                 o: String(order),
                 s: spaced ? "1" : "0",
@@ -83,12 +86,18 @@ export const czPcFirstPrepositionRecipe = {
                 components,
                 country: "CZ",
                 locale: "cs-CZ",
-                source: "synth-cz-pcfirst-preposition",
+                source,
                 source_id,
                 corpus_version: "0.10.0",
                 license: "Synthetic — cz-pcfirst-preposition; (street, number, postcode, city) from OpenAddresses CZ (per-source attribution in the model card)",
             };
-            if (alignAndWrite(write, canonical, "cz-pcfirst-preposition")) {
+            // Per row, because the id names this tuple's record.
+            // A tuples file written before `sourceID` existed has none.
+            // `null` means the recipe had no id to forward.
+            if (alignAndWrite(write, canonical, "cz-pcfirst-preposition", {
+                ...CZ_PCFIRST_PROVENANCE,
+                baseSourceID: t.sourceID ?? null,
+            })) {
                 emitted++;
             }
             else {

package/out/cz/recipes/pcfirst-preposition.js.map

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

package/out/cz/tools/fetch/cuzk.d.ts

@@ -0,0 +1,281 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Harvest ČÚZK's INSPIRE Addresses archives into the directory `#cz/adapters/cuzk/adapter` reads.
+ *
+ * ČÚZK serves the Addresses (AD) theme as a two-level ATOM service rather than as a WFS. The
+ * service document at `https://atom.cuzk.gov.cz/AD/AD.xml` holds one entry per municipality, each
+ * pointing at a dataset feed, and each dataset feed offers that municipality's addresses as a
+ * zipped GML in two projections. Measured 2026-10-02: the service document answered HTTP 200 with
+ * 8,373,817 bytes holding 6,258 entries, sha256
+ * `9b1d51a721ab601fa74307cce5ce20f74d12dd29512f87be29cd1072f0a2d83b`.
+ *
+ * The acquisition belongs under a `tools/` root. `@mailwoman/corpus` is one of the
+ * `TOOLING_PACKAGES` in `dependency-cruiser.config.mjs`, which keep their tooling under `lib/`, so
+ * this module sits beside `#fr/tools/fetch/ban` rather than in an `sdk/` root the workspace does
+ * not declare.
+ *
+ * Every one of the service document's `rights` elements reads `žádné podmínky neplatí`, INSPIRE's
+ * controlled value for no conditions applying to access and use, and the address-source register
+ * elects it on that basis. `#cz/adapters/cuzk/adapter` records the same value on every row.
+ *
+ * Four properties of this service decide the harvest's shape, and each was measured rather than
+ * assumed:
+ *
+ * 1. **The service document states each municipality's file modification time.** An entry's
+ *    `<updated>` equals the archive's `Last-Modified` to the second, checked on six municipalities
+ *    on 2026-10-02 — `584061` reads `2026-06-04T02:19:33+02:00` against
+ *    `Thu, 04 Jun 2026 00:19:33 GMT`, and `531529`, `551481`, `545031`, `587044` and `584282`
+ *    agree the same way. So one 8.4 MB request states the freshness of all 6,258 archives, and a
+ *    re-run requests only the municipalities whose stated time moved. The alternative — a
+ *    conditional request per municipality — costs 6,258 round trips to learn the same thing.
+ * 2. **The download URL is composed from a base the feed itself declares.** The service document's
+ *    own `rel="next"` links are `https://services.cuzk.gov.cz/gml/inspire/ad/epsg-4258` and
+ *    `…/epsg-5514`, and a dataset feed's `alternate` link for the same municipality is that base
+ *    plus `/<code>.zip`. The harvest composes from the declared base instead of reading 6,258
+ *    dataset feeds. That halves its requests. {@linkcode HarvestCzCuzkOptions.resolveThroughDatasetFeed}
+ *    reads the publisher's own href instead, for a run that will not compose a URL.
+ * 3. **The `type` attribute describes the data rather than the file.** A dataset feed's link
+ *    advertises `application/gml+xml` while the host serves `application/zip`, so the GML is inside
+ *    the archive and the advertised type cannot decide what to write. The archive is stored as it
+ *    arrives: the adapter opens it with `adm-zip`, because at least one archive's central directory
+ *    records its member's size as the ZIP64 sentinel `0xFFFFFFFF`.
+ * 4. **A dataset feed's `length` is accurate here, and is still not used.** `584061.zip` claims
+ *    24,846 bytes and the host's `content-length` reports 24,846. Denmark's feed understates its file
+ *    by 23 times, so every byte count this module records is counted off the delivered body.
+ *
+ * The archives are small — a systematic sample of 50 of the 6,258 municipalities on 2026-10-02 ran
+ * from 5,236 to 1,642,586 bytes with a median of 16,591 — so the harvest is bound by round trips
+ * rather than by bandwidth, and it is dispatched serially through one `APIClient`. ČÚZK publishes
+ * no rate limit. {@linkcode CZ_CUZK_REQUEST_INTERVAL_MS} holds the harvest to four requests per
+ * second against one government host. A caller that has asked ČÚZK for more raises it.
+ */
+import { APIClient } from "@mailwoman/core/api";
+import { type PathBuilderLike } from "path-ts";
+import type { AtomFeed } from "#tools/fetch/atom";
+import type { BaseFetchOptions, FetchSummary, SourceCollectionManifest, SourceManifest } from "#tools/fetch/download";
+/**
+ * The ATOM service document listing one dataset feed per municipality.
+ */
+export declare const CZ_CUZK_SERVICE_FEED_URL = "https://atom.cuzk.gov.cz/AD/AD.xml";
+/**
+ * The attribution the model card must state for this source.
+ */
+export declare const CZ_CUZK_ATTRIBUTION = "\u010Cesk\u00FD \u00FA\u0159ad zem\u011Bm\u011B\u0159ick\u00FD a katastr\u00E1ln\u00ED (\u010C\u00DAZK), INSPIRE t\u00E9ma Adresy";
+/**
+ * The two projections the service offers, keyed by the path segment the feed's own base URL ends in.
+ *
+ * The adapter reads either.
+ * `epsg-4258` is ETRS89, in degrees, and is the projection the adapter's
+ * component joins were verified against.
+ */
+export declare const CZ_CUZK_PROJECTIONS: {
+    readonly "epsg-4258": "ETRS89";
+    readonly "epsg-5514": "S-JTSK";
+};
+/**
+ * One of {@linkcode CZ_CUZK_PROJECTIONS}.
+ */
+export type CzCuzkProjection = keyof typeof CZ_CUZK_PROJECTIONS;
+/**
+ * The minimum spacing between two requests to `services.cuzk.gov.cz`, in milliseconds.
+ *
+ * Four requests per second.
+ * A systematic sample of 50 archives on 2026-10-02 answered a serial `HEAD` in 100 ms each,
+ * so this leaves the host more than half the rate it demonstrated.
+ */
+export declare const CZ_CUZK_REQUEST_INTERVAL_MS = 250;
+/**
+ * One municipality's dataset, as the service document states it.
+ */
+export interface CzMunicipalityDataset {
+    /**
+     * The municipality code.
+     *
+     * It is both the `obec` code and the archive's file name stem.
+     */
+    code: string;
+    /**
+     * The entry's title, `INSPIRE - adresní místa - obec: Unkovice [584061]`.
+     */
+    title: string;
+    /**
+     * The `<updated>` the service document states.
+     * This value is the archive's modification time.
+     */
+    updated: string;
+    /**
+     * The dataset feed for this municipality.
+     * It lists the same data in both projections.
+     */
+    datasetFeedURL: string;
+    /**
+     * The archive, composed from the base the feed declares for the requested projection.
+     */
+    downloadURL: string;
+    /**
+     * The file name the archive is written under.
+     * The adapter globs for this name.
+     */
+    filename: string;
+}
+/**
+ * The municipality code of one entry, read from its INSPIRE identifier and checked against its title.
+ *
+ * Both spellings are read because the code is the file name the archive is composed
+ * and stored under, so a disagreement between the publisher's two statements of it
+ * would silently store one municipality's addresses under another's name.
+ *
+ * @throws When either statement is missing or the two disagree.
+ * That reads as a change in the publisher's layout rather than as a municipality without a code.
+ */
+export declare function municipalityCodeOf(entry: {
+    title: string;
+    identifierCode: string | null;
+}): string;
+/**
+ * The base URL the feed declares for one projection.
+ *
+ * Matched on the href's last path segment rather than on the link's `title`,
+ * because the segment is the EPSG code itself while the title is a Czech-language label.
+ *
+ * @throws When the feed declares no base for the requested projection, naming the ones it does
+ * declare, so a publisher that moves its files reports itself instead of composing a dead URL.
+ */
+export declare function projectionBaseURL(feed: AtomFeed, projection: CzCuzkProjection): string;
+/**
+ * The municipalities the service document lists, with the archive URL for one projection.
+ *
+ * @throws When the feed lists no entry, when two entries claim one municipality code,
+ * or when an entry states no dataset feed link.
+ * A repeated code would make one archive overwrite the other.
+ */
+export declare function readCzCuzkServiceFeed(feed: AtomFeed, projection: CzCuzkProjection): readonly CzMunicipalityDataset[];
+/**
+ * The archive link a dataset feed states for one projection.
+ *
+ * Read only when {@linkcode HarvestCzCuzkOptions.resolveThroughDatasetFeed} is set.
+ * The feed holds one entry per projection, each with one `alternate` link, and the projection is
+ * identified by the href's own path segment for the same reason {@linkcode projectionBaseURL} uses it.
+ *
+ * @throws When the dataset feed states no link for the requested projection.
+ */
+export declare function datasetFeedArchiveURL(feed: AtomFeed, projection: CzCuzkProjection, context: string): string;
+/**
+ * One archive, as the harvest's manifest records it.
+ *
+ * {@linkcode SourceManifest}'s five fields plus what a re-run needs: the modification time
+ * the service document stated for this municipality, and the one the host served it under.
+ */
+export interface CzCuzkArchiveEntry extends SourceManifest {
+    municipality_code: string;
+    /**
+     * The `<updated>` the service document stated when this archive was fetched.
+     *
+     * A later run that reads the same value for this municipality does not fetch the archive.
+     * This is the field that makes the harvest resumable without a request per municipality.
+     */
+    feed_updated: string;
+    /**
+     * The `Last-Modified` the host served the archive under, or `null` where it served none.
+     *
+     * Recorded rather than compared: {@linkcode CzCuzkArchiveEntry.feed_updated}
+     * answers the same question without a request.
+     */
+    last_modified: string | null;
+}
+/**
+ * The harvest's `MANIFEST.json`.
+ */
+export interface CzCuzkHarvestManifest extends SourceCollectionManifest {
+    /**
+     * The projection the archives in this directory are in.
+     *
+     * Recorded because the two projections share a file name, so a directory holding
+     * both would be read by the adapter as two copies of every address.
+     */
+    projection: CzCuzkProjection;
+    /**
+     * How many municipalities the service document listed when this manifest was written.
+     *
+     * The denominator for `files`, read from the feed on each run rather than fixed here.
+     */
+    municipalities_listed: number;
+    files: CzCuzkArchiveEntry[];
+}
+export interface HarvestCzCuzkOptions {
+    /**
+     * Where the archives and the manifest are written.
+     * This is the adapter's `inputPath`.
+     */
+    outputDir: PathBuilderLike;
+    /**
+     * Which projection to harvest.
+     *
+     * @defaultValue `epsg-4258`
+     */
+    projection?: CzCuzkProjection;
+    /**
+     * Harvest only these municipality codes, for a probe or to repair specific municipalities.
+     *
+     * A code the service document does not list is reported as a failure rather than ignored.
+     */
+    municipalities?: readonly string[];
+    /**
+     * Stop after this many municipalities, counting the ones already on disk.
+     *
+     * A bounded run rather than all 6,258.
+     */
+    limit?: number;
+    /**
+     * Take each archive's URL from its own dataset feed instead of composing it
+     * from the base the service document declares.
+     *
+     * Costs one extra request per municipality and asks the publisher rather than composing.
+     */
+    resolveThroughDatasetFeed?: boolean;
+    /**
+     * Re-read the sha256 of every archive already on disk instead of comparing its byte count.
+     *
+     * The default compares the recorded byte count against the file's size.
+     * That check takes one `stat`.
+     *
+     * This option re-hashes and reads every archive in the directory.
+     */
+    verifyDigests?: boolean;
+    signal?: AbortSignal;
+    report?: (line: string) => void;
+}
+/**
+ * Harvest the municipalities the service document lists into `options.outputDir`.
+ *
+ * The client is injected so the harvest is testable without the network and so a caller
+ * decides the pacing. {@linkcode fetchCzCuzk} is the registry entry point and supplies both.
+ *
+ * @returns What was fetched, what was already current, and which municipality codes failed.
+ */
+export declare function harvestCzCuzk(client: Pick<APIClient, "fetch">, options: HarvestCzCuzkOptions): Promise<FetchSummary>;
+export interface FetchCzCuzkOptions extends BaseFetchOptions, Pick<HarvestCzCuzkOptions, "projection" | "municipalities" | "limit" | "resolveThroughDatasetFeed" | "verifyDigests" | "signal"> {
+    /**
+     * The minimum spacing between two requests, in milliseconds.
+     *
+     * @defaultValue {@linkcode CZ_CUZK_REQUEST_INTERVAL_MS}
+     */
+    minRequestIntervalMs?: number;
+}
+/**
+ * Harvest ČÚZK's INSPIRE Addresses archives into `<outRoot>/cz-cuzk/`.
+ *
+ * Re-runnable: a municipality whose recorded modification time still matches the service
+ * document's and whose archive is still on disk at the recorded length costs no request.
+ *
+ * A full harvest is 6,259 requests — the service document plus one per municipality —
+ * and an estimated 396 MB, from a mean of 63,337 bytes over a systematic sample
+ * of 50 of the 6,258 archives on 2026-10-02.
+ * The sample ran from 5,236 to 1,642,586 bytes, so the total is an estimate from
+ * 50 measurements rather than a measurement of all 6,258.
+ */
+export declare function fetchCzCuzk(options: FetchCzCuzkOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=cuzk.d.ts.map

package/out/cz/tools/fetch/cuzk.d.ts.map

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