@mailwoman/corpus 10.0.0 → 10.2.0

package/out/recipes/scaffold.js

@@ -3,42 +3,31 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Shared scaffolding for the synthetic-corpus SLICE RECIPES — the common bits the 16
- *   `build-*-slice.mjs` scripts each re-implemented: the seeded LCG PRNG, the tuple reader, and the
- *   canonical → `alignRow` → `LabeledRow` JSONL emit step. A recipe ({@link CorpusRecipe}) supplies
- *   only its synthesis + filter; the `mailwoman corpus slice <recipe>` command supplies the I/O.
+ *   Shared scaffolding for corpus recipes: the seeded LCG PRNG, the tuple reader and
+ *   the canonical → `alignRow` → `LabeledRow` jsonl emit step. A recipe ({@link CorpusRecipe})
+ *   supplies only its row construction and filter. The `mailwoman corpus slice <recipe>` command
+ *   supplies the I/O.
  */
-import { pathExists } from "@mailwoman/core/fs/readers";
+import { pathExists } from "@mailwoman/core/fs/readers/stat";
 import { readZipEntry } from "@mailwoman/core/fs/zip";
-import { tryParsingJSON } from "@mailwoman/core/json";
+import { tryParsingJSON, stringifyJSON } from "@mailwoman/core/json";
 import { AsyncSequence, CSVSpliterator, TextSpliterator } from "spliterator";
-import { stableSourceIDFromParts } from "#adapters/utils";
+import { stableSourceIDFromParts } from "#adapters/source-id";
 import { alignRow } from "#utils";
 /**
- * {@link stableSourceIDFromParts} under the name the recipes use: arbitrary disambiguator keys (e.g. a variant index
- * `v`) that aren't `ComponentTag`s, which is how the legacy builders kept per-variant ids unique.
+ * {@link stableSourceIDFromParts} under the name the recipes use, for arbitrary
+ * disambiguator keys (e.g. a variant index `v`) that are not `ComponentTag`s.
  */
-export function sliceSourceID(adapterID, parts) {
+export function recipeSourceID(adapterID, parts) {
     return stableSourceIDFromParts(adapterID, parts);
 }
 /**
- * Line breaks inside a value become single spaces, and every value is trimmed.
+ * Line breaks inside a value become single spaces.
+ * The function trims every value.
  *
- * A quote-aware parse is the first thing able to return a value CONTAINING a line break — `us/ia/statewide.csv` has 12,
- * all unit designators like `"#2\n#2"` — and every consumer synthesizes one-line address text from these cells with no
- * guard, because until that parse landed no value could carry one. Collapsing keeps the record (the address is fine;
- * the source's line break is not part of it) without emitting a training row with a newline inside it.
- *
- * Only `\r` and `\n`, deliberately — NOT `\s`. Runs of spaces and tabs pass through exactly as the source wrote them
- * (OA's IA extract writes `NORTH`, three spaces, `MAIN STREET`), because those could always appear and every slice
- * built to date contains them. Widening this to `\s+` silently rewrites values on rows with no line break at all.
- * `scaffold.test.ts` pins both halves.
- *
- * This is what a CSV reader here still owns. Quote handling, object rows, and lower-case keys are `CSVSpliterator`'s
- * defaults, so a recipe reads a source with `CSVSpliterator.fromAsync(source).map(withoutLineBreaks)` and needs nothing
- * else.
- *
- * @category CSV
+ * The pattern matches exactly `\r` and `\n`: widening to `\s+` would silently rewrite values on
+ * rows with no line break at all (OA's IA extract writes `north`, three spaces, `main street`),
+ * and `scaffold.test.ts` pins both directions.
  */
 export function withoutLineBreaks(record) {
     const out = {};
@@ -50,31 +39,22 @@ export function withoutLineBreaks(record) {
 /**
  * Read a CSV as header-keyed records.
  *
- * Returns the spliterator's own {@linkcode AsyncSequence}, so a caller composes `take`/`drop`/`filter` onto it — those
- * ops fuse into one pull loop, and a `take` that is satisfied closes the source's file handle on the way out. Wrapping
- * this in an `async function*` costs an async frame per row and takes those ops away; don't.
- *
- * A source at or below the spliterator's 128 KiB bulk threshold is read whole and parsed by the synchronous engine, so
- * this is also the right reader for small sources — there is no buffered variant to reach for.
- *
- * @category CSV
+ * Returns the spliterator's own {@linkcode AsyncSequence} so a caller composes
+ * `take`/`drop`/`filter` onto it.
+ * An `async function*` wrapper would cost an async frame per row and remove those ops.
  */
 export function readCSVRecords(source) {
     return CSVSpliterator.fromAsync(source).map(withoutLineBreaks);
 }
 /**
- * {@link readCSVRecords} over one member of a zip archive — what every recipe reading a cached OA source wants.
+ * {@link readCSVRecords} over one member of a zip archive.
  *
- * A source a checkout has not cached yields nothing, after saying so. A lab holds the archives for the countries it has
- * built, so a recipe naming ten sources routinely finds three, and the `unzip -p` subprocesses these replaced behaved
- * the same way by accident — a non-zero exit warned and returned no rows. A recipe that ends up with NO tuples at all
- * still throws; that is the case where the cache, not the recipe, is the problem.
- *
- * @category CSV
+ * A source a checkout has not cached yields no rows after warning, while a recipe
+ * that ends up with no tuples at all still throws.
  */
 export function readZippedCSVRecords(archivePath, entryName) {
     return AsyncSequence.from(async () => {
-        if (!(await pathExists(String(archivePath)))) {
+        if (!(await pathExists(archivePath))) {
             console.error(`  WARN: ${archivePath} is not cached — skipping ${entryName}`);
             return [];
         }
@@ -82,26 +62,25 @@ export function readZippedCSVRecords(archivePath, entryName) {
     });
 }
 /**
- * License stamped on the synthetic tuple-derived slices (`po-box`, `no-street`, `house-venue`): the output is
- * generated, but it inherits the terms of the real tuples it is derived from, so the attribution travels with it.
+ * License stamped on the synthetic tuple-derived recipe outputs.
+ *
+ * The output is generated but inherits the terms of the real tuples it derives from,
+ * so the attribution travels with it.
  */
 export const SYNTHETIC_TUPLE_LICENSE = "Synthetic — derived from CC-BY / public-domain input tuples";
 /**
- * The surface key shared by the Norwegian slices (`no-fragment`, `no-street-led`).
+ * The surface key shared by the Norwegian recipes (`no-fragment`, `no-street-led`).
  *
- * MUST match the NO digit board's `norm_surface`: NFC, lowercase, collapse whitespace — and KEEP diacritics.
- * fr-fragment's norm strips them (NFD + combining-mark removal), which is right for French but would collapse
- * `Tømmerlien` → `tommerlien` here, so a slice's exclusion check would never match the board's reserved `tømmerlien`
- * and the train/eval split would leak silently. Diacritic street heads (…vegen/…veien with ø/å/æ) are the whole point
- * of those slices' boundary; folding them away is not an option.
+ * Must match the Norwegian digit board's `norm_surface` (NFC, lowercase, collapse whitespace,
+ * keep diacritics); folding them away would collapse `Tømmerlien` to `tommerlien`,
+ * never match the board's reserved `tømmerlien`, and leak the train/eval split silently.
  */
 export const foldNOSurface = (value) => value.normalize("NFC").toLowerCase().replaceAll(/\s+/g, " ").trim();
 /**
- * Stream distinct tuples out of a cached OA zip — the reader the OA-skeleton recipes (`street-affix`, `unit`,
- * `country-balanced`, `fr-order`) share. Field reads, filters, dedup keys and row order are exactly what each recipe's
- * local copy did, so a recipe's slice stays byte-identical.
+ * Stream distinct tuples out of a cached OA zip, the reader the OA-skeleton recipes
+ * (`street-affix`, `unit`, `country-balanced`, `fr-order`) share.
  *
- * @category CSV
+ * Field reads, filters, dedup keys and row order keep each recipe's output byte-identical.
  */
 export async function readOATuples(source, options) {
     const tuples = [];
@@ -128,28 +107,59 @@ export async function readOATuples(source, options) {
     return tuples;
 }
 /**
- * Stream-parse a tuples JSONL file, yielding each parsed object (blank/invalid lines skipped).
+ * Stream-parse a tuples jsonl file, yielding each parsed object (blank/invalid lines skipped).
  */
 export function readTuples(input) {
-    // TextSpliterator (not JSONSpliterator) keeps the reader's established tolerance: malformed lines are skipped rather
-    // than rejecting the sequence. These operators fuse into the source's pull loop instead of adding an async-generator
-    // frame per tuple.
+    // TextSpliterator keeps the reader tolerant of malformed lines.
+    // JSONSpliterator would throw.
+    // These operators fuse into the source's pull loop.
     return TextSpliterator.fromAsync(input)
-        .map((line) => line.trim())
-        .filter((line) => Boolean(line))
         .map((line) => tryParsingJSON(line))
         .filter((tuple) => tuple !== null)
         .map((tuple) => tuple);
 }
 /**
- * Run a canonical row through `alignRow` and, on success, write the `LabeledRow` (+ `synth_method` / `synth_base_id`)
- * as one JSONL line. Returns true if emitted, false if alignment quarantined it.
+ * Bind {@linkcode WriteRecipeLine} to a sink, supplying the delimiter.
+ *
+ * A concatenation would stringify a non-string chunk through `toString()` and corrupt its bytes.
+ */
+export function createRecipeLineWriter(sink) {
+    return (line) => {
+        sink.write(line);
+        sink.write("\n");
+    };
+}
+/**
+ * The register a tuple-reading recipe was invoked with.
+ *
+ * It throws when the flag is absent, naming the recipe, because a default would
+ * stamp one register's id on another register's records.
+ */
+export function requireRegister(opts, recipe) {
+    if (!opts.register) {
+        throw new Error(`${recipe} requires --register <id>: the register the --input tuples were extracted from, ` +
+            `e.g. whos-on-first, openstreetmap, fr-ban. It is written onto every row this recipe emits.`);
+    }
+    return opts.register;
+}
+/**
+ * Run a canonical row through `alignRow` and, on success, write the `LabeledRow`
+ * with its recipe id and provenance as one jsonl line.
+ *
+ * The provenance columns are flat because the parquet schema is flat.
  */
-export function alignAndWrite(write, canonical, synthMethod, synthBaseID = null) {
+export function alignAndWrite(write, canonical, recipe, provenance) {
     const aligned = alignRow(canonical);
-    if (!aligned.row)
+    // A quarantined result also has a `row`, the quarantine record, so the kind decides.
+    if (aligned.kind !== "labeled")
         return false;
-    write(JSON.stringify({ ...aligned.row, synth_method: synthMethod, synth_base_id: synthBaseID }) + "\n");
+    write(stringifyJSON({
+        ...aligned.row,
+        recipe,
+        register: provenance.register,
+        surface: provenance.surface,
+        base_source_id: provenance.baseSourceID ?? null,
+    }));
     return true;
 }
 //# sourceMappingURL=scaffold.js.map

package/out/recipes/scaffold.js.map

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

package/out/recipes/sources.d.ts

@@ -0,0 +1,178 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The `source` identifiers that recipe outputs write, under their retired and current spellings.
+ *
+ *   A recipe-output `source` is a wire identifier rather than prose. It is the literal value of the `source` column on
+ *   every row of every built corpus, the key a training config's `source_weights`, `source_reps`,
+ *   `augment_exclude_sources` and `required_corpus_receipts[].source` address this value. `overlay-manifest` records
+ *   the `--source` label per file. Published model cards also quote the string. A rename requires a data migration
+ *   across every corpus that stores it. This table retains both spellings while an archived corpus or historical
+ *   config records the older one.
+ *
+ *   The retired spelling is `synth-<tail>`. It was read as "synthetic", and most of the rows it labels are real
+ *   published records written in a layout: `synth-german` stores `register: openaddresses` and `surface: composed`.
+ *   The current spelling is `<operation>-<tail>`, where the operation states what the recipe did to attested data.
+ *   The tail is kept byte-for-byte, so the mapping is a prefix swap in either direction.
+ *
+ *   The prefix states the recipe's operation. That value stays constant per source. It omits `surface`, a row property that
+ *   varies within a source. It also omits the register because `requireRegister` makes that an invocation property.
+ *
+ *   Every recipe reads its default `source` from this table through {@linkcode defaultRecipeSource}, and
+ *   {@linkcode WRITE_CURRENT_SOURCE_NAMES} decides which spelling it answers with. An assembly rewrites its routed
+ *   overlays through this table before `overlay-manifest` runs, so the rows and the recipe defaults move together.
+ */
+/**
+ * What a recipe did to attested data to produce its rows.
+ *
+ * This describes the operation behind a source's id.
+ * The row's `surface` is a separate field that `SurfaceOrigin` in `#types` records,
+ * and the two spell `rendered` for different classifications.
+ *
+ * A `rendered-*` source records `SurfaceOrigin.Composed`, because `renderLocaleRow` draws
+ * on the row's house number and postcode and takes an order, so it varies the written form
+ * rather than writing one canonical form per record.
+ * `SurfaceOrigin.Rendered` belongs to an adapter that writes that one form.
+ */
+export declare const SourceOperation: {
+    /**
+     * One real record, written in a layout its country uses, with the form varied across rows.
+     */
+    readonly Rendered: "rendered";
+    /**
+     * Part of one real record.
+     */
+    readonly Fragment: "fragment";
+    /**
+     * A real record with a drawn component added.
+     */
+    readonly Spliced: "spliced";
+    /**
+     * No real record behind the row.
+     */
+    readonly Invented: "invented";
+    /**
+     * A string copied verbatim from `@mailwoman/codex`.
+     */
+    readonly Codex: "codex";
+    /**
+     * Rows a person wrote and checked.
+     */
+    readonly Reviewed: "reviewed";
+};
+/**
+ * One of the {@link SourceOperation} values.
+ */
+export type SourceOperation = (typeof SourceOperation)[keyof typeof SourceOperation];
+/**
+ * One recipe-output source under both spellings.
+ */
+export interface RecipeSource {
+    /**
+     * The spelling recipes wrote through 2026-09-26.
+     *
+     * Every corpus assembled before that date stores this spelling.
+     */
+    retired: string;
+    /**
+     * The spelling a corpus assembled after the rewrite stores and a training config keys on.
+     */
+    current: string;
+    operation: SourceOperation;
+    /**
+     * The file that writes the rows, relative to `packages/corpus/lib/`
+     * unless the value specifies another root.
+     */
+    producer: string;
+    /**
+     * Why the producer's path does not fully explain the placement.
+     */
+    note: string | null;
+}
+/**
+ * Every recipe-output source that a corpus on disk, a training config
+ * or a recipe default has spelled `synth-*`.
+ *
+ * Measured on 2026-09-26 over `/mnt/mw/corpus/versioned/`: 46 values on disk,
+ * 47 keys across 226 configs and the recipe defaults.
+ * This list is their union.
+ */
+export declare const RECIPE_SOURCES: ReadonlyArray<RecipeSource>;
+/**
+ * Overlay sources that are not recipe outputs and keep their spelling.
+ *
+ * Each is either a register's own name, used by an adapter or builder that reads that
+ * register by construction, or an adversarial set whose producer chose the name.
+ * They are listed so a check over training configs can tell a source that
+ * exists from one that a sweep invented.
+ */
+export declare const CARRIED_SOURCES: ReadonlyArray<string>;
+/**
+ * The current spelling of a recipe-output source given either spelling,
+ * or `null` for a source this table does not record.
+ *
+ * A caller rewriting a corpus must refuse on `null` rather than pass the value through, because a
+ * pass-through leaves a corpus carrying two vocabularies with no record of which files were touched.
+ */
+export declare function currentSourceName(source: string): string | null;
+/**
+ * The table entry a source belongs to, under either spelling.
+ */
+export declare function recipeSource(source: string): RecipeSource | null;
+/**
+ * The spelling a recipe writes today, given the retired spelling it has always written.
+ *
+ * Every recipe's default `source` reads this rather than holding a literal, so the
+ * vocabulary is one constant rather than 26 files. {@linkcode WRITE_CURRENT_SOURCE_NAMES}
+ * decides which spelling it answers with.
+ * It must agree with the corpus that a recipe output joins.
+ *
+ * @throws When the table records no entry for `retired`.
+ * A pass-through would let a typo become a source ID on every row of a built corpus.
+ * `wire-identifiers` catches that failure later.
+ * This function catches it at the call.
+ */
+export declare function defaultRecipeSource(retired: string): string;
+/**
+ * Whether a recipe writes the operation spelling or the retired one.
+ *
+ * True since 2026-09-28, because the rewrite has run.
+ * `v0.7.0-overlay-staging` records 43 distinct sources, each under an operation prefix.
+ *
+ * Its `source-names.json` records the mapping applied per file with the row count
+ * and the ordered-`source_id` digest verified on both sides.
+ * `v0.7.0-de-holdout/corpus-v0.7.0-de-holdout` is assembled from those bytes over 766 slices.
+ *
+ * A recipe writing the retired spelling from here on would produce an output
+ * disagreeing with the corpus it joins.
+ *
+ * `v0.6.0-register-surface` and the staging directory's `.pre-rename` copy are never rewritten in place.
+ * The configs that target them keep the spelling their corpus stores.
+ */
+export declare const WRITE_CURRENT_SOURCE_NAMES = true;
+/**
+ * The retired spelling of a recipe-output source given either spelling, or the value unchanged.
+ *
+ * `RECIPE_SURFACES` and `OVERLAY_REGISTERS` key on the retired spelling.
+ * Both refuse a source they do not record.
+ *
+ * A corpus rewritten to the current spelling would therefore make each of them
+ * throw on every row in the corpus.
+ *
+ * Callers of those two tables resolve the key through this, so a lookup answers under
+ * either spelling and a genuinely unknown source still refuses.
+ *
+ * The value is returned unchanged for a source outside the table — an adapter id,
+ * or an overlay source id — because those tables are keyed by whatever the producer emits.
+ */
+export declare function retiredSourceName(source: string): string;
+/**
+ * Every recipe-output spelling and adapter source id this table knows.
+ *
+ * Adapter ids are not here.
+ * They are declared by each adapter as `<NAME>_ADAPTER_ID`, and a reader that needs
+ * the full set of stored `source` values joins the two.
+ */
+export declare function knownOverlaySourceNames(): ReadonlySet<string>;
+//# sourceMappingURL=sources.d.ts.map

package/out/recipes/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../lib/recipes/sources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe;IAC3B;;OAEG;aACH,QAAQ,EAAE,UAAU;IACpB;;OAEG;aACH,QAAQ,EAAE,UAAU;IACpB;;OAEG;aACH,OAAO,EAAE,SAAS;IAClB;;OAEG;aACH,QAAQ,EAAE,UAAU;IACpB;;OAEG;aACH,KAAK,EAAE,OAAO;IACd;;OAEG;aACH,QAAQ,EAAE,UAAU;CACX,CAAA;AAEV;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAA;AAEpF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,eAAe,CAAA;IAC1B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CACnB;AAsBD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,YAAY,CAsItD,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC,MAAM,CAgDjD,CAAA;AAKD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE/D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAEhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAW3D;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAA;AAE9C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,WAAW,CAAC,MAAM,CAAC,CAE7D"}