@toolpath/tool-scraper 2.1.0 → 2.3.0

package/dist/node/cad-mirror.js

@@ -28,19 +28,25 @@
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { CAD_COLUMN } from '../conventions.js';
+import { CAD_COLUMN, CAD_DXF_COLUMN, catalogColumn } from '../conventions.js';
 import { REQUEST_DELAY_MS, consoleWarn, pause } from '../scrape.js';
 /**
- * A catalog number as one path segment.
+ * What one part's mirrored STEP model is called.
  *
  * REGO-FIX's catalog number is the vendor's own title — `BT 30 / PG 25 x 075`
  * — and a separator in it was being honoured as one: `downloadStep` creates
  * the parent directory, so the file landed in a `BT 30 ` subdirectory instead
  * of flat in `outDir`, against what this module promises. The number stays
  * readable, which is the whole reason the file is named for it.
+ *
+ * **Exported because two things now resolve it**, and two answers to "what is
+ * this part's file called" is one too many — the same argument
+ * {@link cadCoverage} makes for counting the column here. `node/holder-import.ts`
+ * reads back what this writes, and a mirror that flattened a separator while a
+ * reader did not would report every REGO-FIX holder as unmirrored.
  */
-function fileName(catalogNumber) {
-    return catalogNumber.replaceAll(/[/\\]/g, '-');
+export function stepFileName(catalogNumber) {
+    return `${catalogNumber.replaceAll(/[/\\]/g, '-')}.stp`;
 }
 /** One STEP file onto disk. Returns the bytes written. */
 export async function downloadStep(fetcher, url, dest) {
@@ -52,6 +58,36 @@ export async function downloadStep(fetcher, url, dest) {
     writeFileSync(dest, data);
     return data.byteLength;
 }
+/**
+ * What a mirror of these rows would and would not get, without asking for any
+ * of it.
+ *
+ * **This is the number that bounds anything built on measured geometry**, and
+ * it is worth knowing before the download rather than after: two of the three
+ * toolholding vendors publish a STEP model for every part, and MariTool — which
+ * is 527 of the 601 holder rows — publishes one for about two thirds. A
+ * pipeline scoped against 601 and run against 431 is a surprise at the end.
+ *
+ * Counted here rather than in the CLI because it is the same column read the
+ * same way {@link mirrorFamilySteps} reads it, and two answers to "does this row
+ * have a model" is one too many. Pure, and it makes no requests.
+ *
+ * **The DXF is counted and is not a fallback.** `conventions.CAD_DXF_COLUMN`
+ * says why the two are different columns: a DXF is a drawing whose datum,
+ * projection and layer semantics are the vendor's business, and deriving a
+ * profile from one is a separate project rather than a way to cover the gap.
+ */
+export function cadCoverage(rows) {
+    let step = 0;
+    let dxf = 0;
+    for (const row of rows) {
+        if ((row[CAD_COLUMN] ?? '').trim())
+            step += 1;
+        if ((row[CAD_DXF_COLUMN] ?? '').trim())
+            dxf += 1;
+    }
+    return { rows: rows.length, step, dxf };
+}
 /**
  * Every STEP model a holder scrape names, into `outDir`, one file per row.
  *
@@ -59,6 +95,16 @@ export async function downloadStep(fetcher, url, dest) {
  * filename is what a human reads and `BT30ER16060M` says what the part is
  * where `1258023` does not.
  *
+ * **`brand` is what says which column that number is in, and it is an argument
+ * rather than a guess.** This read `row['ISO Catalog Number']` until 2026-09-02,
+ * which is Kennametal's pair and REGO-FIX's adopted copy of it. MariTool
+ * publishes one number per part, under `Material Number`, and no catalog
+ * designation at all — `conventions.IDENTITY_DEVIATIONS` records why — so every
+ * one of its 357 published models was skipped with a warning saying the row had
+ * no catalog number to name it. `conventions.catalogColumn` is the lookup, and
+ * it is a lookup rather than a fallback down a list of candidate columns for the
+ * reason stated there.
+ *
  * **`outDir` is a required argument and never inferred.** These files are a
  * local working copy, they are gitignored, and a default that pointed into a
  * tracked directory would be the one mistake that silently commits ~3 MB of
@@ -68,21 +114,23 @@ export async function downloadStep(fetcher, url, dest) {
  * `lightweightStepUrl`'s documented null case arriving here — and a skipped
  * row spends no delay, because the count that matters is downloads and a
  * family that is mostly blank should not sleep its way through the gaps.
+ * {@link cadCoverage} is how many of them there will be, before any of it runs.
  */
-export async function mirrorFamilySteps(fetcher, rows, outDir, delayMs = REQUEST_DELAY_MS, warn = consoleWarn) {
+export async function mirrorFamilySteps(fetcher, rows, brand, outDir, delayMs = REQUEST_DELAY_MS, warn = consoleWarn) {
     const written = [];
+    const column = catalogColumn(brand);
     for (const row of rows) {
         const url = (row[CAD_COLUMN] ?? '').trim();
         if (!url)
             continue;
-        const catalogNumber = row['ISO Catalog Number'] ?? '';
+        const catalogNumber = row[column] ?? '';
         if (!catalogNumber) {
-            warn(`  SKIPPED a row with a CAD URL and no catalog number to name it`);
+            warn(`  SKIPPED a row with a CAD URL and no ${column} to name it`);
             continue;
         }
         if (written.length > 0)
             await pause(delayMs);
-        const bytes = await downloadStep(fetcher, url, join(outDir, `${fileName(catalogNumber)}.stp`));
+        const bytes = await downloadStep(fetcher, url, join(outDir, stepFileName(catalogNumber)));
         written.push({ catalogNumber, bytes });
     }
     return written;

package/dist/node/cli.d.ts

@@ -12,6 +12,8 @@
  * toolpath-scrape cad             add the vendor CAD model column
  * toolpath-scrape materials       add the ISO workpiece-group column
  * toolpath-scrape mirror-cad      download the vendor STEP models
+ * toolpath-scrape coverage        report which rows publish a CAD model
+ * toolpath-scrape profiles        measure the mirrored models into profiles
  * ```
  *
  * **One binary with subcommands.** Seven names in `node_modules/.bin` for one
@@ -27,12 +29,13 @@
  * tree.
  */
 import { type Fetcher } from '../fetch.js';
+import { type HolderApi } from './holder-import.js';
 /** Everything the CLI prints, injectable so a test is not stdout. */
 export interface Console_ {
     log: (message: string) => void;
     error: (message: string) => void;
 }
 /** Run one command. Exported so the tests drive it without a subprocess. */
-export declare function run(argv: string[], io?: Console_, fetcher?: Fetcher): Promise<number>;
+export declare function run(argv: string[], io?: Console_, fetcher?: Fetcher, api?: HolderApi): Promise<number>;
 /** The process entry point: run, and turn a refusal into an exit code. */
 export declare function main(argv?: string[]): Promise<number>;

package/dist/node/cli.js

@@ -12,6 +12,8 @@
  * toolpath-scrape cad             add the vendor CAD model column
  * toolpath-scrape materials       add the ISO workpiece-group column
  * toolpath-scrape mirror-cad      download the vendor STEP models
+ * toolpath-scrape coverage        report which rows publish a CAD model
+ * toolpath-scrape profiles        measure the mirrored models into profiles
  * ```
  *
  * **One binary with subcommands.** Seven names in `node_modules/.bin` for one
@@ -26,18 +28,20 @@
  * or an assembly catalog is a different product, and none of it is in this
  * tree.
  */
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { basename, dirname } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import { ScraperConfigError, VendorResponseError } from '../errors.js';
 import { familyBrand } from '../family.js';
 import { ALL_FAMILIES, FAMILIES, HOLDER_FAMILIES, familyConfig } from '../families/index.js';
 import { createFetcher } from '../fetch.js';
+import { buildProfiles } from '../profiles.js';
 import { AEM_BRANDS } from '../identity.js';
-import { boundFamily } from '../registry.js';
+import { boundFamily, toHolding } from '../registry.js';
 import { pause, REQUEST_DELAY_MS } from '../scrape.js';
-import { mirrorFamilySteps } from './cad-mirror.js';
+import { cadCoverage, mirrorFamilySteps } from './cad-mirror.js';
 import { parseCsv, toCsv } from './csv.js';
-import { describeRoot, familyCsv, stepDir } from './paths.js';
+import { API_KEY_ENV, API_URL_ENV, createHolderApi, describeApi, measureFamily, } from './holder-import.js';
+import { describeRoot, familyCsv, profilesDir, profilesJson, stepDir } from './paths.js';
 import * as receipts from './receipts.js';
 import { scrapeFamily } from '../vendors/kennametal/scrape.js';
 import { annotateCadUrls } from '../vendors/kennametal/cad.js';
@@ -59,6 +63,31 @@ import { scrapeCategory } from '../vendors/emuge/scrape.js';
  * that fit nothing.
  */
 const BT30_COLLET_SIZES = ['6', '10', '15', '25'];
+/**
+ * Brand -> the step that fills `conventions.CAD_COLUMN` for it, where the
+ * vendor needs a second request to say where its model is.
+ *
+ * **Two brands are in here and three are deliberately not.** `annotateCadUrls`
+ * is Kennametal's CDS Visual lookup, not a vendor-neutral one: it queries
+ * product-config.net and rewrites the column on every row. Run against a
+ * REGO-FIX holder it would post that vendor's SKUs to Kennametal and blank the
+ * STEP URLs the REGO-FIX scrape had already filled in.
+ *
+ * A brand that is absent is **not** a brand this command refuses. REGO-FIX and
+ * MariTool write the column during the scrape itself, so for them there is
+ * nothing to annotate and the honest answer is to say so and report what the
+ * CSV already carries — see {@link cad}. It exited 2 until 2026-09-02, which
+ * made `cad <every holder family>` impossible to run over a catalog holding
+ * more than one vendor's.
+ *
+ * A table here rather than a check against `AEM_BRANDS`, because being on
+ * Kennametal's AEM platform and having a CAD lookup are two different facts
+ * that happen to coincide across two brands.
+ */
+const CAD_ANNOTATORS = {
+    kennametal: annotateCadUrls,
+    widia: annotateCadUrls,
+};
 const USAGE = `usage: toolpath-scrape <command> [args]
 
   kennametal [--brand kennametal|widia] FAMILY_CODE OUTPUT_CSV [Name=Value ...]
@@ -123,6 +152,20 @@ const USAGE = `usage: toolpath-scrape <command> [args]
       Downloads each row's STEP model into <root>/<brand>/step. Run \`cad\`
       first — a CSV with no CAD column yields nothing and says so.
 
+  profiles HOLDERS.csv [more.csv ...]
+      Measures each mirrored STEP model through the Toolpath Engine API and
+      writes the gage-line profile document — one per family under
+      <root>/<brand>/profiles, plus the merged <root>/profiles.json.
+      Needs ${API_KEY_ENV} set, and ${API_URL_ENV} until the holder routes
+      reach production. Run \`mirror-cad\` first: a holder with no mirrored
+      model is reported and skipped, not measured.
+
+  coverage [HOLDERS.csv ...]
+      Reports how many rows of each holder family publish a STEP model and a
+      DXF. Reads the scraped CSVs and makes no requests at all. With no
+      arguments it reports every holder family, and says which ones have not
+      been scraped on this machine rather than failing on them.
+
 An output path is used verbatim; scraped CSVs belong under the scrape root,
 in <brand>/csv/. The in-place commands take a bare CSV name and resolve it
 through the family's own brand.`;
@@ -183,7 +226,7 @@ function namesIn(argv, known, what) {
     return names;
 }
 /** Run one command. Exported so the tests drive it without a subprocess. */
-export async function run(argv, io = STDOUT, fetcher = createFetcher()) {
+export async function run(argv, io = STDOUT, fetcher = createFetcher(), api) {
     // Somebody reading the usage text is the person most likely to be about to
     // point a scrape at the wrong place, so help gets the root too.
     io.log(describeRoot());
@@ -213,6 +256,10 @@ export async function run(argv, io = STDOUT, fetcher = createFetcher()) {
             return materials(rest, io, fetcher);
         case 'mirror-cad':
             return mirrorCad(rest, io, fetcher);
+        case 'coverage':
+            return coverage(rest, io);
+        case 'profiles':
+            return profiles(rest, io, api);
         default:
             io.error(`unknown command ${JSON.stringify(command)}\n\n${USAGE}`);
             return 2;
@@ -419,25 +466,35 @@ function threadPitch(argv, io) {
     }
     return 0;
 }
+/**
+ * Fill the CAD model column, for the vendors that need a second request to.
+ *
+ * Vendor-dispatched through {@link CAD_ANNOTATORS} rather than gated on
+ * `AEM_BRANDS`. A brand with no annotator is a **no-op with a message**, not a
+ * refusal: its scrape already wrote the column, so there is nothing this
+ * command could add, and exiting 2 on it meant `cad` could not be run across a
+ * catalog holding more than one vendor's holders. `mirror-cad` reads the column
+ * and is neutral; this writes it and is not.
+ */
 async function cad(argv, io, fetcher) {
     if (argv.length === 0) {
         io.error(USAGE);
         return 2;
     }
     for (const name of namesIn(argv, HOLDER_FAMILIES, 'holder')) {
-        // `annotateCadUrls` is Kennametal's CDS lookup, not a vendor-neutral one —
-        // it queries product-config.net and rewrites `CAD_COLUMN` on every row. Run
-        // against a REGO-FIX holder it would post that vendor's SKUs to Kennametal
-        // and blank the STEP URLs the REGO-FIX scrape had already filled in.
-        // `mirror-cad` reads the column and *is* neutral; this writes it and is not.
         const brand = familyBrand(familyConfig(name));
-        if (!AEM_BRANDS.includes(brand)) {
-            io.error(`${name}: the cad step is ${[...AEM_BRANDS].sort().join('/')}-only — ` +
-                `${brand} publishes its own CAD URLs with the scrape`);
-            return 2;
-        }
         const path = familyCsv(name);
-        const { scrape, found } = await annotateCadUrls(fetcher, readCsv(name, path));
+        const annotate = CAD_ANNOTATORS[brand];
+        if (annotate === undefined) {
+            const found = coverageOf(name);
+            io.log(`${name}: nothing to annotate — ${brand} publishes its CAD URLs with ` +
+                `the scrape` +
+                (found === null
+                    ? ' (not scraped on this machine)'
+                    : ` (${found.step} of ${found.rows} rows carry one)`));
+            continue;
+        }
+        const { scrape, found } = await annotate(fetcher, readCsv(name, path));
         writeCsv(path, scrape);
         io.log(`${name}: ${found} CAD models`);
     }
@@ -474,12 +531,129 @@ async function mirrorCad(argv, io, fetcher) {
     for (const name of namesIn(argv, HOLDER_FAMILIES, 'holder')) {
         const path = familyCsv(name);
         const brand = familyBrand(familyConfig(name));
-        const written = await mirrorFamilySteps(fetcher, readCsv(name, path).rows, stepDir(brand), undefined, io.error);
+        const written = await mirrorFamilySteps(fetcher, readCsv(name, path).rows, brand, stepDir(brand), undefined, io.error);
         const total = written.reduce((sum, f) => sum + f.bytes, 0);
         io.log(`${name}: ${written.length} STEP files, ${Math.floor(total / 1024)} KB`);
     }
     return 0;
 }
+/** One family's CAD coverage, or null where it has not been scraped here. */
+function coverageOf(name) {
+    const path = familyCsv(name);
+    if (!existsSync(path))
+        return null;
+    return cadCoverage(parseCsv(readFileSync(path, 'utf8')).rows);
+}
+/**
+ * How much of the holder catalog publishes a model, before anything downloads
+ * one.
+ *
+ * **The one command here that makes no requests and writes no files.** It is
+ * the number that bounds anything built on measured geometry, and it is worth
+ * having before the mirror runs rather than after: MariTool is 527 of the 601
+ * holder rows and publishes a STEP for about two thirds of them.
+ *
+ * A family that has not been scraped on this machine is **reported, not
+ * refused**, even when it was asked for by name. The whole command is a report,
+ * and one absent CSV must not stop it printing the rest — which is exactly the
+ * shape the `cad` step had wrong.
+ */
+function coverage(argv, io) {
+    const names = argv.length === 0
+        ? Object.keys(HOLDER_FAMILIES).sort()
+        : namesIn(argv, HOLDER_FAMILIES, 'holder');
+    const total = { rows: 0, step: 0, dxf: 0 };
+    let counted = 0;
+    for (const name of names) {
+        const found = coverageOf(name);
+        if (found === null) {
+            io.log(`${name}: not scraped on this machine`);
+            continue;
+        }
+        counted += 1;
+        total.rows += found.rows;
+        total.step += found.step;
+        total.dxf += found.dxf;
+        io.log(`${name}: ${describeCoverage(found)}`);
+    }
+    if (counted > 1)
+        io.log(`${counted} families: ${describeCoverage(total)}`);
+    return 0;
+}
+/** One coverage line: the counts, and the STEP share a mirror would get. */
+function describeCoverage(found) {
+    // Guarded rather than assumed: an empty CSV is a scrape that produced a header
+    // and no parts, and a NaN percentage would read as a parsing fault here
+    // instead of as the empty file it is.
+    const share = found.rows === 0 ? '—' : `${Math.round((100 * found.step) / found.rows)}%`;
+    return `${found.rows} rows, ${found.step} STEP (${share}), ${found.dxf} DXF`;
+}
+/**
+ * Measure one holder family's mirrored models into a profiles document.
+ *
+ * **The one command that sends data to Toolpath rather than reading from a
+ * vendor.** The API takes a direct upload of the STEP file — it does not fetch
+ * the vendor's URL itself — so every measurement puts a vendor's binary in
+ * Toolpath object storage, which is why the API base URL is printed beside the
+ * scrape root before anything is uploaded.
+ *
+ * Per family *and* merged, because the two answer different questions: a family
+ * document is what a re-measure of that family replaces, and the merged one is
+ * what a consumer loads. Both are built by `profiles.buildProfiles`, so a guid
+ * that appeared twice would be refused rather than silently overwritten.
+ */
+async function profiles(argv, io, api) {
+    if (argv.length === 0) {
+        io.error(USAGE);
+        return 2;
+    }
+    const names = namesIn(argv, HOLDER_FAMILIES, 'holder');
+    io.log(describeApi());
+    const client = api ?? createHolderApi();
+    const everyMeasurement = [];
+    const everyHolder = [];
+    for (const name of names) {
+        const path = familyCsv(name);
+        const brand = familyBrand(familyConfig(name));
+        // Holders only: a collet publishes no CAD model and is not drawn, because
+        // it sits inside the nut the holder's own profile already includes.
+        const holders = toHolding(name, readCsv(name, path), { warn: io.error });
+        const run = await measureFamily(client, holders, stepDir(brand), undefined, undefined, io.error);
+        if (run.unmirrored.length > 0) {
+            io.log(`${name}: ${run.unmirrored.length} holders publish no mirrored model`);
+        }
+        if (run.failed.length > 0) {
+            io.log(`${name}: ${run.failed.length} imports the kernel refused`);
+        }
+        if (run.measured.length === 0) {
+            io.log(`${name}: nothing measured — run mirror-cad first`);
+            continue;
+        }
+        const document = buildProfiles(run.measured, holders);
+        writeJson(join(profilesDir(brand), `${basename(name, '.csv')}.json`), document);
+        io.log(`${name}: ${describeProfiles(document)}`);
+        everyMeasurement.push(...run.measured);
+        everyHolder.push(...holders);
+    }
+    if (everyMeasurement.length === 0)
+        return 0;
+    const merged = buildProfiles(everyMeasurement, everyHolder);
+    writeJson(profilesJson(), merged);
+    io.log(`${profilesJson()}: ${describeProfiles(merged)}`);
+    return 0;
+}
+/** One profiles line: how many holders, and how many agree with the vendor's L1. */
+function describeProfiles(document) {
+    const complete = Object.values(document.holders).filter((p) => p.complete).length;
+    return (`${document.holderCount} profiles, ${complete} complete ` +
+        `(kernel ${document.kernelVersion}, tolerance ${document.options.tolerance}, ` +
+        `fillBays ${document.options.fillBays})`);
+}
+/** A derived document onto disk, its directory created and a trailing newline on it. */
+function writeJson(path, document) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(document, null, 1)}\n`);
+}
 /** The process entry point: run, and turn a refusal into an exit code. */
 export async function main(argv = process.argv.slice(2)) {
     try {

package/dist/node/holder-import.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Measuring a mirrored holder through the Toolpath Engine API.
+ *
+ * The step between `node/cad-mirror.ts`, which puts a vendor's STEP file on
+ * disk, and `profiles.ts`, which turns a measurement into a drawing's
+ * silhouette. Five calls per holder: create, upload, queue, poll, read.
+ *
+ * **This is what deleted the Fusion dependency.** The pipeline this replaces
+ * could only measure a holder on a machine running Fusion 360 with an MCP
+ * bridge attached to it — roughly 1,800 lines of Python driving a GUI
+ * application. The same numbers now come back in about two seconds over HTTP,
+ * to nanometre agreement, from something that can run in CI.
+ *
+ * ## Why it is in `node/` and not in the library half
+ *
+ * The same three reasons `cad-mirror.ts` gives for itself, and they all hold
+ * here: it reads a mirrored binary off disk, it is a batch job with pacing
+ * rather than a request-scoped call, and it is a maintainer's command rather
+ * than something a backend embeds.
+ *
+ * ## Why it does not go through `fetch.Fetcher`
+ *
+ * `Fetcher` is four GET-and-decode shapes for anonymous vendor endpoints. This
+ * needs a bearer token, a PUT of raw bytes to a presigned URL and a PATCH with
+ * an idempotency header, and widening a public interface every consumer may
+ * have implemented — to serve one maintainer's command — is a break bought for
+ * nothing. So the transport is small and local, and injectable the same way
+ * `fetch.FetcherOptions.fetch` is, which is what lets a test drive the whole
+ * five-call flow with no stack behind it.
+ *
+ * **`@toolpath/api` is deliberately not a dependency.** This package takes one
+ * runtime dependency today and a second is a decision every consumer inherits;
+ * the generated SDK is pinned to `openapi/openapi.json` at v1.1.0, which has no
+ * holder routes at all, so it could not make these calls until that pin moves.
+ *
+ * ## What refuses, and what is survivable
+ *
+ * The split is `holding.ts`'s, for the same reason: a failed **job** is one
+ * holder's model the kernel could not read, so it is an `IncompletePartError`
+ * and {@link measureFamily} warns and drops it — losing a 431-holder batch to
+ * one bad STEP file is not a trade worth making. Anything else — a transport
+ * failure, a non-2xx, a response whose shape this cannot read — is a
+ * `VendorResponseError` and stops the run.
+ */
+import type { HolderRecord } from '../holding.js';
+import type { ImportOptions, MeasuredHolder } from '../profiles.js';
+import { type Warn } from '../scrape.js';
+/** Where the holder routes are. Set it to `http://localhost:4000` for development. */
+export declare const API_URL_ENV = "TOOLPATH_API_URL";
+/**
+ * The bearer token, **from the environment only**.
+ *
+ * Never a flag, never a file path this package reads, never logged, never
+ * written into a receipt and never echoed in an error — an API key that reaches
+ * a terminal reaches a shell history and a CI log with it.
+ */
+export declare const API_KEY_ENV = "TOOLPATH_API_KEY";
+/** Where the API is when nothing says otherwise. */
+export declare const DEFAULT_API_URL = "https://api.toolpath.com";
+/**
+ * The import options this pipeline measures with.
+ *
+ * `tolerance` matches the reference implementation's, and there is deliberately
+ * no segment budget behind it: a real BT30-ER16 is 69 segments at 0.01 mm and
+ * still 51 at 1.0 mm, because those are grooves and thread reliefs rather than
+ * sampling noise, and relaxing toward a budget inflates the holder until the
+ * flange-to-taper step is swallowed and the cone stops being detectable.
+ *
+ * **`fillBays` is off, and that is the fork.** Raising each solid's enclosed
+ * bays to their brims — the V-flange groove, the thread relief — is right for a
+ * collision envelope and wrong for a drawing: the groove and the relief are
+ * what a machinist looks for, so the literal silhouette is the honest thing to
+ * store. The consumer here is `@toolpath/tool-drawing`, so it is off, and the
+ * option is recorded in the document so nothing downstream has to guess which
+ * it got. A second run with it on, for a Fusion collision library, is a later
+ * optional step rather than a fork in this code.
+ *
+ * `flipped` is an override for a holder the automatic orientation reads
+ * backwards, not a setting: the automatic pass reads the 7:24 taper and got
+ * every validated holder right.
+ */
+export declare const DEFAULT_IMPORT_OPTIONS: ImportOptions;
+/** Milliseconds between polls of an import job. Imports finish in about two seconds. */
+export declare const POLL_INTERVAL_MS = 500;
+/** Milliseconds before an import job that never settles is abandoned. */
+export declare const POLL_TIMEOUT_MS = 120000;
+/**
+ * How many times one rate-limited request is retried before the run gives up.
+ *
+ * Generous on purpose: the window the API is asking the client to wait out is
+ * measured in tens of seconds, and the alternative to waiting is abandoning a
+ * batch that has already paid for every holder before this one.
+ */
+export declare const RATE_LIMIT_ATTEMPTS = 6;
+/** What to wait when the API names no `Retry-After` of its own, in milliseconds. */
+export declare const RATE_LIMIT_BACKOFF_MS = 2000;
+/**
+ * How long to wait out a 429, preferring the API's own answer.
+ *
+ * `Retry-After` is in seconds and is the only number that knows when the
+ * window rolls, so it wins wherever it parses. A header that is absent, empty,
+ * or an HTTP-date rather than a delay yields `NaN`, and the fallback grows with
+ * the attempt so a client that cannot read the header still backs off.
+ */
+export declare function retryAfterMs(response: Response, attempt: number): number;
+/** The resolved API base URL, without its trailing slash. */
+export declare function apiUrl(): string;
+/**
+ * One line naming the resolved API base URL and how it was resolved.
+ *
+ * Printed by every command that measures, for the reason `paths.describeRoot`
+ * is printed by every command that scrapes: production is still Engine API
+ * v1.1.0 and carries none of these routes, so a run that went somewhere
+ * surprising should say so on the way rather than be discovered in a 404.
+ */
+export declare function describeApi(): string;
+/** How to reach the API. Every field has an environment or a constant behind it. */
+export interface HolderApiOptions {
+    /** Defaults to {@link apiUrl}. */
+    baseUrl?: string;
+    /** Defaults to `process.env[API_KEY_ENV]`. */
+    apiKey?: string;
+    /** Injectable, so a test drives the five calls with no stack behind them. */
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    /** How many times one rate-limited request is retried. Zero never retries. */
+    rateLimitAttempts?: number;
+}
+/** The transport {@link measureHolder} makes its five calls through. */
+export interface HolderApi {
+    /** One authenticated call to a path under the base URL, decoded as JSON. */
+    call<T>(method: string, path: string, headers?: Record<string, string>): Promise<T>;
+    /** One PUT of raw bytes to a presigned URL, which carries its own authentication. */
+    put(url: string, body: Uint8Array): Promise<void>;
+    readonly pollIntervalMs: number;
+    readonly pollTimeoutMs: number;
+}
+/**
+ * The transport, authenticated and timed out.
+ *
+ * Refuses at construction when no key is set rather than at the first request:
+ * a batch that authenticated per holder would fail on holder one after mirroring
+ * the whole family, and the message would be about a 401 instead of about an
+ * unset variable.
+ */
+export declare function createHolderApi(options?: HolderApiOptions): HolderApi;
+/**
+ * A key that stops one retried queue call dispatching a second import.
+ *
+ * **Keyed on the holder the API just created, not on the catalog number**, and
+ * the distinction is the whole correctness of this function. The API binds a
+ * key to the holder it first saw and refuses a later request that reuses the
+ * key for a different one — `idempotency_key_reused`, 409. {@link measureHolder}
+ * creates a *fresh* holder on every call, so a key derived from the catalog
+ * number is the same string naming a different holder on the second run: the
+ * second measurement of any family 409s on its first part, permanently, for
+ * that organisation. That is what this was doing until 2026-09-02.
+ *
+ * So the scope this can honestly promise is **one run**: a `PATCH` retried
+ * after a transport blip replays the job it already dispatched instead of
+ * queueing a second. It cannot make re-running an interrupted family free — the
+ * earlier docstring claimed that, and the API's own dedupe rule makes it
+ * unreachable, because there is no way to ask for the holder a previous run
+ * created. Resuming cheaply is `profiles.ts`'s job, by not re-measuring what
+ * the store already holds.
+ *
+ * The options stay in the key: the same holder imported at two tolerances is
+ * two different measurements and must not deduplicate to one.
+ */
+export declare function idempotencyKey(holderId: string, options: ImportOptions): string;
+/**
+ * A `HolderResponse` as the fields a profile needs, and nothing else.
+ *
+ * **The one place the API's shape is read**, so a route that changes fails here
+ * naming the field rather than as an undefined three transforms downstream. The
+ * quality signals it drops — `axisAreaFraction`, `faceCount`, `sampleCount` —
+ * are read and reported by {@link measureFamily} rather than carried, because
+ * they say something about a run and nothing about the shape of the holder.
+ */
+export declare function parseHolderResponse(body: unknown, part: {
+    brand: MeasuredHolder['brand'];
+    catalogNumber: string;
+}): MeasuredHolder;
+/**
+ * One mirrored STEP file, measured.
+ *
+ * The five calls of the contract, in order, with the poll in the middle: create
+ * a holder and take its presigned upload URL, PUT the bytes, queue the import,
+ * wait for the job, read the result.
+ *
+ * Polling rather than the job's SSE stream, because a batch of 431 wants a
+ * simple loop and every validated import settled in about two seconds.
+ */
+export declare function measureHolder(api: HolderApi, part: {
+    brand: MeasuredHolder['brand'];
+    catalogNumber: string;
+}, step: Uint8Array, options?: ImportOptions): Promise<MeasuredHolder>;
+/** One holder's mirrored STEP file, or null where the vendor published none. */
+export declare function readMirroredStep(stepRoot: string, catalogNumber: string): Uint8Array | null;
+/** What one family's measurement run produced, and what it did not. */
+export interface MeasuredFamily {
+    readonly measured: MeasuredHolder[];
+    /** Holders whose STEP file is not mirrored on this machine. */
+    readonly unmirrored: string[];
+    /** Holders whose import the kernel refused. */
+    readonly failed: string[];
+}
+/**
+ * Every holder of one family that has a mirrored model, measured, paced.
+ *
+ * **A holder with no mirrored file is counted, not failed.** MariTool publishes
+ * no STEP model for about a third of its parts and none at all for its CAT50
+ * line, so an absent file is the ordinary case rather than a fault, and
+ * `cad-mirror.cadCoverage` is what says how many there will be before any of
+ * this runs.
+ *
+ * The pace is the mirror's, and for the same reason: this is a maintainer's
+ * batch against a service, and 431 imports arriving as fast as a loop can issue
+ * them is a different kind of request than one holder being measured.
+ */
+export declare function measureFamily(api: HolderApi, holders: readonly HolderRecord[], stepRoot: string, options?: ImportOptions, delayMs?: number, warn?: Warn): Promise<MeasuredFamily>;