@mailwoman/corpus 10.0.0 → 10.1.0

package/lib/kr/adapters/juso/label-rows.ts

@@ -3,25 +3,12 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The Korean road-name address register (주소DB) as the LABEL source: a streaming reader over the monthly zip
- *   `fetchJusoKR` downloads (#2204 §1).
- *
- *   The archive holds four pipe-delimited CP949 text files per 시도 plus one nationwide road-code file, laid out as the
- *   guide inside the zip states (붙임1, the 전체분 layout):
- *
- *       개선_도로명코드_전체분.txt   도로명코드|도로명|도로명로마자|읍면동일련번호|시도명|…|읍면동구분|…
- *       주소_<시도>.txt              관리번호|도로명코드|읍면동일련번호|지하여부|건물본번|건물부번|기초구역번호|…
- *       지번_<시도>.txt              관리번호|일련번호|법정동코드|시도명|시군구명|법정읍면동명|법정리명|산여부|…
- *       부가정보_<시도>.txt          관리번호|행정동코드|행정동명|우편번호|…|건축물대장건물명|시군구건물명|공동주택여부
- *
- *   A LABEL row is one 주소 record joined to its road code (the admin ladder and the road name), its representative lot
- *   (대표여부 = 1: the 법정동, the 리, and the lot number the 지번 form writes) and its supplement (the postcode — the
- *   기초구역번호 on the 주소 row IS the five-digit postcode — and the building name). The row-count note in the zip
- *   gives 6,424,089 addresses and 8,194,643 lots for the 2026-08-31 edition.
- *
- *   MEMBER NAMES ARE CP949 WITHOUT THE UTF-8 FLAG, so a zip reader that trusts the format's CP437 default finds
- *   `┴╓╝╥_╝¡┐ïÆ╣▌╗π.txt` and matches nothing; `filenameEncoding` decodes the central directory's real bytes. The
- *   contents need the same treatment one layer down, which is what `decodeByteStream` does before the line split.
+ * The Korean road-name address register (주소DB) used as alignment ground truth. The ministry assigns
+ * the road names and building numbers it publishes, so the register asserts `address` on `premise`
+ * rows where the permit registry's address field is an `observation`. The archive is four
+ * pipe-delimited CP949 text files per 시도 plus one nationwide road-code file, as the guide inside the
+ * zip states (붙임1, the 전체분 layout), and both its member names and its contents need the publisher's
+ * encoding.
  */
 
 import { decodeByteStream } from "@mailwoman/core/fs/streams"
@@ -30,10 +17,8 @@ import type { PathBuilderLike } from "path-ts"
 import { TextSpliterator } from "spliterator"
 
 /**
- * The publisher's encoding, for both the member names and their contents.
- *
- * `cp949`, not `euc-kr`: the register uses the UHC extension, and Node's WHATWG `euc-kr` reads none of it. One row in
- * 48,000 carries such a sequence and decodes to a different string with no error raised — see `decodeByteStream`.
+ * The publisher's encoding; `cp949` rather than `euc-kr`, because the register's UHC extension appears
+ * in about one row in 48,000 and Node's whatwg `euc-kr` decodes it to a different string with no error.
  */
 const ENCODING = "cp949"
 
@@ -58,10 +43,8 @@ const LOT = { id: 0, dong: 5, ri: 6, mountain: 7, main: 8, sub: 9, primary: 10 }
 const SUP = { id: 0, postcode: 3, buildingRegister: 6, buildingLocal: 7, apartment: 8 } as const
 
 /**
- * Joins 도로명코드 to 읍면동일련번호, written as an escape so no NUL byte enters the source.
- *
- * Neither part has a fixed width, so a printable separator that could occur in either would let two different pairs
- * produce one key. No code contains NUL.
+ * Joins 도로명코드 to 읍면동일련번호 with a NUL no code contains, since neither part has a fixed width
+ * and a printable separator could let two different pairs produce one key.
  */
 const CODE_SEPARATOR = "\0"
 
@@ -73,8 +56,8 @@ function roadCodeKey(code: string, serial: string): string {
 }
 
 /**
- * The 2026 edition writes the merged 전남광주통합특별시 where every older source — the permit registry, Who's On First — still
- * writes 전라남도 and 광주광역시. A typed string in either form aligns against the register through this map.
+ * The 2026 edition merged 전남광주통합특별시 while older sources still write 전라남도 and 광주광역시,
+ * so a typed string in either form aligns against the register through this map.
  */
 export const REGION_ALIASES: Readonly<Record<string, string>> = {
 	전라남도: "전남광주통합특별시",
@@ -90,8 +73,9 @@ export interface JusoLabelRow {
 	region: string
 	sigungu: string
 	/**
-	 * The 읍/면 the road address itself carries between the 시군구 and the road (읍면동구분 `0`), else empty: a 동 is never written
-	 * in the road form, it goes in the parenthetical.
+	 * The 읍/면 included in the road address between the 시군구 and the road (읍면동구분 `0`), else empty.
+	 *
+	 * A 동 is never written in the road form, it goes in the parenthetical.
 	 */
 	eupmyeon: string
 	dong: string
@@ -112,10 +96,9 @@ export function parenthetical(row: JusoLabelRow): string {
 }
 
 /**
- * Every full-edition member of one kind, as `[region suffix, archive name]`, sorted by region.
+ * Every full-edition member of one kind as `[region suffix, archive name]`, sorted by region.
  *
- * The monthly edition also ships 변동 (change-only) files under the same prefixes; those carry a different row set and
- * are excluded by name.
+ * The monthly edition's 변동 (change-only) files under the same prefixes are excluded by name.
  */
 export function regionMembers(names: readonly string[], prefix: string): Array<[string, string]> {
 	return names
@@ -131,15 +114,13 @@ async function* fields(archivePath: PathBuilderLike, member: string): AsyncGener
 	const bytes = readZipEntry(archivePath, member, { filenameEncoding: ENCODING })
 
 	for await (const line of TextSpliterator.fromAsync(decodeByteStream(bytes, ENCODING))) {
-		yield line.replace(/\r$/u, "").split("|")
+		yield line.split("|")
 	}
 }
 
 /**
- * The road-code table, keyed by {@link roadCodeKey}: the admin ladder, the road name and the 읍면동구분.
- *
- * Held whole because every region's addresses join against it. A composite string key rather than a nested map: the
- * pair is read once per address row and a single lookup is what that path can afford.
+ * The road-code table keyed by {@link roadCodeKey}, held whole because every region's
+ * addresses join against it and read as one composite string key rather than a nested map.
  */
 async function loadRoadCodes(archivePath: PathBuilderLike, member: string): Promise<Map<string, string[]>> {
 	const codes = new Map<string, string[]>()
@@ -171,16 +152,15 @@ function joinNumber(main: string, sub: string): string {
 
 export interface ReadJusoOptions {
 	/**
-	 * Stop after this many rows per 시도. For a fixture or a smoke run; omit for the whole register.
+	 * Stop after this many rows per 시도, for a fixture or a smoke run.
+	 * Omit for the whole register.
 	 */
 	maxRowsPerRegion?: number
 }
 
 /**
- * Stream every LABEL row, region by region.
- *
- * The lot and supplement files of one 시도 are held while its address file streams, so the join never holds the country
- * at once — the largest region's two side files, not 6.4 million addresses.
+ * Stream every label row region by region, holding one 시도's lot and supplement files
+ * while its address file streams, so the join never holds the country at once.
  */
 export async function* readJusoLabelRows(
 	archivePath: PathBuilderLike,

package/lib/kr/adapters/localdata/align.ts

@@ -3,21 +3,9 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Align one permit-registry address string to the LABEL register's key, or answer null (#2204 §5).
- *
- *   Every permit row carries the same premises in both address systems, typed by a clerk:
- *
- *       도로명주소  서울특별시 종로구 종로 233, 1층 일부호 (종로5가)
- *       지번주소    서울특별시 종로구 종로5가 43-1
- *
- *   The road-name form is `<시도> <시군구> <도로명> <건물번호>`, then an optional `, <상세주소>` (floor, unit, building)
- *   and an optional parenthetical `(<법정동>[, <건물명>])`; the lot-number form is
- *   `<시도> <시군구> <법정동> [<리>] [산]<본번>[-<부번>]` followed by whatever the clerk added.
- *
- *   ALIGNMENT IS EXACT against {@link KeyIndex}, never fuzzy. A string that satisfies the whole key becomes a training
- *   row whose spans are the matched pieces; one that does not is a BOARD row — an address the model will be read on and
- *   never trained on. The rate per file is measured and reported before any row enters a corpus, which is the rule a
- *   noisy source is admitted under.
+ * Align one permit-registry address string to the address register's key, or answer null. Alignment
+ * is exact against {@link KeyIndex} rather than fuzzy, so a string that satisfies the whole key becomes
+ * a training row of matched spans and one that does not becomes a board row.
  */
 
 import { type KeyIndex, sigunguSpan, unitKey } from "#kr/adapters/localdata/key-index"
@@ -38,13 +26,13 @@ const LOT_NUMBER = /^산?\d+(?:-\d+)?(?:번지)?$/u
 const UNIT_TOKEN = /^(?:지하\s?)?(?:B?\d+(?:~\d+)?(?:층|호)|\d+층|B\d+|지하\d*층?|\d+동|[가-힣]?\d*호)(?:,)?$/u
 
 /**
- * The shortest either form can be: 시도, 시군구, and the road or the 법정동. Anything shorter cannot carry the key, whatever
- * else it holds.
+ * The shortest either form can be — 시도, 시군구 and the road or the 법정동.
+ * No shorter value can contain the key.
  */
 const MINIMUM_TOKENS = 3
 
 /**
- * One aligned string: the spans that matched, and the key they matched under.
+ * One aligned string: the spans that matched and the key they matched under.
  */
 export interface Aligned {
 	raw: string
@@ -63,10 +51,10 @@ interface Span {
 }
 
 /**
- * Record a span, unless it is empty or blank.
+ * Record a span unless it is empty or blank.
  *
- * A blank span is what a clerk's double space produces, and a zero-width one what a token found at its own end
- * produces; neither is a component and both would train the model on nothing.
+ * A blank span from a clerk's double space or a zero-width one at a token's own
+ * end would train the model on no component.
  */
 function put(spans: Span[], text: string, start: number, end: number, tag: string): void {
 	if (end > start && text.slice(start, end).trim()) {
@@ -75,8 +63,8 @@ function put(spans: Span[], text: string, start: number, end: number, tag: strin
 }
 
 /**
- * Where each token begins in the original text, walked left to right so a repeated token takes its own position rather
- * than the first one's.
+ * Where each token begins in the original text, walked left to right so a repeated
+ * token takes its own position rather than the first one's.
  */
 function tokenPositions(text: string, tokens: readonly string[], from = 0): number[] {
 	const positions: number[] = []
@@ -136,7 +124,7 @@ export function alignRoadAddress(text: string, index: KeyIndex): Aligned | null
 	const region = tokens[0]!
 	const width = sigunguSpan(index, region, tokens, 1)
 
-	// A region with no 시군구 level (세종특별자치시) lists the empty string; its strings go region → road.
+	// A region with no 시군구 level (세종특별자치시) lists the empty string, so its strings go region → road.
 	if (!width && !index.sigunguByRegion.get(region)?.has("")) return null
 
 	const sigungu = tokens.slice(1, 1 + width).join(" ")
@@ -147,14 +135,15 @@ export function alignRoadAddress(text: string, index: KeyIndex): Aligned | null
 	let roadAt = 1 + width
 	let eupmyeonAt: number | null = null
 
-	// In an 읍/면 area the road form carries the 읍/면 between the 시군구 and the road (`기장군 기장읍 기장해안로 205`); the
-	// register lists those names beside the 동 of the same unit.
+	// In an 읍/면 area the road form includes the 읍/면 between the 시군구 and the road
+	// (`기장군 기장읍 기장해안로 205`); the register lists those names beside the 동 of the same unit.
 	if (roadAt + 2 < tokens.length && dongs.has(tokens[roadAt]!) && roads.has(tokens[roadAt + 1]!)) {
 		eupmyeonAt = roadAt
 		roadAt += 1
 	}
 
-	// A road name is one token; a numbered branch (`대학로8길`) is part of that token in the register.
+	// A road name is one token.
+	// A numbered branch (`대학로8길`) is part of that token in the register.
 	if (roadAt + 1 >= tokens.length || !roads.has(tokens[roadAt]!)) return null
 
 	let numberAtToken = roadAt + 1
@@ -188,8 +177,7 @@ export function alignRoadAddress(text: string, index: KeyIndex): Aligned | null
 
 	put(spans, text, numberAt, numberAt + number.length, "house_number")
 
-	// What follows the number, with or without a comma, is the building name and then the floor/unit — the same
-	// leading-venue, unit-tail reading the lot form uses.
+	// What follows the number, with or without a comma, reads as venue then unit, the same as the lot form.
 	const restTokens = [...tokens.slice(numberAtToken + 1), ...detail.split(/\s+/u).filter((token) => token.length)]
 
 	if (restTokens.length) {
@@ -282,8 +270,9 @@ export function alignLotAddress(text: string, index: KeyIndex): Aligned | null {
 	const rest = tokens.slice(lotAt + 1)
 
 	if (rest.length) {
-		// The clerk writes the building name first and the floor/unit after it (`교보생명빌딩 2층`, `지강빌딩 1층 일부호`):
-		// the venue is the run of tokens before the first unit-shaped one, the unit everything from there to the end.
+		// The clerk writes the building name first and the floor/unit after it
+		// (`교보생명빌딩 2층`, `지강빌딩 1층 일부호`): the venue is the run of tokens before the first
+		// unit-shaped one, the unit everything from there to the end.
 		const firstUnit = firstUnitIndex(rest)
 
 		if (firstUnit) {

package/lib/kr/adapters/localdata/key-index.ts

@@ -3,32 +3,25 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The LABEL register's key sets, the only thing a permit string is allowed to align against (#2204 §5).
- *
- *   The permit registry is a NOISY source: a clerk typed each address, in both address systems, with no validation. So
- *   nothing in a permit string is taken on its own word. The region must be a 시도 the register lists, the 시군구 one
- *   that region lists, the road one that 시군구 lists, the 동 one that 시군구 lists, the 리 one that 동 lists. A string
- *   that satisfies the whole key becomes a training row; one that does not is a BOARD row — an address the model will
- *   be read on and never trained on.
- *
- *   Built by one pass over the LABEL rows, which is why it lives beside them rather than inside the aligner.
+ * The address register's key sets, the only thing a permit string is allowed to align against. The
+ * permit registry's address field is an `observation` a clerk typed without validation, so every part
+ * of a string — 시도, 시군구, road, 동, 리 — must be one the register lists under its parent.
  */
 
 import { type JusoLabelRow, REGION_ALIASES } from "#kr/adapters/juso/label-rows"
 
 /**
- * The separator between the parts of a composite key, written as an escape so no NUL byte enters the source.
+ * The separator between the parts of a composite key, written as an escape
+ * so no NUL byte enters the source.
  *
- * A space cannot serve. A 시군구 is written with one (`수원시 장안구`), so `unitKey("A", "B C")` and `unitKey("A B", "C")` would
- * produce one key for two different places. No place name contains NUL.
+ * A space cannot serve, because a 시군구 is written with one (`수원시 장안구`)
+ * and `unitKey("A", "B C")` would collide with `unitKey("A B", "C")`.
  */
 const UNIT_SEPARATOR = "\0"
 
 /**
- * The key sets, keyed as the register nests them.
- *
- * A composite string key where the register's own key is a tuple, because a nested map costs a second lookup on the hot
- * path and every permit row does several.
+ * The key sets keyed as the register nests them, as composite string keys rather than
+ * nested maps, because a nested map costs a second lookup on the hot path.
  */
 export interface KeyIndex {
 	regions: Set<string>
@@ -78,10 +71,10 @@ function add(map: Map<string, Set<string>>, key: string, value: string): void {
 }
 
 /**
- * Add one LABEL row's names to the key sets.
+ * Add one label row's names to the key sets.
  *
- * The 읍/면 joins the road set's unit as a road-form token too, since the road address writes it between the 시군구 and the
- * road.
+ * The 읍/면 joins the unit's 동 set as a road-form token, since the road address
+ * writes it between the 시군구 and the road.
  */
 export function indexLabelRow(index: KeyIndex, row: JusoLabelRow): void {
 	index.regions.add(row.region)
@@ -105,10 +98,8 @@ export function indexLabelRow(index: KeyIndex, row: JusoLabelRow): void {
 }
 
 /**
- * Admit the pre-merger region names as aliases of the register's current one, SHARING its key sets.
- *
- * The sets are shared by reference rather than copied: an alias is the same place under an older name, and a later
- * `indexLabelRow` under either name must reach the same set.
+ * Admit the pre-merger region names as aliases of the register's current one, sharing its
+ * sets by reference so a later `indexLabelRow` under either name reaches the same set.
  */
 export function aliasKeyIndex(index: KeyIndex): void {
 	for (const [legacy, current] of Object.entries(REGION_ALIASES)) {
@@ -153,7 +144,8 @@ export function aliasKeyIndex(index: KeyIndex): void {
 /**
  * How many tokens from `start` form one of the region's 시군구 — 2 for `수원시 장안구`, 1 for `종로구`, 0 for none.
  *
- * Two-token first: `수원시` alone is also a listed name, and taking it would leave `장안구` to be read as a road.
+ * Two-token first, because `수원시` by itself is also listed and taking it would
+ * leave `장안구` to be read as a road.
  */
 export function sigunguSpan(index: KeyIndex, region: string, tokens: readonly string[], start: number): number {
 	const candidates = index.sigunguByRegion.get(region)
@@ -170,7 +162,7 @@ export function sigunguSpan(index: KeyIndex, region: string, tokens: readonly st
 }
 
 /**
- * The key sets the permit aligner reads, from one pass over the LABEL rows.
+ * The key sets the permit aligner reads, from one pass over the register rows.
  */
 export async function buildKeyIndex(rows: AsyncIterable<JusoLabelRow>): Promise<KeyIndex> {
 	const index = emptyKeyIndex()

package/lib/kr/adapters/localdata/permit-rows.ts

@@ -3,38 +3,44 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The Korean permit registry (지방행정인허가데이터) as a NOISY corpus source: reading the delivered CSVs, and turning
- *   an aligned string into a corpus row (#2204 §5).
+ * The Korean permit registry (지방행정인허가데이터) as an `observation` source. It reads the delivered
+ * CSVs and turns an aligned string into a corpus row.
  *
- *   The publisher delivers CP949, one file per business category, with both address systems typed by a clerk plus a
- *   planar coordinate in EPSG:5174 and both postcodes. Reading is separated from ALIGNING so the alignment rate per
- *   file can be measured before any row enters a corpus.
+ * The publisher delivers CP949, one file per business category, with both address systems typed by
+ * a clerk plus a planar coordinate in epsg:5174 and both postcodes. The adapter separates reading from
+ * aligning so the alignment rate per file can be measured before any row enters a corpus.
  */
 
 import { decodeByteStream, openReadStream } from "@mailwoman/core/fs/streams"
-import { basename, extname, join, type PathBuilderLike } from "path-ts"
+import { basename, extname, type PathBuilderLike, resolvePathBuilder } from "path-ts"
 import { CSVSpliterator } from "spliterator"
 import { Globerator } from "spliterator/node/fs"
 
 import type { Aligned } from "#kr/adapters/localdata/align"
 
 /**
- * The source label every row of this adapter carries, and the name a config's `source_weights` addresses it by.
+ * The source label stored on every row from this adapter.
+ * Configs use this label as the `source_weights` key.
  */
 export const SOURCE = "localdata-kr"
 
 /**
- * Every permit in this registry is Korean; the publisher issues no others.
+ * Every permit in this registry is Korean.
+ * The publisher issues no others.
  */
 export const COUNTRY = "KR"
 
 /**
- * The 영업상태명 of a business still trading. A closed one's address records somewhere that was.
+ * The 영업상태명 of a business still trading.
+ *
+ * A closed one's address records somewhere that was.
  */
 export const OPEN_STATUS = "영업/정상"
 
 /**
- * The publisher's encoding. `cp949` rather than `euc-kr` for the reason `decodeByteStream` states.
+ * The publisher's encoding.
+ *
+ * `cp949` rather than `euc-kr` for the reason `decodeByteStream` states.
  */
 const ENCODING = "cp949"
 
@@ -57,11 +63,11 @@ export interface PermitRow {
 }
 
 /**
- * The first of these column spellings the row carries, trimmed, or the empty string.
+ * The first of these column spellings present in the row, trimmed, or the empty string.
  *
- * The publisher's older and newer exports name the same field differently — `도로명주소` against `도로명전체주소`, `좌표정보(X)`
- * against `좌표정보(x)` — and a directory holds both vintages, so each field names every spelling it has been delivered
- * under.
+ * The publisher's older and newer exports name the same field differently — `도로명주소`
+ * against `도로명전체주소`, `좌표정보(X)` against `좌표정보(x)` — and a directory holds both vintages,
+ * so each field names every spelling it has been delivered under.
  */
 function firstColumn(row: Record<string, string | undefined>, ...names: readonly string[]): string {
 	for (const name of names) {
@@ -83,7 +89,9 @@ function toNumber(value: string): number | null {
 
 export interface ReadPermitOptions {
 	/**
-	 * Keep only these 영업상태명 values. Empty admits every status.
+	 * Keep only these 영업상태명 values.
+	 *
+	 * Empty admits every status.
 	 */
 	statuses?: readonly string[]
 }
@@ -96,7 +104,8 @@ export async function* readPermitFile(
 	options: ReadPermitOptions = {}
 ): AsyncGenerator<PermitRow> {
 	const wanted = new Set(options.statuses ?? [OPEN_STATUS])
-	const category = basename(String(path), extname(String(path)))
+	const file = path.toString()
+	const category = basename(file, extname(file))
 	const bytes = openReadStream(path)
 
 	for await (const row of CSVSpliterator.fromAsync<Record<string, string>>(decodeByteStream(bytes, ENCODING))) {
@@ -130,24 +139,22 @@ export async function* readPermitDirectory(
 	directory: PathBuilderLike,
 	options: ReadPermitOptions = {}
 ): AsyncGenerator<PermitRow> {
-	const files = await Globerator.from("*", { cwd: directory, withFileTypes: true, onlyFiles: false })
-		.filter((entry) => entry.isFile() && entry.name.endsWith(".csv"))
-		.map((entry) => entry.name)
-		.toSorted()
+	const files = await Globerator.files("csv", { cwd: directory, absolute: false, recursive: false }).toSorted()
 
 	for (const name of files) {
-		yield* readPermitFile(join(directory, name), options)
+		yield* readPermitFile(resolvePathBuilder(directory, name), options)
 	}
 }
 
 /**
- * One aligned string as a row in the CJK slice schema.
+ * One aligned string as a row in the CJK corpus schema.
  *
- * The token labels are derived from the spans rather than carried beside them: a token is `B-<tag>` when its FIRST
- * character falls inside a span, `O` otherwise. A span covering several tokens therefore labels only the token it
- * starts in, which is what the char-path trainer reads the spans for.
+ * The token labels are derived from the spans rather than stored beside them:
+ * a token is `B-<tag>` when its first character falls inside a span, `O` otherwise.
+ * A span covering several tokens labels only the token where it starts.
+ * The char-path trainer reads this label from each span.
  */
-export function alignedToSliceRow(aligned: Aligned): Record<string, unknown> {
+export function alignedToCJKRow(aligned: Aligned): Record<string, unknown> {
 	const raw = aligned.raw
 	const tokens: string[] = []
 	const labels: string[] = []

package/lib/kr/tools/fetch/juso.ts

@@ -4,33 +4,29 @@
  * @author Teffen Ellis, et al.
  *
  *   Fetch the Korean road-name address register (도로명주소 주소DB) from the ministry's address-industry
- *   portal, business.juso.go.kr. This is the LABEL source for Korean addresses: about 6,000,000
+ *   portal, business.juso.go.kr. The ministry assigns the road names and building numbers it publishes, so
+ *   this source asserts `address` on `premise` rows: about 6,000,000
  *   road-name addresses and 8,000,000 lot-number (지번) records, split by the publisher into four
  *   pipe-delimited CP949 text files per region (도로명코드 / 주소 / 지번 / 부가정보), with the postcode in
  *   the supplementary file. No coordinates. The public-data portal labels it "이용허락범위 제한 없음"
- *   (no restriction on the scope of use), and it is a direct download with no application step — the
- *   distinction that matters against the ministry's entrance-coordinate products, which are provided
+ *   (no restriction on the scope of use). It is a direct download with no application step — the
+ *   distinction that matters against the ministry's entrance-coordinate products. Those products are provided
  *   only after a purpose-of-use review (`docs/superpowers/plans/counsel-dossier.md` §4).
  *
- *   The portal is a single-page app; the file behind it is reached in two calls. `selectAttrbDBDwldList`
+ *   The portal is a single-page app. the file behind it is reached in two calls. `selectAttrbDBDwldList`
  *   lists the monthly full files for one product (`rtlDtaDtlSn` 8 is the 주소DB, 2 the English
- *   road-name DB), and `/api/jst/download` streams one by the parameters the listing carried. The
- *   English DB rides along because it is the Latin-script half of the same register.
+ *   road-name DB), and `/api/jst/download` streams one by the parameters in the listing. The
+ *   English DB accompanies it as the Latin-script half of the same register.
  *
  *   Invoke via `mailwoman corpus fetch juso-kr --out-root <path>`.
  */
 
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
-import { join } from "path-ts"
+import { stringifyJSON } from "@mailwoman/core/json"
 
-import type {
-	BaseFetchOptions,
-	FetchSummary,
-	SourceCollectionManifest,
-	SourceManifest,
-} from "#tools/fetch/download/index"
-import { resumableDownload, writeManifest } from "#tools/fetch/download/index"
+import type { BaseFetchOptions, FetchSummary, SourceCollectionManifest, SourceManifest } from "#tools/fetch/download"
+import { resumableDownload, writeManifest } from "#tools/fetch/download"
 
 const SLUG = "juso-kr"
 const PORTAL = "https://business.juso.go.kr"
@@ -68,7 +64,9 @@ interface ListResponse {
 
 export interface FetchJusoKROptions extends BaseFetchOptions {
 	/**
-	 * The month to fetch as `YYYYMM`. Defaults to the latest month the portal lists as present.
+	 * The month to fetch as `yyyymm`.
+	 *
+	 * Defaults to the latest month the portal lists as present.
 	 */
 	month?: string
 }
@@ -85,7 +83,7 @@ async function listMonthlyFiles(sn: string, year: number, month: number): Promis
 	const res = await fetch(LIST_URL, {
 		method: "POST",
 		headers: { ...BROWSER_HEADERS, accept: "application/json", "content-type": "application/json;charset=UTF-8" },
-		body: JSON.stringify({ rtlDtaDtlSn: sn, year, month, expand: "Y" }),
+		body: stringifyJSON({ rtlDtaDtlSn: sn, year, month, expand: "Y" }),
 	})
 
 	if (!res.ok) throw new Error(`juso-kr: listing product ${sn} answered HTTP ${res.status}`)
@@ -110,7 +108,7 @@ function downloadURL(file: ListedFile, regYmd: string): string {
 }
 
 export async function fetchJusoKR(options: FetchJusoKROptions, report?: (line: string) => void): Promise<FetchSummary> {
-	const destDir = join(options.outRoot, SLUG)
+	const destDir = options.outRoot(SLUG)
 	await makeDirectories(destDir)
 
 	const now = new Date()
@@ -129,13 +127,13 @@ export async function fetchJusoKR(options: FetchJusoKROptions, report?: (line: s
 		}
 
 		const url = downloadURL(file, String(now.getFullYear()))
-		const dest = join(destDir, file.tmprFileNm)
+		const dest = destDir(file.tmprFileNm)
 		report?.(`=== ${SLUG} / ${product.name} ${file.crtrYm} → ${file.tmprFileNm}`)
 		let bytes: number
 
 		try {
-			// The portal drops a connection every few megabytes and answers Range with 206, so the transfer resumes
-			// from what landed rather than starting the 181 MB over.
+			// The portal drops a connection every few megabytes and answers Range with 206,
+			// so the transfer resumes from what landed rather than starting the 181 MB over.
 			bytes = await resumableDownload({ url, dest, headers: BROWSER_HEADERS, report })
 		} catch (error) {
 			report?.(`  ✗ ${(error as Error).message}`)
@@ -166,7 +164,7 @@ export async function fetchJusoKR(options: FetchJusoKROptions, report?: (line: s
 		files,
 	}
 
-	await writeManifest(join(destDir, "MANIFEST.json"), manifest)
+	await writeManifest(destDir("MANIFEST.json"), manifest)
 
 	return { fetched: files.length, skipped: 0, failed: failedCodes.length, failedCodes }
 }