@mailwoman/corpus 9.4.0 → 10.1.0

package/lib/parquet/writers.ts

@@ -0,0 +1,451 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Writes Parquet files and the manifest that describes their contents.
+ *
+ *   This module exposes two writers. {@linkcode writeParquetFile} writes one file from rows already in memory.
+ *   {@linkcode writeParquetSplits} streams per-split row iterables into as many files as the row cap requires. It
+ *   returns the manifest. Both writers create their parent directory, as `@mailwoman/core/fs` writers do
+ *   encode rather than repeat at each call site.
+ *
+ *   Layout under `<outputDir>`:
+ *
+ *   ```
+ *   corpus-v<version>/
+ *     manifest.json
+ *     train/
+ *       part-0000.parquet
+ *       part-0001.parquet
+ *     val/
+ *       part-0000.parquet
+ *     test/
+ *       part-0000.parquet
+ *   ```
+ *
+ *   Each file caps at `rowsPerFile` (default 1,000,000). Within a file DuckDB writes a row group every
+ *   {@linkcode ROW_GROUP_SIZE} rows. The manifest captures every file's path, row count, byte size and SHA-256, the
+ *   digest computed by re-reading the file once after close — cheap against the cost of writing it.
+ *
+ *   A part is closed by its row count and never by a source boundary, so one part may hold the tail of one source and
+ *   the head of the next. A reader must therefore take a file's sources from all of its rows.
+ */
+
+import { pathExists, readLocalJSONFile, tryStat } from "@mailwoman/core/fs/readers"
+import { openWriteStream, type WriteStream } from "@mailwoman/core/fs/streams"
+import { temporaryDirectory } from "@mailwoman/core/fs/temporary"
+import { makeDirectories, writeLocalBuffer, writeLocalJSONFile } from "@mailwoman/core/fs/writers"
+import { sha256File } from "@mailwoman/core/hash"
+import { stringifyJSON } from "@mailwoman/core/json"
+import { once } from "@mailwoman/core/utils/events"
+import { Field, Int32, List, Table as ArrowTable, tableToIPC, Utf8, vectorFromArray } from "apache-arrow"
+import { Compression, Table as WasmTable, WriterPropertiesBuilder, writeParquet } from "parquet-wasm"
+import { type PathBuilderLike, resolvePathBuilder } from "path-ts"
+
+import { corpusDirectoryName } from "#directory"
+import { escapeSQLIdentifier, escapeSQLString, openDuckDB } from "#parquet/duckdb"
+import {
+	PARQUET_COLUMN_TYPES,
+	PARQUET_COLUMNS,
+	PARQUET_COMPRESSION,
+	type ParquetRow,
+	ROW_GROUP_SIZE,
+	rowToParquet,
+	ROWS_PER_FILE,
+} from "#parquet/schema"
+import type { LabeledRow } from "#types"
+import type { SplitName } from "#utils/split"
+
+const stringListType = new List(new Field("item", new Utf8(), true))
+const int32ListType = new List(new Field("item", new Int32(), true))
+
+function parquetTable(rows: readonly ParquetRow[]) {
+	return new ArrowTable({
+		raw: vectorFromArray(
+			rows.map((row) => row.raw),
+			new Utf8()
+		),
+		tokens: vectorFromArray(
+			rows.map((row) => row.tokens),
+			stringListType
+		),
+		labels: vectorFromArray(
+			rows.map((row) => row.labels),
+			stringListType
+		),
+		span_starts: vectorFromArray(
+			rows.map((row) => row.span_starts),
+			int32ListType
+		),
+		span_ends: vectorFromArray(
+			rows.map((row) => row.span_ends),
+			int32ListType
+		),
+		span_tags: vectorFromArray(
+			rows.map((row) => row.span_tags),
+			stringListType
+		),
+		country: vectorFromArray(
+			rows.map((row) => row.country),
+			new Utf8()
+		),
+		locale: vectorFromArray(
+			rows.map((row) => row.locale ?? null),
+			new Utf8()
+		),
+		source: vectorFromArray(
+			rows.map((row) => row.source),
+			new Utf8()
+		),
+		source_id: vectorFromArray(
+			rows.map((row) => row.source_id),
+			new Utf8()
+		),
+		corpus_version: vectorFromArray(
+			rows.map((row) => row.corpus_version),
+			new Utf8()
+		),
+		license: vectorFromArray(
+			rows.map((row) => row.license),
+			new Utf8()
+		),
+		register: vectorFromArray(
+			rows.map((row) => row.register ?? null),
+			new Utf8()
+		),
+		surface: vectorFromArray(
+			rows.map((row) => row.surface),
+			new Utf8()
+		),
+		recipe: vectorFromArray(
+			rows.map((row) => row.recipe ?? null),
+			new Utf8()
+		),
+		base_source_id: vectorFromArray(
+			rows.map((row) => row.base_source_id ?? null),
+			new Utf8()
+		),
+	})
+}
+
+/**
+ * Write one parquet file from rows held in memory.
+ */
+export async function writeParquetFile(rows: readonly ParquetRow[], path: PathBuilderLike): Promise<void> {
+	const arrow = parquetTable(rows)
+	const wasmTable = WasmTable.fromIPCStream(tableToIPC(arrow, "stream"))
+
+	const properties = new WriterPropertiesBuilder()
+		.setCompression(Compression.SNAPPY)
+		.setCreatedBy("mailwoman")
+		.setMaxRowGroupSize(ROW_GROUP_SIZE)
+		.build()
+
+	// parquet-wasm serializes key-value metadata through a hash map.
+	// Its order can change between writes.
+	// File identity and provenance live in manifest.json, so omitting file
+	// metadata preserves deterministic bytes.
+	await writeLocalBuffer(writeParquet(wasmTable, properties), path)
+}
+
+/**
+ * Per-file metadata captured in `manifest.json`, one entry per `.parquet` file of a split.
+ *
+ * The `slices` key it sits under is the wire interface the Python loader reads
+ * (`manifest_files` in `corpus_files.py`, with its pre-rename fallback); every corpus
+ * on disk includes it, so the key name is not the writer's to change.
+ */
+export interface ParquetFileDescriptor {
+	split: SplitName
+	path: string
+	format: "parquet"
+	compression: typeof PARQUET_COMPRESSION
+	rows: number
+	bytes: number
+	sha256: string
+	first_source_id: string
+	last_source_id: string
+	/**
+	 * The file's corpus source slug, when the writer knows it.
+	 *
+	 * `audit.ts` prefers this over inferring the source from `first_source_id`'s prefix;
+	 * {@linkcode writeParquetSplits} itself writes multi-source files and leaves it unset.
+	 */
+	source?: string
+}
+
+export interface ParquetManifest {
+	corpus_version: string
+	schema: readonly string[]
+	rows_per_slice: number
+	row_group_size: number
+	slices: ParquetFileDescriptor[]
+	counts: Record<SplitName, number>
+	total_rows: number
+}
+
+export interface WriteParquetSplitsOptions {
+	/**
+	 * Root output directory.
+	 *
+	 * The corpus version directory is created beneath it.
+	 */
+	outputDir: PathBuilderLike
+
+	/**
+	 * Corpus version stamped onto rows and into the output directory name.
+	 */
+	corpusVersion: string
+
+	/**
+	 * Max rows per `.parquet` file.
+	 *
+	 * Default 1,000,000.
+	 */
+	rowsPerFile?: number
+
+	/**
+	 * Continue from the files `<corpusDir>/MANIFEST.json` already records.
+	 *
+	 * The manifest is rewritten after each finished file.
+	 * A descriptor is appended only after its `.parquet` file closes, so each recorded file is complete.
+	 *
+	 * A resumed run rereads each descriptor's size.
+	 * It discards that many rows from the front of each split's iterable and opens the next file index.
+	 *
+	 * The caller therefore has to supply the same iterables in the same order.
+	 * For `buildCorpus` that means the same labeled files and the same shuffle seed.
+	 */
+	resume?: boolean
+}
+
+/**
+ * Pre-partitioned labeled-row streams, one per split.
+ *
+ * Callers (`buildCorpus`) decide each row's split inline at align time via `splitForRow`
+ * and route rows to the matching stream.
+ * Splits with no rows can be omitted or passed as an empty iterable.
+ * {@linkcode writeParquetSplits} skips them.
+ */
+export type PerSplitRows = Partial<Record<SplitName, AsyncIterable<LabeledRow>>>
+
+async function writeStagedParquet(stagePath: string, outputPath: string): Promise<void> {
+	using db = await openDuckDB()
+	const columns = [...PARQUET_COLUMNS]
+
+	const columnsLiteral =
+		"{" + columns.map((column) => `'${column}': '${PARQUET_COLUMN_TYPES[column]}'`).join(", ") + "}"
+
+	const selectList = columns.map(escapeSQLIdentifier).join(", ")
+
+	await db.run("SET preserve_insertion_order=true")
+
+	await db.run(
+		`COPY (SELECT ${selectList} FROM read_json('${escapeSQLString(stagePath)}', ` +
+			`columns = ${columnsLiteral}, format = 'newline_delimited')) ` +
+			`TO '${escapeSQLString(outputPath)}' (FORMAT PARQUET, COMPRESSION SNAPPY, ROW_GROUP_SIZE ${ROW_GROUP_SIZE})`
+	)
+}
+
+async function writeStagedRow(stage: WriteStream, row: ParquetRow): Promise<void> {
+	if (!stage.write(stringifyJSON(row) + "\n")) {
+		await once(stage, "drain")
+	}
+}
+
+/**
+ * Streams labeled rows into `.parquet` files, with one set per split.
+ * It writes the manifest that describes them.
+ *
+ * Splits are processed sequentially so only one file is open at a time.
+ * Rows are staged to newline-delimited JSON with backpressure, then DuckDB
+ * writes the Parquet file from disk.
+ */
+export async function writeParquetSplits(
+	perSplit: PerSplitRows,
+	opts: WriteParquetSplitsOptions
+): Promise<ParquetManifest> {
+	const rowsPerFile = opts.rowsPerFile ?? ROWS_PER_FILE
+	const corpusDir = resolvePathBuilder(opts.outputDir, corpusDirectoryName(opts.corpusVersion))
+	await makeDirectories(corpusDir)
+
+	const manifestPath = corpusDir("MANIFEST.json")
+	const files: ParquetFileDescriptor[] = opts.resume ? await readFinishedParquetFiles(manifestPath) : []
+
+	/**
+	 * The manifest as the finished files describe it.
+	 *
+	 * `counts` and `total_rows` are summed from the descriptors rather than from a running row counter,
+	 * so a manifest written between two files never claims the rows of the file being written.
+	 */
+	const manifestNow = (): ParquetManifest => {
+		const counts: Record<SplitName, number> = { train: 0, val: 0, test: 0 }
+		let totalRows = 0
+
+		for (const file of files) {
+			counts[file.split] += file.rows
+			totalRows += file.rows
+		}
+
+		return {
+			corpus_version: opts.corpusVersion,
+			schema: PARQUET_COLUMNS,
+			rows_per_slice: rowsPerFile,
+			row_group_size: ROW_GROUP_SIZE,
+			slices: files.toSorted((a, b) =>
+				a.split === b.split ? a.path.localeCompare(b.path) : a.split.localeCompare(b.split)
+			),
+			counts,
+			total_rows: totalRows,
+		}
+	}
+
+	for (const split of ["train", "val", "test"] as const) {
+		const rows = perSplit[split]
+
+		if (!rows) continue
+
+		await using staging = await temporaryDirectory(`mailwoman-parquet-${split}-`)
+
+		const finished = files.filter((file) => file.split === split)
+
+		// The rows of this split already in `.parquet` files.
+		// A resumed run reads the same iterable from its start, so these rows arrive again
+		// and are discarded rather than written twice.
+		let skipRows = finished.reduce((total, file) => total + file.rows, 0)
+
+		let fileIndex = finished.length
+		let path = ""
+		let stagePath = ""
+		let fileRows = 0
+		let stage: WriteStream | null = null
+		let firstSourceID = ""
+		let lastSourceID = ""
+
+		const openFile = async (): Promise<void> => {
+			const splitDir = corpusDir(split)
+			await makeDirectories(splitDir)
+			// A string, because the manifest records it.
+			path = splitDir(`part-${String(fileIndex).padStart(4, "0")}.parquet`).toString()
+
+			// A string, because DuckDB reads it inside SQL text.
+			stagePath = staging.path(`part-${String(fileIndex).padStart(4, "0")}.ndjson`).toString()
+			stage = staging.use(openWriteStream(stagePath))
+			fileRows = 0
+			firstSourceID = ""
+			lastSourceID = ""
+		}
+
+		const closeFile = async (): Promise<void> => {
+			const activeStage = stage
+
+			if (!activeStage) return
+
+			await new Promise<void>((resolve, reject) => {
+				activeStage.end((error?: Error | null) => (error ? reject(error) : resolve()))
+			})
+
+			if (fileRows) {
+				await writeStagedParquet(stagePath, path)
+
+				const fileStat = await tryStat(path)
+				const sha256 = await sha256File(path)
+
+				files.push({
+					split,
+					path,
+					format: "parquet",
+					compression: PARQUET_COMPRESSION,
+					rows: fileRows,
+					bytes: fileStat?.size ?? 0,
+					sha256,
+					first_source_id: firstSourceID,
+					last_source_id: lastSourceID,
+				})
+
+				// Written per file rather than once at the end, so an interrupted build resumes
+				// at the next file index instead of rewriting every split.
+				// About 700 small writes over a full build.
+				await writeLocalJSONFile(manifestNow(), manifestPath)
+			}
+
+			stage = null
+			fileRows = 0
+		}
+
+		for await (const row of rows) {
+			if (skipRows > 0) {
+				skipRows--
+
+				continue
+			}
+
+			if (!path) {
+				await openFile()
+			}
+
+			const pq = rowToParquet(row)
+
+			if (!stage) throw new Error("Parquet file writer was not opened")
+			await writeStagedRow(stage, pq)
+
+			fileRows++
+
+			if (fileRows === 1) {
+				firstSourceID = row.source_id
+			}
+
+			lastSourceID = row.source_id
+
+			if (fileRows >= rowsPerFile) {
+				await closeFile()
+
+				fileIndex++
+				path = ""
+			}
+		}
+
+		await closeFile()
+	}
+
+	const manifest = manifestNow()
+
+	await writeLocalJSONFile(manifest, manifestPath)
+
+	return manifest
+}
+
+/**
+ * The finished `.parquet` files an earlier run recorded, each verified against its file on disk.
+ *
+ * @throws When a recorded file is missing or its size differs from the descriptor.
+ * The writer creates a descriptor only after closing the file.
+ * Either case therefore means the file changed after its run.
+ * The writer would produce a corpus whose manifest describes bytes the files
+ * no longer contain if it continued.
+ */
+async function readFinishedParquetFiles(manifestPath: PathBuilderLike): Promise<ParquetFileDescriptor[]> {
+	if (!(await pathExists(manifestPath))) return []
+
+	const manifest = await readLocalJSONFile<ParquetManifest>(manifestPath)
+
+	for (const file of manifest.slices) {
+		const stat = await tryStat(file.path)
+
+		if (!stat) {
+			throw new Error(
+				`resume refused: ${manifestPath.toString()} records ${file.path} and no file sits at that path. ` +
+					`Delete the manifest to write every parquet file again.`
+			)
+		}
+
+		if (stat.size !== file.bytes) {
+			throw new Error(
+				`resume refused: ${file.path} is ${stat.size.toLocaleString()} bytes and ` +
+					`${manifestPath.toString()} records ${file.bytes.toLocaleString()}.`
+			)
+		}
+	}
+
+	return [...manifest.slices]
+}

package/lib/pl/adapters/emuia/adapter.ts

@@ -0,0 +1,202 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * `emuia`: Poland's INSPIRE Addresses (AD) theme, published by Główny Urząd Geodezji i Kartografii out
+ * of the Państwowy Rejestr Granic.
+ *
+ * Input is GML, because the service serves four GML flavors and no JSON. Its capabilities document
+ * advertises no `outputFormat` values at all and a `GetFeature` returns
+ * `application/gml+xml; version=3.2`. A page is a `wfs:FeatureCollection` of `ms:AD.Address` members,
+ * and the adapter reads it with `streamMarkupElements` from `@mailwoman/core/html/elements`, which
+ * yields one member subtree at a time, so neither a page nor a whole extract sits in memory.
+ *
+ * The payload is the Polish register's own schema rather than the harmonized INSPIRE model: a member's
+ * element names are the register's columns and every address value is inline, so there is no
+ * `ad:ThoroughfareName` to join to and no `xlink:href` to resolve. Read with that same function over
+ * 500 members across ten windows spread through the service, a member carries 21 children and never a
+ * twenty-second: `gml:boundedBy`, `ms:msGeometry` and nineteen columns, which are `ms:id`,
+ * `ms:gml_id`, `ms:lokalnyid`, `ms:jednostkaadmnistracyjna`, `ms:miejscowosc`,
+ * `ms:miejscowosc_lower`, `ms:czescmiejscowosci`, `ms:ulica`, `ms:ulica_pol`, `ms:ulica_skr`,
+ * `ms:numer`, `ms:kod`, `ms:teryt`, `ms:simc`, `ms:ulic`, `ms:status`, `ms:data_od`, `ms:wazny_od`
+ * and `ms:adres`. The adapter reads `ulica` as the street, `numer` as the house number, `kod` as the
+ * postcode and `miejscowosc` as the locality, with `czescmiejscowosci` as the part of the locality
+ * where the publisher populates it. Every column is written on every member, and three carry a value
+ * on every one of the 500: `numer`, `kod` and `miejscowosc`. Two are written and populated on none:
+ * `status` and `czescmiejscowosci`.
+ *
+ * A row with no street is the ordinary rural case rather than a defect. Over those 500 members 299
+ * carry a street and 201 leave `ms:ulica` written and empty, and the publisher's own `ms:adres` writes
+ * the streetless form as locality and number: `Księżyki 5`, `Jawor 19`. The adapter emits those rows
+ * with a locality and a number and no street, which is the address Poland delivers to.
+ *
+ * `ms:jednostkaadmnistracyjna` carries the administrative path as a PostgreSQL array literal,
+ * `{Polska,łódzkie,"Piotrków Trybunalski","Piotrków Trybunalski"}`, whose second element is the
+ * voivodeship. It is left unread: a Polish postal address does not carry the voivodeship, the codex
+ * layout for `PL` leaves a `region` component unplaced, and parsing a quoted array literal to reach a
+ * value the layout leaves unplaced would cost a parse and reach no rendered component.
+ *
+ * The service states no count of its own. `resultType=hits` answers `numberMatched="1000"`, which is
+ * MapServer's default feature cap rather than a count — it stays 1000 when asked with `count=2000` and
+ * when asked at `startIndex=1` — and a feature page answers `numberMatched="unknown"`. The size is a
+ * property of the service on the day it is asked, so this file states no count. The acquisition
+ * step reads it by paging, with `countWFSFeaturesByPaging` from `@mailwoman/core/api`.
+ *
+ * GUGiK's dataset record states one condition of use, in `otherConstraints`: `Brak warunków dostępu i
+ * użytkowania`, no conditions for access and use. The address-source register elected that and names
+ * no license instrument, so no SPDX identifier exists and the publisher's own words are the label the
+ * adapter stamps on every row. Crediting GUGiK stays good practice and the statement requires it
+ * nowhere.
+ *
+ * The adapter honors `opts.limit` and `opts.signal`. `opts.country` is optional and accepts only `PL`.
+ */
+
+import { formatAddressRow } from "@mailwoman/codex/address/format"
+import { openReadStream } from "@mailwoman/core/fs/streams"
+import { streamMarkupElements, textAtPath, type MarkupElement } from "@mailwoman/core/html/elements"
+
+import { UnsupportedCountryError } from "#adapters/errors"
+import { stableSourceID } from "#adapters/source-id"
+import { SourceRegister } from "#registers"
+import { AddressRole, type AdapterOptions, type CanonicalRow, type CorpusAdapter, SurfaceOrigin } from "#types"
+
+/**
+ * Registry id for this adapter.
+ *
+ * Stamped into every row it emits, so a corpus record can be traced back to the dataset it came from.
+ * The name is the municipal register the feature ids point at: a `ms:gml_id`
+ * reads `PL.ZIPIN.3742.EMUiA_9945001100000172050`.
+ */
+export const EMUIA_ADAPTER_ID = "emuia"
+
+/**
+ * The one jurisdiction this adapter emits.
+ */
+export const EMUIA_COUNTRIES: readonly string[] = ["PL"]
+
+/**
+ * The terms the address-source register elected for this publisher.
+ *
+ * `unchecked-access-free-pl-g-wny-urz-d-geodezji-i-kartografii` is elected with no `spdx`
+ * and no `termsVersion`, so `electedTerms` is the whole of what the publisher stated
+ * and `electedLicenseLabel` returns exactly this string.
+ * Czechia's row is recorded the same way.
+ */
+export const EMUIA_DEFAULT_LICENSE = "Brak warunków dostępu i użytkowania"
+
+/**
+ * The feature element MapServer writes, spelled as the document spells it.
+ *
+ * The prefix is the service's own, `ms:`, rather than `ad:`.
+ * A reader comparing the part after the colon against `Address` finds no address
+ * type here, because the local name is `AD.Address`.
+ */
+const ADDRESS_ELEMENT = "ms:AD.Address"
+
+/**
+ * A member's column value, trimmed, or an empty string.
+ *
+ * `textAtPath` answers an empty string for an element the publisher wrote
+ * and left blank and `undefined` for one it omitted.
+ * Both are an absent value for this adapter's purposes, and all 500 members measured carried
+ * every one of the nineteen columns, so the distinction carries no information on this service.
+ */
+function column(feature: MarkupElement, name: string): string {
+	return (textAtPath(feature, `ms:${name}`) ?? "").trim()
+}
+
+export function createEMUiAAdapter(): CorpusAdapter {
+	return {
+		id: EMUIA_ADAPTER_ID,
+		defaultLicense: EMUIA_DEFAULT_LICENSE,
+		addressRole: AddressRole.Premise,
+		register: SourceRegister.PolandEMUiA,
+		surface: SurfaceOrigin.Rendered,
+		description:
+			"Poland's INSPIRE Addresses theme (GUGiK): house-number-level addresses from the municipal EMUiA registers.",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && !EMUIA_COUNTRIES.includes(opts.country)) {
+				throw new UnsupportedCountryError(EMUIA_ADAPTER_ID, EMUIA_COUNTRIES, opts.country)
+			}
+
+			const stream = openReadStream(opts.inputPath)
+
+			let emitted = 0
+
+			try {
+				for await (const feature of streamMarkupElements(stream, ADDRESS_ELEMENT, {
+					xml: true,
+					signal: opts.signal,
+				})) {
+					if (opts.signal?.aborted) break
+
+					if (opts.limit !== undefined && emitted >= opts.limit) break
+
+					const street = column(feature, "ulica")
+					const house = column(feature, "numer")
+					const postcode = column(feature, "kod")
+					const locality = column(feature, "miejscowosc")
+					const partOfLocality = column(feature, "czescmiejscowosci")
+
+					if (!locality) continue
+
+					if (!house && !street) continue
+
+					const components: CanonicalRow["components"] = {}
+
+					if (house) {
+						components.house_number = house
+					}
+
+					if (street) {
+						components.street = street
+					}
+
+					if (partOfLocality && partOfLocality !== locality) {
+						components.dependent_locality = partOfLocality
+					}
+
+					if (postcode) {
+						components.postcode = postcode
+					}
+
+					components.locality = locality
+
+					const rendered = formatAddressRow(components, "PL", { singleLine: true })
+
+					if (!rendered) continue
+
+					const { raw, components: aligned } = rendered
+
+					// `ms:gml_id` names the upstream municipal register and its record, which is
+					// the identifier worth keeping; `ms:id` is this service's own row number.
+					const seed = column(feature, "gml_id") || column(feature, "id")
+
+					const sourceID = seed ? `${EMUIA_ADAPTER_ID}-${seed}` : stableSourceID(EMUIA_ADAPTER_ID, aligned)
+
+					yield {
+						raw,
+						components: aligned,
+						country: "PL",
+						locale: "pl-PL",
+						source: EMUIA_ADAPTER_ID,
+						source_id: sourceID,
+						corpus_version: "",
+						license: EMUIA_DEFAULT_LICENSE,
+					}
+
+					emitted++
+				}
+			} finally {
+				stream.destroy()
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const emuiaAdapter = createEMUiAAdapter()