@toolpath/tool-scraper 0.1.0 → 2.1.0

package/dist/records.d.ts

@@ -43,6 +43,8 @@
  * separately could supply a tool that claims a holder it does not have.
  */
 import { type UnitSystem } from './conventions.js';
+import { type BrandName } from './identity.js';
+import type { FactSource } from './provenance.js';
 /** The kinds of cutting tool this package maps. */
 export type ToolKind = 'drill' | 'tap' | 'endmill';
 /**
@@ -56,6 +58,35 @@ export type ToolKind = 'drill' | 'tap' | 'endmill';
  * and a tool's own list from another has no way to notice the two disagree.
  */
 export declare const ISO_MATERIAL_GROUPS: readonly ["P", "M", "K", "N", "S", "H", "C"];
+/**
+ * The material-groups label for **we do not know what this tool is for**.
+ *
+ * Not an ISO 513 group and deliberately not one of {@link ISO_MATERIAL_GROUPS}:
+ * it is a statement about this package's evidence, not about the tool. It sits
+ * in {@link ToolRecord.materialGroupsSource} rather than in the group list,
+ * because a consumer filtering a catalog down to "cuts steel" must not have to
+ * know that one of the letters is not a letter.
+ *
+ * **Why a label and not a bare `null`.** The absence was expressible before —
+ * `materialGroups === null` — and an absence is the one thing a reader has to
+ * interpret. Every Harvey part is here, and so is every Kennametal family whose
+ * material sweep has not been run: two different reasons for the same honest
+ * answer, and neither is "rated for nothing". A named value says that out loud
+ * in a UI, a log line and a filter, which `null` never does.
+ */
+export declare const UNSPECIFIED = "unspecified";
+/**
+ * How a record's material groups were arrived at.
+ *
+ * A fact's own three sources plus {@link UNSPECIFIED}, which provenance has no
+ * word for because a `Fact` only exists once somebody has stated something. A
+ * record exists either way, so it needs the fourth.
+ *
+ * Only `vendor-stated`, `derived` and `unspecified` occur today; `assumed` is
+ * reachable the moment a family fact supplies the groups, and is kept in the
+ * type so that the vocabularies cannot drift apart.
+ */
+export type MaterialGroupsSource = FactSource | typeof UNSPECIFIED;
 /** One canonical geometry name: what it measures, and whose name it is. */
 export interface GeometryField {
     /**
@@ -186,6 +217,55 @@ export declare const DIMENSIONAL: ReadonlySet<GeometryName>;
  * suffix would look for a column that was never scraped.
  */
 export declare const DIMENSIONAL_COLUMNS: ReadonlySet<GeometryName>;
+/**
+ * What geometry a **record** of each kind carries, as against what a family
+ * must map.
+ *
+ * {@link REQUIRED_GEOMETRY} is about columns: it refuses a family whose config
+ * maps no `LCF`. This is about the record that comes out the other end, and the
+ * two genuinely differ — a Kennametal drill's `NOF` and `SIG` come from facts
+ * and not from any column, so they can never appear in a column map and are
+ * always on the record.
+ *
+ * **`sometimes` is the point of the table.** An absent key was the one thing in
+ * a record a reader had to interpret: `geometry.NOF === undefined` means "Harvey
+ * publishes no flute count for this family" on an end mill and "not part of the
+ * contract" on a drill, and nothing said which. That is exactly the ambiguity
+ * {@link UNSPECIFIED} exists to remove from {@link ToolRecord.materialGroups},
+ * and the record shipped both encodings at once. Now the absence is declared:
+ * a key in `sometimes` may be missing and its absence is the vendor's silence;
+ * a key in neither list is not part of that kind's record at all.
+ *
+ * Every `sometimes` entry today is one vendor publishing nothing where another
+ * publishes a number. `sometimes` permits the key, it does not forbid it — the
+ * vendors that state these keep filling them.
+ *
+ * - the **end mill's `NOF`**, for Harvey's two deburring families — they
+ *   publish right- and left-hand tooth counts and no flute count, so there is
+ *   nothing to read and 0 is not a substitute;
+ * - the **tap's `NOF`**, for EMUGE-FRANKEN, which states no flute count
+ *   anywhere a scrape can reach — not on the grouped product, the variant
+ *   listing, the per-part detail record or any facet — while its own tap
+ *   families run 2, 3 and 4 flutes across their size range, so no per-family
+ *   constant could be true of every row. Kennametal's taps publish a `Z`
+ *   column and keep filling it;
+ * - the **drill's `SIG`**, for the one EMUGE-FRANKEN drill whose point-angle
+ *   cell is empty. This one is a hole in a column the vendor otherwise fills,
+ *   not a column it never had, and it is the reason the key had to move: the
+ *   EMUGE drill family reads `SIG` from a column rather than from a fact, so
+ *   a single blank cell refused the row, and `registry.toRecords` maps a
+ *   family's rows together — 2,669 drills were lost to the 2,670th. Every
+ *   Kennametal drill supplies `SIG` from a fact and none can be absent.
+ *
+ * A point angle is not a field to guess at. It sets the drill tip's length, so
+ * a CAM system that assumed 140 deg for a part ground at 118 would cut a hole
+ * to the wrong depth — an absence a consumer must check for is recoverable and
+ * a plausible wrong number is not.
+ */
+export declare const RECORD_GEOMETRY: Record<ToolKind, {
+    readonly always: readonly GeometryName[];
+    readonly sometimes: readonly GeometryName[];
+}>;
 /**
  * One orderable cutting tool, in canonical fields, ready for the core.
  *
@@ -193,23 +273,134 @@ export declare const DIMENSIONAL_COLUMNS: ReadonlySet<GeometryName>;
  * it and hands it over, and a mapper that mutated one would be reaching back
  * across the seam this type exists to draw.
  *
- * `geometry` holds {@link GEOMETRY_FIELDS} names in `unit`. An **empty**
- * `materialGroups` is a real answer — Kennametal indexes no tap by workpiece
- * material, so all 129 carry none, and reading empty as "unconstrained" would
- * put every tap under every material on no evidence.
+ * `geometry` holds {@link GEOMETRY_FIELDS} names in `unit`.
+ *
+ * ## The workpiece-material groups have three states, not two
+ *
+ * They were `string[]` until this contract, and an empty array carried two
+ * incompatible claims at once. Kennametal's 129 taps are empty because the
+ * vendor's own index rates them for nothing; every Harvey part was empty
+ * because Harvey publishes no index a scrape can reach, and a Kennametal family
+ * whose material sweep was never run was empty for a third reason. A consumer
+ * reading the first as "not rated for steel" is right and reading the second
+ * the same way is wrong, and nothing in the record told the two apart.
+ *
+ * So:
+ *
+ * - **`null`, labelled {@link UNSPECIFIED}** — we do not know what this tool is
+ *   for. Not indexed, not published, or not swept. Says nothing about what it
+ *   cuts, and is not a claim that it cuts nothing.
+ * - **`[]`** — the vendor's index exists and rates this part for nothing.
+ * - **non-empty** — rated, in {@link ISO_MATERIAL_GROUPS} order.
+ *
+ * {@link ToolRecord.materialGroupsSource} is never absent: it is `unspecified`
+ * in the first case and, in the other two, how the answer was arrived at in the
+ * same vocabulary a family fact uses — `vendor-stated` where the vendor's own
+ * index said so, `derived` where this package computed it. A consumer that will
+ * not act on a guess filters on it, and one that will not show an unknown as an
+ * empty facet filters on it too.
  */
 export interface ToolRecord {
+    /**
+     * The brand key the record was minted under — `identity.BRANDS`'s own key,
+     * not the display name.
+     *
+     * Here because {@link ToolRecord.guid} is the join key for every downstream
+     * consumer and it is minted in this brand's namespace: without the key on
+     * the record, the guid is underivable from the record and `vendor` is a
+     * display string nothing can look a namespace up by.
+     */
+    readonly brand: BrandName;
+    /** What this brand's records call the vendor — `identity.BRANDS[brand].vendor`. */
     readonly vendor: string;
+    /**
+     * `identity.recordGuid(brand, materialNumber)`, minted by {@link toolRecord}
+     * rather than by an adapter: one mint path is what makes a guid collision
+     * across brands structurally impossible instead of merely unlikely.
+     */
+    readonly guid: string;
     readonly materialNumber: string;
     readonly catalogNumber: string;
+    /**
+     * The vendor's own free text about this part, verbatim — `''` where the
+     * vendor publishes none.
+     *
+     * **Never a copy of another field on this record.** It was
+     * `row['ISO Catalog Number']` on every Kennametal drill and end mill until
+     * 2026-08-29, which put the catalog number in two fields and told a consumer
+     * nothing it did not already have: a search index built on it matched a part
+     * number and no words. Kennametal publishes no description column, so the
+     * honest answer is the empty string — the same rule {@link ToolRecord.coating}
+     * already states for a table that publishes no coating.
+     *
+     * **It may be per product line rather than per part.** Harvey states one
+     * title for a whole page and no per-part text, so every record of a Harvey
+     * family carries that family's title. That is what the vendor published; a
+     * consumer that needs a per-part string has `catalogNumber`.
+     */
     readonly description: string;
+    /**
+     * The vendor's own name for the product line this part belongs to —
+     * `FRANKEN TOP-Cut`, `MultiDRILL`, `KenCut™ FF`, `Viper` — or `null` where
+     * the vendor names none.
+     *
+     * **Null is the vendor's silence, not an empty name**, the same three-state
+     * reasoning {@link ToolRecord.materialGroups} makes with {@link UNSPECIFIED}
+     * and for the same reason: a consumer faceting a catalog by product line has
+     * to be able to tell "EMUGE calls this Alu-Cut" from "nobody has decided what
+     * Harvey's line is called", and `''` collapses the two.
+     *
+     * **Verbatim, and never inferred** — the {@link ToolRecord.coating} rule.
+     * EMUGE's own index says `FRANKEN Expert` for the eight end mills its
+     * marketing calls "Cut & Form", and Destiny Tool ships `viper-mini` and
+     * `python` beside `Viper` and `Raptor`; case-folding either here would be
+     * this package authoring a vendor's catalog. The one thing an adapter may do
+     * is map a vendor's *code* onto that same vendor's *own* published name for
+     * it — see `vendors/emuge/records.ts`'s `PRODUCT_LINES`, where both sides of
+     * every entry are EMUGE's and the article page each name came from is cited.
+     *
+     * **Where it comes from is a fact about the vendor's data, not a convention.**
+     * Three sources are in use and each is the only one its vendor offers: a
+     * scraped column read per part (EMUGE, Destiny Tool), a page title fetched
+     * per family (Kennametal, WIDIA), and nothing at all (Harvey Tool, whose
+     * product-line title is already this record's `description` — a second copy
+     * of one string is the thing that field's own docstring refuses).
+     *
+     * **Never a copy of another field on this record**, for the reason
+     * {@link ToolRecord.description} states it.
+     */
+    readonly productLine: string | null;
     readonly kind: ToolKind;
     readonly unit: UnitSystem;
     readonly substrate: string;
-    readonly grade: string;
-    readonly geometry: Readonly<Partial<Record<GeometryName, number | boolean>>>;
+    /**
+     * The vendor's own coating string, `''` where the table publishes none.
+     *
+     * Raw, and never inferred from: `AlTiN COATED`, `TiN` and a Destiny Tool
+     * coating id are three vendors' vocabularies, and mapping them onto a shared
+     * one here would be this package inventing a standard rather than recording
+     * what was published.
+     */
+    readonly coating: string;
+    /**
+     * The canonical geometry, in {@link ToolRecord.unit}.
+     *
+     * Numbers only. It was `number | boolean` until 2026-08-29 and no adapter has
+     * ever put a boolean in one — {@link GEOMETRY_FIELDS} defines no boolean
+     * field — so the width bought nothing and cost every consumer a narrowing
+     * before it could do arithmetic on `geometry.DC`.
+     *
+     * **Which keys are present is stated per kind, not left to the mapper**: see
+     * {@link RECORD_GEOMETRY}. An absent key is a claim, and it is the vendor's
+     * silence rather than a gap — the same distinction
+     * {@link ToolRecord.materialGroups} draws with {@link UNSPECIFIED}.
+     */
+    readonly geometry: Readonly<Partial<Record<GeometryName, number>>>;
     readonly coolantThrough: boolean;
-    readonly materialGroups: readonly string[];
+    /** ISO 513 main groups in {@link ISO_MATERIAL_GROUPS} order — see above. */
+    readonly materialGroups: readonly string[] | null;
+    /** How the groups were arrived at. {@link UNSPECIFIED} exactly when they are null. */
+    readonly materialGroupsSource: MaterialGroupsSource;
     /**
      * Drills only, and deliberately `null` elsewhere rather than `false`: it
      * drops the two ferrous presets downstream, and a default would ship them on
@@ -218,20 +409,31 @@ export interface ToolRecord {
     readonly nonFerrous: boolean | null;
 }
 /**
- * Build a {@link ToolRecord}, defaulting the two fields that have a meaningful
- * absence.
+ * Build a {@link ToolRecord}: mint its guid, default the fields that have a
+ * meaningful absence, and refuse the one state that cannot be true.
  *
  * An interface cannot carry a default, and requiring every adapter to write
- * `materialGroups: []` would put the decision back in the three places least
+ * `materialGroups: null` would put the decision back in the three places least
  * able to notice it was wrong. They stay **required on the type** so a
  * consumer reading a record never handles `undefined` — only the construction
- * is optional.
+ * is optional. The default is `null`/{@link UNSPECIFIED} and not `[]`, because
+ * an adapter that says nothing about workpiece materials has produced no
+ * evidence, which is the one thing the three-state rule exists to distinguish.
+ *
+ * `guid` is not an input at all. Every adapter minting it would be three
+ * copies of `recordGuid(brand, materialNumber)` to drift, on the value that is
+ * the join key for every downstream consumer.
+ *
+ * The geometry is checked against {@link RECORD_GEOMETRY} before anything is
+ * built, so a kind's shape is one table rather than a convention three mappers
+ * each keep separately. That is the same move the material-groups invariant
+ * below makes: the factory is where a record's shape can be refused once.
  *
  * The result is frozen, geometry and material groups included: a record is an
  * interchange value, and a mapper that mutated one would be reaching back
  * across the seam this type exists to draw.
  */
-export declare function toolRecord(fields: Omit<ToolRecord, 'materialGroups' | 'nonFerrous'> & Partial<Pick<ToolRecord, 'materialGroups' | 'nonFerrous'>>): ToolRecord;
+export declare function toolRecord(fields: Omit<ToolRecord, 'guid' | 'materialGroups' | 'materialGroupsSource' | 'nonFerrous' | 'productLine'> & Partial<Pick<ToolRecord, 'materialGroups' | 'materialGroupsSource' | 'nonFerrous' | 'productLine'>>): ToolRecord;
 /**
  * A family's canonical-field → CSV-column-label mapping, validated.
  *

package/dist/records.js

@@ -44,6 +44,7 @@
  */
 import { dimensionalColumn } from './conventions.js';
 import { ScraperConfigError } from './errors.js';
+import { recordGuid } from './identity.js';
 /**
  * ISO 513's main workpiece-material groups, in the order every vendor's
  * material groups must agree on — **core, not a Kennametal fact**, the same
@@ -55,6 +56,23 @@ import { ScraperConfigError } from './errors.js';
  * and a tool's own list from another has no way to notice the two disagree.
  */
 export const ISO_MATERIAL_GROUPS = ['P', 'M', 'K', 'N', 'S', 'H', 'C'];
+/**
+ * The material-groups label for **we do not know what this tool is for**.
+ *
+ * Not an ISO 513 group and deliberately not one of {@link ISO_MATERIAL_GROUPS}:
+ * it is a statement about this package's evidence, not about the tool. It sits
+ * in {@link ToolRecord.materialGroupsSource} rather than in the group list,
+ * because a consumer filtering a catalog down to "cuts steel" must not have to
+ * know that one of the letters is not a letter.
+ *
+ * **Why a label and not a bare `null`.** The absence was expressible before —
+ * `materialGroups === null` — and an absence is the one thing a reader has to
+ * interpret. Every Harvey part is here, and so is every Kennametal family whose
+ * material sweep has not been run: two different reasons for the same honest
+ * answer, and neither is "rated for nothing". A named value says that out loud
+ * in a UI, a log line and a filter, which `null` never does.
+ */
+export const UNSPECIFIED = 'unspecified';
 /**
  * Canonical geometry fields an adapter may supply, and what each means.
  *
@@ -158,25 +176,142 @@ export const DIMENSIONAL = new Set([
  */
 export const DIMENSIONAL_COLUMNS = new Set([...DIMENSIONAL].filter((name) => name !== 'TP'));
 /**
- * Build a {@link ToolRecord}, defaulting the two fields that have a meaningful
- * absence.
+ * What geometry a **record** of each kind carries, as against what a family
+ * must map.
+ *
+ * {@link REQUIRED_GEOMETRY} is about columns: it refuses a family whose config
+ * maps no `LCF`. This is about the record that comes out the other end, and the
+ * two genuinely differ — a Kennametal drill's `NOF` and `SIG` come from facts
+ * and not from any column, so they can never appear in a column map and are
+ * always on the record.
+ *
+ * **`sometimes` is the point of the table.** An absent key was the one thing in
+ * a record a reader had to interpret: `geometry.NOF === undefined` means "Harvey
+ * publishes no flute count for this family" on an end mill and "not part of the
+ * contract" on a drill, and nothing said which. That is exactly the ambiguity
+ * {@link UNSPECIFIED} exists to remove from {@link ToolRecord.materialGroups},
+ * and the record shipped both encodings at once. Now the absence is declared:
+ * a key in `sometimes` may be missing and its absence is the vendor's silence;
+ * a key in neither list is not part of that kind's record at all.
+ *
+ * Every `sometimes` entry today is one vendor publishing nothing where another
+ * publishes a number. `sometimes` permits the key, it does not forbid it — the
+ * vendors that state these keep filling them.
+ *
+ * - the **end mill's `NOF`**, for Harvey's two deburring families — they
+ *   publish right- and left-hand tooth counts and no flute count, so there is
+ *   nothing to read and 0 is not a substitute;
+ * - the **tap's `NOF`**, for EMUGE-FRANKEN, which states no flute count
+ *   anywhere a scrape can reach — not on the grouped product, the variant
+ *   listing, the per-part detail record or any facet — while its own tap
+ *   families run 2, 3 and 4 flutes across their size range, so no per-family
+ *   constant could be true of every row. Kennametal's taps publish a `Z`
+ *   column and keep filling it;
+ * - the **drill's `SIG`**, for the one EMUGE-FRANKEN drill whose point-angle
+ *   cell is empty. This one is a hole in a column the vendor otherwise fills,
+ *   not a column it never had, and it is the reason the key had to move: the
+ *   EMUGE drill family reads `SIG` from a column rather than from a fact, so
+ *   a single blank cell refused the row, and `registry.toRecords` maps a
+ *   family's rows together — 2,669 drills were lost to the 2,670th. Every
+ *   Kennametal drill supplies `SIG` from a fact and none can be absent.
+ *
+ * A point angle is not a field to guess at. It sets the drill tip's length, so
+ * a CAM system that assumed 140 deg for a part ground at 118 would cut a hole
+ * to the wrong depth — an absence a consumer must check for is recoverable and
+ * a plausible wrong number is not.
+ */
+export const RECORD_GEOMETRY = {
+    drill: {
+        always: ['DC', 'SFDM', 'OAL', 'LCF', 'NOF'],
+        sometimes: ['SIG'],
+    },
+    tap: {
+        always: ['DC', 'TP', 'SFDM', 'OAL', 'LCF'],
+        sometimes: ['NOF'],
+    },
+    endmill: {
+        always: ['DC', 'RE', 'SFDM', 'OAL', 'LCF', 'shoulder-length', 'shoulder-diameter'],
+        sometimes: ['NOF'],
+    },
+};
+/**
+ * Refuse a record whose geometry does not match its kind's declared shape.
+ *
+ * Two failures, and the second is the one worth having: a key the kind does not
+ * declare at all means a mapper is writing a measurement into a record nothing
+ * downstream expects to find there, which is invisible until a consumer does
+ * not read it.
+ */
+function checkGeometry(kind, what, geometry) {
+    const { always, sometimes } = RECORD_GEOMETRY[kind];
+    const present = new Set(Object.keys(geometry));
+    const missing = always.filter((name) => !present.has(name));
+    if (missing.length > 0) {
+        throw new ScraperConfigError(what, `a ${kind} record carries ${missing.join(', ')} and this one does not — ` +
+            `a field a kind always has is not a field a mapper may skip`);
+    }
+    const declared = new Set([...always, ...sometimes]);
+    const extra = [...present].filter((name) => !declared.has(name)).sort();
+    if (extra.length > 0) {
+        throw new ScraperConfigError(what, `a ${kind} record does not carry ${extra.join(', ')} — ` +
+            `add it to RECORD_GEOMETRY before a mapper writes one`);
+    }
+}
+/**
+ * Build a {@link ToolRecord}: mint its guid, default the fields that have a
+ * meaningful absence, and refuse the one state that cannot be true.
  *
  * An interface cannot carry a default, and requiring every adapter to write
- * `materialGroups: []` would put the decision back in the three places least
+ * `materialGroups: null` would put the decision back in the three places least
  * able to notice it was wrong. They stay **required on the type** so a
  * consumer reading a record never handles `undefined` — only the construction
- * is optional.
+ * is optional. The default is `null`/{@link UNSPECIFIED} and not `[]`, because
+ * an adapter that says nothing about workpiece materials has produced no
+ * evidence, which is the one thing the three-state rule exists to distinguish.
+ *
+ * `guid` is not an input at all. Every adapter minting it would be three
+ * copies of `recordGuid(brand, materialNumber)` to drift, on the value that is
+ * the join key for every downstream consumer.
+ *
+ * The geometry is checked against {@link RECORD_GEOMETRY} before anything is
+ * built, so a kind's shape is one table rather than a convention three mappers
+ * each keep separately. That is the same move the material-groups invariant
+ * below makes: the factory is where a record's shape can be refused once.
  *
  * The result is frozen, geometry and material groups included: a record is an
  * interchange value, and a mapper that mutated one would be reaching back
  * across the seam this type exists to draw.
  */
 export function toolRecord(fields) {
+    const groups = fields.materialGroups ?? null;
+    const source = fields.materialGroupsSource ?? UNSPECIFIED;
+    // An adapter that has nothing to say about the product line says nothing;
+    // `''` would be a name and there is no nameless line. Optional here and
+    // required on the type for the reason stated above — a consumer reading a
+    // record never handles `undefined`.
+    const line = fields.productLine ?? null;
+    if (line === '') {
+        throw new ScraperConfigError(fields.materialNumber, `productLine is the empty string — a vendor that names no product line ` +
+            `is null, which is the state a consumer can tell from a name`);
+    }
+    // The invariant is what keeps the three states three: groups labelled
+    // `unspecified` are groups nobody stated, and an attributed source with no
+    // groups attributes nothing. Either would land as a record whose material
+    // index reads as the opposite of what the adapter meant.
+    if ((groups === null) !== (source === UNSPECIFIED)) {
+        throw new ScraperConfigError(fields.materialNumber, `materialGroups is ${groups === null ? 'null' : JSON.stringify([...groups])} ` +
+            `and materialGroupsSource is ${JSON.stringify(source)} — ` +
+            `groups are ${JSON.stringify(UNSPECIFIED)} exactly when there are none`);
+    }
+    checkGeometry(fields.kind, fields.materialNumber, fields.geometry);
     return Object.freeze({
         ...fields,
+        guid: recordGuid(fields.brand, fields.materialNumber),
         geometry: Object.freeze({ ...fields.geometry }),
-        materialGroups: Object.freeze([...(fields.materialGroups ?? [])]),
+        materialGroups: groups === null ? null : Object.freeze([...groups]),
+        materialGroupsSource: source,
         nonFerrous: fields.nonFerrous ?? null,
+        productLine: line,
     });
 }
 /**

package/dist/registry.d.ts

@@ -26,7 +26,9 @@
  * key. What changes is only *when* — first use rather than import — and every
  * entry point into this package goes through here.
  */
-import type { BoundFamily, BoundToolholding, RecordMappers } from './family.js';
+import { type BoundFamily, type BoundToolholding, type RecordMappers } from './family.js';
+import { type ToolRecord } from './records.js';
+import { type MapperOptions, type ScrapeResult } from './scrape.js';
 /**
  * Brand -> its row-to-record mappers, by tool kind.
  *
@@ -53,6 +55,59 @@ export declare function boundFamilies(): Map<string, BoundFamily>;
 export declare function boundToolholding(): Map<string, BoundToolholding>;
 /** One bound cutting-tool family by CSV name. */
 export declare function boundFamily(name: string): BoundFamily;
+/**
+ * One family's scrape, as {@link ToolRecord}s — the package's uniform output.
+ *
+ * **This is what a consumer wants and what nothing shipped until now.** Every
+ * CLI command ends at a vendor-labelled CSV, and a CSV is the receipt: four
+ * vendors, four column vocabularies, and a `D1_mm` that means one thing in
+ * Kennametal's table and another in ISO 13399's dictionary. The adapters that
+ * resolve that have been here the whole time and only the tests called them.
+ *
+ * It lives in the registry rather than beside `toolRecord` because it needs
+ * both halves — the config table and the vendor mappers — and the main entry
+ * point deliberately imports no vendor. Reach it through the `./registry`
+ * subpath.
+ *
+ * The two checks run **before the first row**, in the order a failure is
+ * cheapest to read:
+ *
+ * 1. {@link checkIdentityColumns} — a re-scrape whose part-number column was
+ *    renamed still parses, still has the right row count, and mints every guid
+ *    off an empty string.
+ * 2. {@link checkColumnsExist} — a mapped column the CSV does not carry names
+ *    the family and the field here, instead of naming one row out of ninety-three
+ *    from inside a mapper.
+ *
+ * `familyName` is the CSV filename the catalog is keyed by
+ * (`'harvey_endmill_025.csv'`), which is what `boundFamily` takes.
+ *
+ * ## One incomplete part does not end the family
+ *
+ * The rows are mapped together, so until 2026-09-01 every refusal was equally
+ * fatal — and the refusals are not equal. A part the vendor left a required
+ * cell blank on is one bad row among thousands of good ones; EMUGE-FRANKEN
+ * omits `overall length l₁` on roughly 175 of its 7,021 end mill variants, and
+ * both end mill families converted to nothing at all because of them.
+ *
+ * So an {@link IncompletePartError} is warned about and the row is dropped.
+ * **Nothing else is.** A cutting material with no mapping, a column a family
+ * stopped mapping, a response that changed shape — those say the vendor's
+ * vocabulary or this package's catalog has moved, and a scraper that skipped
+ * quietly past them would publish a catalog nobody checked. `columns.required`
+ * is the only place that raises the skippable one.
+ *
+ * A dropped row is **not** a relaxed contract. `records.RECORD_GEOMETRY` still
+ * says an end mill always has an `OAL`, and every record returned here still
+ * has one: the part without it becomes no record rather than a record with a
+ * hole. Where a vendor genuinely never publishes a field, `sometimes` is still
+ * the answer — a drill's `SIG` is that, and it stays that.
+ *
+ * The count of what was dropped is not returned. A caller that needs it has
+ * the row count it passed in and the length it got back, and the warnings name
+ * every part by number.
+ */
+export declare function toRecords(familyName: string, scrape: ScrapeResult, options?: MapperOptions): ToolRecord[];
 /**
  * Forget what has been bound.
  *

package/dist/registry.js

@@ -26,11 +26,16 @@
  * key. What changes is only *when* — first use rather than import — and every
  * entry point into this package goes through here.
  */
+import { checkIdentityColumns } from './conventions.js';
+import { familyBrand, } from './family.js';
 import { COLLET_FAMILIES, FAMILIES, HOLDER_FAMILIES } from './families/index.js';
-import { ScraperConfigError } from './errors.js';
+import { IncompletePartError, ScraperConfigError } from './errors.js';
 import { checkFact } from './provenance.js';
-import { checkColumnMap } from './records.js';
+import { checkColumnMap, checkColumnsExist } from './records.js';
+import { consoleWarn } from './scrape.js';
 import { RECORD_MAPPERS as DESTINYTOOL } from './vendors/destinytool/records.js';
+import { RECORD_MAPPERS as EMUGE } from './vendors/emuge/records.js';
+import { RECORD_MAPPERS as HARVEY } from './vendors/harvey/records.js';
 import { RECORD_MAPPERS as KENNAMETAL } from './vendors/kennametal/records.js';
 /**
  * Brand -> its row-to-record mappers, by tool kind.
@@ -45,6 +50,8 @@ export const ADAPTERS = {
     kennametal: KENNAMETAL,
     widia: KENNAMETAL,
     destinytool: DESTINYTOOL,
+    harvey: HARVEY,
+    emuge: EMUGE,
 };
 /**
  * Check every fact of one family and project its value onto the config under
@@ -132,6 +139,76 @@ export function boundFamily(name) {
     }
     return cfg;
 }
+/**
+ * One family's scrape, as {@link ToolRecord}s — the package's uniform output.
+ *
+ * **This is what a consumer wants and what nothing shipped until now.** Every
+ * CLI command ends at a vendor-labelled CSV, and a CSV is the receipt: four
+ * vendors, four column vocabularies, and a `D1_mm` that means one thing in
+ * Kennametal's table and another in ISO 13399's dictionary. The adapters that
+ * resolve that have been here the whole time and only the tests called them.
+ *
+ * It lives in the registry rather than beside `toolRecord` because it needs
+ * both halves — the config table and the vendor mappers — and the main entry
+ * point deliberately imports no vendor. Reach it through the `./registry`
+ * subpath.
+ *
+ * The two checks run **before the first row**, in the order a failure is
+ * cheapest to read:
+ *
+ * 1. {@link checkIdentityColumns} — a re-scrape whose part-number column was
+ *    renamed still parses, still has the right row count, and mints every guid
+ *    off an empty string.
+ * 2. {@link checkColumnsExist} — a mapped column the CSV does not carry names
+ *    the family and the field here, instead of naming one row out of ninety-three
+ *    from inside a mapper.
+ *
+ * `familyName` is the CSV filename the catalog is keyed by
+ * (`'harvey_endmill_025.csv'`), which is what `boundFamily` takes.
+ *
+ * ## One incomplete part does not end the family
+ *
+ * The rows are mapped together, so until 2026-09-01 every refusal was equally
+ * fatal — and the refusals are not equal. A part the vendor left a required
+ * cell blank on is one bad row among thousands of good ones; EMUGE-FRANKEN
+ * omits `overall length l₁` on roughly 175 of its 7,021 end mill variants, and
+ * both end mill families converted to nothing at all because of them.
+ *
+ * So an {@link IncompletePartError} is warned about and the row is dropped.
+ * **Nothing else is.** A cutting material with no mapping, a column a family
+ * stopped mapping, a response that changed shape — those say the vendor's
+ * vocabulary or this package's catalog has moved, and a scraper that skipped
+ * quietly past them would publish a catalog nobody checked. `columns.required`
+ * is the only place that raises the skippable one.
+ *
+ * A dropped row is **not** a relaxed contract. `records.RECORD_GEOMETRY` still
+ * says an end mill always has an `OAL`, and every record returned here still
+ * has one: the part without it becomes no record rather than a record with a
+ * hole. Where a vendor genuinely never publishes a field, `sometimes` is still
+ * the answer — a drill's `SIG` is that, and it stays that.
+ *
+ * The count of what was dropped is not returned. A caller that needs it has
+ * the row count it passed in and the length it got back, and the warnings name
+ * every part by number.
+ */
+export function toRecords(familyName, scrape, options) {
+    const cfg = boundFamily(familyName);
+    const warn = options?.warn ?? consoleWarn;
+    checkIdentityColumns(familyBrand(cfg), scrape.header);
+    checkColumnsExist(familyName, cfg, scrape.header);
+    const records = [];
+    for (const row of scrape.rows) {
+        try {
+            records.push(cfg.records(row, cfg, cfg.columns, options));
+        }
+        catch (error) {
+            if (!(error instanceof IncompletePartError))
+                throw error;
+            warn(`  WARNING: ${error.message} — no record written for it`);
+        }
+    }
+    return records;
+}
 /**
  * Forget what has been bound.
  *

package/dist/scrape.d.ts

@@ -49,6 +49,21 @@ export interface MapperOptions {
 }
 /** The default: stderr, where a message nobody injected a sink for belongs. */
 export declare const consoleWarn: Warn;
+/**
+ * Rows to the header they imply: the union of their keys, in first-seen order.
+ *
+ * A union rather than the first row's keys, and the reason is the same for both
+ * vendors that build a `ScrapeResult` this way. A REGO-FIX collet family is
+ * mixed-unit — `D1_mm` on its metric rows and `D1_in` on its inch ones — and a
+ * MariTool CSV mixes three holder styles, so which spec keys a part publishes is
+ * a function of its style. Keying off row one drops whichever came second.
+ *
+ * It lived in both adapters, byte for byte, until 2026-08-29. Building the
+ * header of a {@link ScrapeResult} is this module's business rather than any
+ * manufacturer's — the same call `pause` and `conventions.CAD_COLUMN` already
+ * got, and the one `tests/vendor-boundary.test.ts` now makes automatically.
+ */
+export declare function unionHeader(rows: readonly ScrapedRow[]): string[];
 /**
  * Milliseconds between requests, wherever a scrape or a mirror loops.
  *