@toolpath/tool-scraper 0.1.0 → 2.0.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,41 @@ 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.
+ *
+ * Both `sometimes` entries today are a flute count nobody publishes:
+ *
+ * - the **end mill's**, 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**, 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: `sometimes` permits the key, it does not forbid it.
+ */
+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 +259,103 @@ 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;
     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 +364,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'> & Partial<Pick<ToolRecord, 'materialGroups' | 'materialGroupsSource' | 'nonFerrous'>>): 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,24 +176,117 @@ 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.
+ *
+ * Both `sometimes` entries today are a flute count nobody publishes:
+ *
+ * - the **end mill's**, 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**, 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: `sometimes` permits the key, it does not forbid it.
+ */
+export const RECORD_GEOMETRY = {
+    drill: {
+        always: ['DC', 'SFDM', 'OAL', 'LCF', 'NOF', 'SIG'],
+        sometimes: [],
+    },
+    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;
+    // 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,
     });
 }

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, ScrapeResult } from './scrape.js';
 /**
  * Brand -> its row-to-record mappers, by tool kind.
  *
@@ -53,6 +55,34 @@ 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.
+ */
+export declare function toRecords(familyName: string, scrape: ScrapeResult, options?: MapperOptions): ToolRecord[];
 /**
  * Forget what has been bound.
  *

package/dist/registry.js

@@ -26,11 +26,15 @@
  * 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 { checkFact } from './provenance.js';
-import { checkColumnMap } from './records.js';
+import { checkColumnMap, checkColumnsExist } from './records.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 +49,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 +138,39 @@ 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.
+ */
+export function toRecords(familyName, scrape, options) {
+    const cfg = boundFamily(familyName);
+    checkIdentityColumns(familyBrand(cfg), scrape.header);
+    checkColumnsExist(familyName, cfg, scrape.header);
+    return scrape.rows.map((row) => cfg.records(row, cfg, cfg.columns, options));
+}
 /**
  * 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.
  *

package/dist/scrape.js

@@ -13,6 +13,30 @@
 export const consoleWarn = (message) => {
     console.warn(message);
 };
+/**
+ * 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 function unionHeader(rows) {
+    const header = [];
+    for (const row of rows) {
+        for (const key of Object.keys(row)) {
+            if (!header.includes(key))
+                header.push(key);
+        }
+    }
+    return header;
+}
 /**
  * Milliseconds between requests, wherever a scrape or a mirror loops.
  *

package/dist/vendors/destinytool/records.d.ts

@@ -94,6 +94,13 @@ export declare function shoulderDiameter(description: string, dc: number): numbe
  * column when populated, or a fallback keyed on flute count when it is not
  * (blank on 423 of 3,898 rows, 2026-08-19).
  *
+ * **The two answers are labelled, not blended.** A populated cell is
+ * `vendor-stated` and the flute-count fallback is `derived`, so a consumer that
+ * will not route a cut off this package's arithmetic can filter on the source
+ * rather than having to know which rows Destiny Tool left blank. Neither is
+ * ever `null`: the fallback covers every blank cell, so this vendor always has
+ * an answer.
+ *
  * The fallback is not a new rule invented for this vendor — it is the split
  * cutting-data presets are routed by downstream (≤3 flutes non-ferrous, >3
  * ferrous), applied here to the material-groups facet instead. Real vendor
@@ -109,10 +116,13 @@ export declare function shoulderDiameter(description: string, dc: number): numbe
  * array and a tool's own list from another has no way to notice the two
  * disagree.
  */
-export declare function materialGroups(row: ScrapedRow, flutes: number): string[];
+export declare function materialGroups(row: ScrapedRow, flutes: number): Pick<ToolRecord, 'materialGroups' | 'materialGroupsSource'>;
 /**
- * A solid end mill, always in inches — Destiny Tool publishes no metric line
- * (the `unit` fact on the family).
+ * A solid end mill, in the family's declared unit.
+ *
+ * Which is inches on the one family there is — Destiny Tool publishes no metric
+ * line — but read from the `unit` fact rather than hardcoded, so the fact stays
+ * the single authored copy the way it is for every other vendor here.
  */
 export declare function endmillRecord(row: ScrapedRow, family: BoundFamily, columns: ColumnMap, options?: MapperOptions): ToolRecord;
 export declare const RECORD_MAPPERS: RecordMappers;