@cutoptim/engine 0.0.1 → 1.0.0

package/dist/types.gen.d.ts

@@ -0,0 +1,1154 @@
+/** One webhook event. Thin on purpose: the plan is read with GET /v1/jobs/{id}, never pushed. */
+export interface WebhookEvent {
+    /** Event id, `evt_…` — stable across retries; deduplicate on it. */
+    id: string;
+    /** `webhook.test` is sent only by the dashboard's "Send test event" button. */
+    type: "job.succeeded" | "job.failed" | "webhook.test";
+    /** Unix seconds when the event was created (not when this attempt was sent). */
+    created: number;
+    /** The type of the key that submitted the job. */
+    env: "live" | "test";
+    /** For job events: the job. For webhook.test: a `message`. */
+    data: {
+        jobId?: string;
+        mode?: "2d" | "nest";
+        engine?: "max";
+        status?: "succeeded" | "failed";
+        message?: string;
+    };
+}
+/** The request is well-formed. No solve ran and no quota was spent. */
+export interface ValidateResponse {
+    /** Always true on a 200 — a malformed request is a 400 with the exact bad field path (`details.path`) instead. The body is the SAME one the matching optimize endpoint takes. */
+    valid: boolean;
+    /** The endpoint you called. */
+    mode: "2d" | "1d" | "wood" | "nest";
+    /** Shape version. Currently `"1"`. */
+    contractVersion: string;
+    /** Nest only — whether the nesting engine is built into this deployment. Absent for the rectangular modes. */
+    engineEnabled?: boolean;
+    /** Part rows sent, and the total quantity after `qty` expansion. Check it against the part cap before you spend a call. */
+    parts: {
+        /** Number of part rows sent. */
+        rows: number;
+        /** Total quantity across all part rows (Σ qty). */
+        total: number;
+    };
+    /** The same for stock. */
+    stock: {
+        /** Number of stock rows sent. */
+        rows: number;
+        /** Total quantity across all stock rows (Σ qty). */
+        total: number;
+    };
+    /** Approximate, solve-free feasibility notes — e.g. a part that fits no stock (2D and nest: by bounding box; wood: no matching section long enough). Empty ⇒ every part fits some stock. Ignores trim/kerf/material (a shape check, not a solve). */
+    warnings: Array<string>;
+}
+/** The error envelope for every failure the engine itself produces. */
+export interface Error {
+    /** Stable machine-readable code. Branch on this, never on `message`. (`service_unavailable` means an engine is not built into that deployment: the nesting engine for `POST /v1/optimize/nest`, or the async `max` engine for `engine:"max"`. `solve_timeout` is produced only by `POST /v1/optimize/nest`, whose subprocess has its own budget; the rectangular paths are bounded at the proxy and answer 504 without this envelope. The two `idempotency_*` codes (409) are sent only to a request that carried an `Idempotency-Key` header.) */
+    error: "invalid_request" | "unauthorized" | "quota_exceeded" | "key_revoked" | "too_large" | "busy" | "service_unavailable" | "solve_timeout" | "internal" | "idempotency_conflict" | "idempotency_in_progress";
+    /** Human-readable explanation. Wording may change between releases. */
+    message: string;
+    /** Present on some errors. For `invalid_request` it carries `path`, the dotted/indexed location of the offending field (e.g. `parts[0].h`) — and, when `engine: "max"` was asked for something that tier cannot model, an `unsupported` array naming each one. For `too_large` it carries `path`, `max` and sometimes `got` — except a request BODY over the size cap, which carries `maxBytes` alone (the body is refused before it is parsed, so there is no field path). An unknown `engine` id adds `available`, the ids this deployment accepts. On `/v1/optimize/nest` a part outline that crosses itself carries `reason: "self_intersecting"` with `path` (`parts[i].polygon`), or with the nesting engine's internal `itemId` when it cannot be traced back to a request row. Treat unknown keys as informational: new ones are additive. The public demo key's refusals (403 `key_revoked`, 429 `busy`) carry `reason` (`demo_scope` / `demo_rate_limit`) and `testKeyUrl`; a rate refusal adds `limit`, a size refusal `maxParts` or `maxStockRows`. */
+    details?: {
+        path?: string;
+        max?: number;
+        got?: number;
+        /** The request-body cap in bytes (`too_large` on the body itself). */
+        maxBytes?: number;
+        /** What `engine: "max"` cannot model in this request. */
+        unsupported?: Array<string>;
+        /** Engine ids this deployment accepts (unknown `engine`). */
+        available?: Array<string>;
+        /** A finer cause within the code: `self_intersecting` (a nest outline crosses itself), `demo_scope` or `demo_rate_limit` (a public demo key refusal). */
+        reason?: string;
+        /** Public demo key refusals only: where a signed-in account creates a free test key (never billed). */
+        testKeyUrl?: string;
+        /** Public demo key rate refusals only (`demo_rate_limit`): which allowance ran out — `ip-min`, `ip-day`, `global-min`, `global-day`, or `capacity` (every solve slot busy; the demo never queues). */
+        limit?: string;
+        /** Public demo key only: the parts cap (total quantity) a demo request may carry. */
+        maxParts?: number;
+        /** Public demo key only: the stock-row cap a demo request may carry. */
+        maxStockRows?: number;
+        /** Nest only, when no request row could be named: the nesting engine's internal id of the rejected outline. */
+        itemId?: number;
+    };
+}
+/** Routing failure. Uses a code (`not_found`) that is intentionally outside the `Error` enum, because it is produced by the router rather than by the API contract. */
+export interface NotFoundError {
+    error: "not_found";
+    message: string;
+}
+/** An [x, y] vertex, in the caller's chosen unit. */
+export type NestPoint = Array<number>;
+/** An ordered ring of ≥3 vertices. May be given closed (first == last) or open; the DTO layer normalises. Winding order is not required — it is oriented internally. */
+export type NestRing = Array<NestPoint>;
+/** An exclusion / inferior-quality zone ON a sheet: a defect, a clamp footprint, a pre-printed area — something the rectangular API cannot express. */
+export interface NestZone {
+    polygon: NestRing;
+    /** A zone of quality Q is a hazard for any part whose `minQuality` exceeds Q. Default 0 = hard-forbidden for any part with the default `minQuality` of 1. */
+    quality?: number;
+}
+/** Read this part's outline out of an SVG or DXF FILE instead of listing coordinates. The same parser the CutOptim app uses for its Nesting mode runs server-side, so a part library that already exists as CAD files needs no path/arc flattener of your own. **The file replaces ONLY the geometry.** `qty`, `material`, `allowedRotations`, `minQuality`, `priority` and `meta` behave exactly as they do on a `polygon` part. **Exactly ONE outline per source.** Holes are folded in automatically (a ring contained in another becomes a hole), so a typical single-part drawing — outline plus bolt holes — is one outline. A file describing several separate parts is a 400 that names `POST /v1/import/nest`, which splits it. **Nothing is stored.** The bytes exist only as this request body, are parsed in memory and are gone when the response is written: no disk, no database, no temp file, no log line. There is nothing to delete and nothing retained. **Units are reported, never applied.** A DXF may declare `$INSUNITS`; it comes back in `imported.units` and several disagreeing files produce a warning, but coordinates pass through verbatim — this API converts nothing (see the unit rule on `/v1/optimize/nest`). */
+export interface NestSource {
+    /** The file TEXT — not base64, not a URL, not a multipart upload: both formats are text documents, so they travel inside the JSON body like any other field. Max 4,000,000 characters per file and 8,000,000 across the request; over either is a 413. ⚠️ The HTTP body cap differs by path: 10 MB on `/v1/optimize/nest` and `/v1/import/nest`, but the DEFAULT 1 MB on `/v1/validate/nest`, which is the only nest path that needs no key. A source body over 1 MB therefore validates on the optimize path, not the free one. */
+    content: string;
+    /** Omit to sniff the content (an `<svg` tag ⇒ svg, otherwise dxf). An explicit format always wins — including over a misleading `filename` extension. */
+    format?: "svg" | "dxf";
+    /** Used for format detection AND as the part name when the row has no `name` (extension stripped). Never touches a filesystem. */
+    filename?: string;
+    /** Curve / arc flattening tolerance, in the FILE's own coordinate unit. Larger = fewer vertices. This is the lever when a dense outline trips the 2,000-vertex per-ring cap. */
+    flattenTolerance?: number;
+}
+/** The same four fields `parts[].source` takes, at the top level. See NestSource for the caps, the sniffing rule and the no-storage guarantee. */
+export interface NestImportRequest {
+    /** The file TEXT (not base64) — the same 4,000,000-character cap as `parts[].source`. */
+    content: string;
+    /** Omit to sniff; an explicit value wins over the filename extension. */
+    format?: "svg" | "dxf";
+    /** Used for detection and to NAME the parts: one outline keeps the bare name, several are numbered `<name> 1`, `<name> 2`, … */
+    filename?: string;
+    /** Curve / arc flattening tolerance in the file's own unit. */
+    flattenTolerance?: number;
+}
+/** One outline, in exactly the shape a `parts[]` row wants — paste it in and add your own qty / material / rotations. */
+export interface NestImportedPart {
+    /** Named from `filename`: one outline keeps the bare name, several are numbered. */
+    name: string;
+    polygon: NestRing;
+    /** Present only when the outline actually contained a ring. */
+    holes?: Array<NestRing>;
+}
+export interface NestImportResponse {
+    /** The parser that actually ran — useful when you let the server sniff. */
+    format: "svg" | "dxf";
+    /** One entry per closed outline, largest first — each already in the shape a `parts[]` row wants: paste it in and add your own qty / material / allowedRotations. Deterministic: the same bytes always give the same vertices in the same order. */
+    parts: Array<NestImportedPart>;
+    /** Total vertices after flattening, outlines and holes together. Compare against the 2,000-per-ring cap before you build a big request. */
+    vertices: number;
+    /** A DXF `$INSUNITS` declaration when the file carries one. REPORTED, NEVER APPLIED — the API converts nothing, so this is information for you, not a transformation we performed. Absent for SVG (the format has no unit) and for a DXF that declares none. */
+    sourceUnit?: "mm" | "in";
+    /** What the parser could not honour — e.g. an SVG `<use>` clone (not expanded), or geometry that never closed into a contour. SVG `transform=` attributes (on the element and its groups) are applied, and shapes inside `<defs>`, `<clipPath>`, `<mask>` or hidden with `display:none` are not read. Empty means the file was read whole. */
+    warnings: Array<string>;
+    /** Whether THIS deployment can also SOLVE a nest. Importing works everywhere (it is pure parsing); on a deployment without the nesting engine `/v1/optimize/nest` answers 503, and this flag tells you that up front. Mirrors the field on `/v1/validate/nest`. */
+    engineEnabled: boolean;
+    /** Nest contract version. Currently `"1"`. */
+    contractVersion: string;
+}
+/** What the request's `source` files contributed. ABSENT when every part carried `polygon` coordinates, which is what keeps such a request byte-identical to before the feature existed. */
+export interface NestImportSummary {
+    /** Part ROWS whose geometry came from a file. */
+    parts: number;
+    /** Total vertices those files produced, after flattening (outlines + holes) — the number to watch against the 2,000-vertex per-ring cap. */
+    vertices: number;
+    /** Distinct units the files DECLARED (DXF `$INSUNITS`); empty when none did. Reporting only — more than one entry also raises a warning, because mixing units silently produces a plan that validates and is physically wrong, and the server must not "fix" it by converting — no field in this API asserts a unit. */
+    units: Array<"mm" | "in">;
+}
+/** A part. Give its outline as `polygon` coordinates OR as a `source` file — exactly one of the two (both, or neither, is a 400). */
+export type NestPart = {
+    /** Optional label, echoed on every placement. Defaults to `source.filename` without its extension when a file was given, otherwise `Part <1-based row index>`. */
+    name?: string;
+    polygon?: NestRing;
+    source?: NestSource;
+    /** Optional interior holes — a part with a cut-out. NOT accepted together with `source`: the file already carries its own holes. */
+    holes?: Array<NestRing>;
+    /** Copies to place. */
+    qty?: number;
+    /** Allowed rotations in DEGREES (e.g. [0,90,180,270]). Omit or "continuous" for free rotation. */
+    allowedRotations?: Array<number> | "continuous";
+    /** The part may only be placed where sheet quality ≥ this. Default 1 → it avoids every quality-0 exclusion zone. Raise it to keep the part off inferior-but-not-forbidden zones too. */
+    minQuality?: number;
+    /** Must-cut. With `options.respectStock` (a capped supply, where not every part may fit) these parts are placed first, so a plain part never takes the sheet space a must-cut part needs, and every plan comparison ranks the plan that keeps more of them ahead. Honoured by both engines. Without `respectStock` every part that fits is placed anyway, so the flag changes nothing. A must-cut part that fits no sheet is still listed in `unplaced`. */
+    priority?: boolean;
+    /** A part of material X nests only on material-X sheets; the job is partitioned by material. */
+    material?: string;
+    /** Opaque JSON (your ERP ids), echoed verbatim on every placed copy. Never affects the layout. */
+    meta?: Record<string, unknown>;
+} & ({
+    polygon: NestRing;
+} | {
+    source: NestSource;
+});
+/** A stock sheet type: either a rectangle (w & h) OR an arbitrary polygon outline (an off-cut remnant). Exactly one of {w & h} | polygon. */
+export interface NestStock {
+    /** Rectangular sheet size. Give w & h OR polygon, not both. */
+    w?: number;
+    /** Rectangular sheet size. Give w & h OR polygon, not both. */
+    h?: number;
+    /** Arbitrary sheet outline (an off-cut remnant, a non-rectangular board) instead of w & h. */
+    polygon?: NestRing;
+    /** A HARD cap only when options.respectStock is true. */
+    qty?: number;
+    /** Per-sheet price. Summed into `totalPrice` / `stockUsage[].totalPrice`, and the ranking key of `options.minimizeCost`. */
+    price?: number;
+    /** Integer relative per-sheet cost, used by `options.minimizeCost` for a row that has no `price` (e.g. when price is not money). */
+    cost?: number;
+    /** This sheet serves only material-matching parts. */
+    material?: string;
+    /** Per-sheet excluded / inferior zones: a defect, a clamp footprint, a pre-printed area — what the rectangular API cannot express. */
+    exclusions?: Array<NestZone>;
+    /** Echoed on every sheet cut from this stock row. */
+    meta?: Record<string, unknown>;
+}
+/** Solve options. All optional. */
+export interface NestOptions {
+    /** Minimum clearance between parts and between a part and any hazard (sheet edge / zone). Use for kerf / beam / torch width. Default 0. The sheet-edge part can be set separately with `edgeClearance`. */
+    minSeparation?: number;
+    /** Minimum distance between any part and the SHEET EDGE, independent of `minSeparation` (e.g. 5 between parts, 0 or 10 at the edge). Omit it and the edge keeps `minSeparation` (the previous behaviour, unchanged). Both engines. Rectangular sheets only — with a `polygon` sheet it is a 400, as is a value that leaves no room on a sheet (the sheet minus twice `edgeClearance − minSeparation` must stay positive). Exclusion zones keep `minSeparation`, like parts. */
+    edgeClearance?: number;
+    /** Search budget for engine `max`, in milliseconds (default 60000; clamped to 10000–180000, and a clamp is reported in `warnings`). Ignored by `lbf` (no search budget). The job finishes about 1–2 s after the budget, plus any time spent queued; for a job of a few dozen parts 15000 is usually enough. Poll `GET /v1/jobs/{id}` every 2–3 s — polling costs no quota. */
+    timeBudgetMs?: number;
+    /** Determinism: fixed seed → reproducible layout. Omit and the server pins a fixed default, so the response stays reproducible. */
+    seed?: number;
+    /** How engine `lbf` chooses the sheet size when a material has two or more stock rows. It always tries the rows in your order, each row on its own and a cheapest-first order, and keeps the best, so the result does not depend on the order you list them in. Ranking: most must-cut (`parts[].priority`) parts placed → most parts placed → (with `minimizeCost`) lowest total price → least total sheet area → fewest sheets. `minimizeCost` ranks by `price` (or `cost` when a row has no price) only when EVERY row of that material carries one; otherwise it falls back to sheet area and says so in `warnings`. Since 2026-09-22 (F3) the plan may also MIX sizes within a material: every sheet, least-filled first, is re-nested onto the cheaper or smaller rows and replaced when the whole plan ranks better — typically the half-empty last sheet moves to a smaller size. Engine `max` uses the same ranking to decide whether its search result replaces the `lbf` plan. */
+    minimizeCost?: boolean;
+    /** Treat each stock qty as a hard cap (both engines; the mixed-size re-nest never uses more sheets of a row than its qty). */
+    respectStock?: boolean;
+    /** Polygon simplification tolerance (max area deviation as a fraction). Speeds up dense DXF outlines with hundreds of vertices. 0 disables. */
+    simplifyTolerance?: number;
+    /** Compact the least-filled sheet of each material (both engines, default on). After the plan is final, that sheet's parts are re-nested on the same sheet with rotation SUBSETS of what each part allows — {0,180}, {0,90,180,270} and a single orientation, intersected with a discrete `allowedRotations`, never a new angle — and the variant with the smallest used area (`sheets[].usedWidth × usedHeight`) is kept. With engine `max` the sheet (when it holds two or more parts) is then also re-packed by the strip search itself — along the sheet's height and, on a one-sheet plan, also along its width; a few seconds on top of the search budget, under a hard time limit — and the result replaces the sheet only when it is strictly smaller under `compactFor` and keeps the spacing and the edge clearance. Sheet count, sizes, price and placed parts are unchanged by construction. Runs within a work budget (a very full last sheet may be left as it is). `false` returns the uncompacted layout. */
+    compact?: boolean;
+    /** Which used measure the compaction minimises — match it to how you charge a partial sheet. `box` (default): the smallest used bounding area (`usedArea`). `horizontal`: the lowest `usedHeight`, for charging a strip across the full sheet width. `vertical`: the smallest `usedWidth`, for charging a strip over the full sheet height. Ties fall back to the used area; the strip modes also try every copy turned a quarter (90° or 270°, where `allowedRotations` permits it). It only changes which compacted layout is kept: sheet count, sizes, price and placed parts never change, and the result is never worse than the uncompacted layout on that measure. Ignored with `compact: false`. */
+    compactFor?: "box" | "horizontal" | "vertical";
+}
+export interface OptimizeNestRequest {
+    /** One or more parts to nest, one NestPart per row. */
+    parts: Array<NestPart>;
+    /** One or more sheet types, one NestStock per row. */
+    stock: Array<NestStock>;
+    options?: NestOptions;
+    /** `lbf` (default) is single-pass, synchronous and instant. `max` is ASYNCHRONOUS: 202 + poll `GET /v1/jobs/{id}`; it runs `lbf` first, then a time-budgeted search that fills sheets one at a time looking for FEWER sheets, and never returns more than `lbf`, nor a plan that ranks worse (price with `minimizeCost`, otherwise sheet area). It accepts several sheet sizes per material and `respectStock`; a `polygon` sheet or exclusion zones are served by `lbf` inside the job, with a warning. `sparrow` is a deprecated alias of `max`. */
+    engine?: "lbf" | "max" | "sparrow";
+    /** Additive inline export of the achieved layout. `svg` returns a self-contained, styled `<svg>` string (one titled band per sheet, parts drawn as filled polygons with holes, exclusion zones hatched); `dxf` returns an R12 document (closed `POLYLINE`/`VERTEX` outlines on STOCK/PARTS/HOLES/ZONES layers, part names on LABELS). Both are unit-agnostic, exactly like the request coordinates. The geometry in `sheets[]` is returned either way. */
+    include?: Array<"svg" | "dxf">;
+}
+/** A placed copy. Carries the rigid transform (rotation THEN translation), not a re-emitted polygon: rotate the input outline by `rotation` about its origin, then add (x, y). */
+export interface PlacedNestPart {
+    /** The requested name, or the generated default. */
+    name: string;
+    /** 0-based index into `sheets`. */
+    sheet: number;
+    /** Translation x (applied after rotation). */
+    x: number;
+    /** Translation y. */
+    y: number;
+    /** Degrees, applied about the part's own origin first. May be negative (jagua's own value); the reconstruction is exact regardless of sign. */
+    rotation: number;
+    /** The material this copy nested from. */
+    material?: string;
+    /** The part's opaque passthrough. */
+    meta?: Record<string, unknown>;
+}
+export interface NestSheet {
+    /** Present for rectangular sheets. Always the real sheet size (also with `edgeClearance`). */
+    w?: number;
+    /** Present for rectangular sheets. Always the real sheet size (also with `edgeClearance`). */
+    h?: number;
+    /** Present for arbitrary-outline sheets instead of w/h. */
+    polygon?: NestRing;
+    /** Index into the request `stock[]` this sheet was cut from — the key an ERP uses to tie the sheet back to its stock row. */
+    stock: number;
+    /** The stock row's price, or null. */
+    price: number | null;
+    /** This sheet's fill = placed polygon area / sheet area. */
+    density: number;
+    /** Σ perimeter of the placed parts' outer outlines AND holes on this sheet, 3 decimals, in your unit — the contour length a laser / plasma / waterjet head follows. Geometric: no common-line cutting, lead-in/out or micro-joints (your CAM adds those). */
+    cutLength: number;
+    /** Pierce points on this sheet: one per closed contour (each placed part's outline + one per hole). */
+    pierces: number;
+    /** The farthest x any placed part reaches, measured from the sheet origin (0,0), 3 decimals, in your unit — real sheet coordinates (with `edgeClearance` it includes the edge gap). With `usedHeight`: the used bounding box from the origin corner, for partial-sheet charging (full sheet / horizontal cut = usedHeight × w / vertical cut = usedWidth × h / boundary box — the charging rule is yours). A `polygon` sheet: the same, in the polygon's own coordinate frame. */
+    usedWidth: number;
+    /** The farthest y any placed part reaches, from the sheet origin (see `usedWidth`). */
+    usedHeight: number;
+    /** `usedWidth × usedHeight` (rounded to 2 decimals). */
+    usedArea: number;
+    /** Placements on this sheet. */
+    parts: Array<PlacedNestPart>;
+    /** The zones that applied to this sheet, echoed for rendering. */
+    exclusions?: Array<NestZone>;
+    /** Present when the sheet carried a material. */
+    material?: string;
+    /** Echoed from the stock row's meta. */
+    meta?: Record<string, unknown>;
+}
+/** Job totals. */
+export interface NestMetrics {
+    /** Sheets used. Equals `sheets.length`. ⚠️ The honest, cross-comparable metric between nesting and the rectangular modes. */
+    sheetCount: number;
+    /** ⚠️ Placed POLYGON area / used sheet area — the honest fill (concave pockets count as empty). NOT comparable to a rectangular packer's `yieldPct`, which counts each bounding box as solid and so reads higher for a worse result; the cross-comparable metric is `sheetCount`. */
+    density: number;
+    /** Part copies placed. */
+    placed: number;
+    /** Part copies requested. */
+    total: number;
+    /** Sum of used sheet prices. */
+    totalPrice: number;
+    /** Σ `sheets[].cutLength` — placed parts only (outlines + holes), in your unit. */
+    cutLength: number;
+    /** Σ `sheets[].pierces`. */
+    pierces: number;
+}
+/** Sheets used per request stock ROW ("quantity per sheet size"). The unit is the row, not the size: two rows with the same w × h but a different price or meta are two entries. */
+export interface NestStockUsage {
+    /** Index into the request `stock[]`. */
+    stock: number;
+    /** Present for rectangular rows. */
+    w?: number;
+    /** Present for rectangular rows. */
+    h?: number;
+    /** Present when the row carries a material. */
+    material?: string;
+    /** Sheets cut from this row. */
+    sheetCount: number;
+    /** Σ sheet price (0 for a row without a price, the same rule as `metrics.totalPrice`). */
+    totalPrice: number;
+    /** Placed polygon area / total area of this row's sheets. */
+    density: number;
+    /** Σ `sheets[].usedArea` of this row's sheets — the used bounding area to total per sheet size. */
+    usedArea: number;
+}
+export interface UnplacedNest {
+    /** The part name. */
+    name: string;
+    /** How many copies could not be placed. */
+    qty: number;
+}
+/** One material's totals across the sheets cut from it. */
+export interface NestMaterialSummary {
+    /** The tag exactly as you sent it. Free text, matched exactly. */
+    material: string;
+    /** Sheets cut from this material. */
+    sheetCount: number;
+    /** This material's own fill: placed polygon area / area of its sheets — a polygon fill, not comparable to the rectangular modes' `yieldPct`. */
+    density: number;
+    /** Part copies of this material placed. */
+    placed: number;
+    /** Part copies of this material requested (Σ qty). */
+    total: number;
+    /** Sum of the prices of the sheets used for this material. */
+    totalPrice: number;
+}
+export interface UnmatchedMaterialNest {
+    /** The tag that has no stock of its own anywhere in the request. */
+    material: string;
+    /** The demand rows in that material, in the nest unplaced shape: name, qty. */
+    parts: Array<UnplacedNest>;
+}
+export interface OptimizeNestResponse {
+    /** The engine that served the request: `lbf` for a synchronous nest, `max` for the result of an async `max` job (read from `GET /v1/jobs/{id}`). */
+    engine: "lbf" | "max";
+    /** Algorithm version = package version + pinned jagua-rs commit + a hash of the mapping layer. Versions independently of the rectangular engines. */
+    engineVersion: string;
+    /** Nest contract version, currently `"1"`. Versions independently of the `/v1/` rectangular contract — it is a different path and engine family. */
+    contractVersion: string;
+    /** `true` for `lbf` (a pinned seed makes the layout reproducible) — unless a comparison of alternative layouts (several stock rows, right angles) hit its time limit on the server (then `false`, with a warning). For `max` it is `false` whenever a time-limited search ran — the search for fewer sheets, or the re-packing of the least-filled sheet (`options.compact`) — and `true` only when the `lbf` pass alone decided the layout (a single-part sheet, `compact: false`). */
+    deterministic: boolean;
+    /** One entry per used sheet. */
+    sheets: Array<NestSheet>;
+    metrics: NestMetrics;
+    /** One entry per USED request stock row, sorted by `stock`: sheets used, total price and density. Always present. */
+    stockUsage: Array<NestStockUsage>;
+    /** Demand that could not be placed — a plan-plus-warning, not an error. */
+    unplaced: Array<UnplacedNest>;
+    /** e.g. unplaced parts, a material with no matching stock, or — for `max` — how the result was reached (for instance that the `lbf` layout was kept because no layout with fewer sheets was found in the time budget). */
+    warnings: Array<string>;
+    /** Per-material rollup, present only for a material-aware request. */
+    materials?: Array<NestMaterialSummary>;
+    /** Parts whose material has no matching stock. Present only when it happens. */
+    unmatchedMaterials?: Array<UnmatchedMaterialNest>;
+    imported?: NestImportSummary;
+    /** Additive — a self-contained SVG of the achieved layout, present only when `include` has "svg". */
+    svg?: string;
+    /** Additive — an R12 DXF of the achieved layout, present only when `include` has "dxf". */
+    dxf?: string;
+    /** The solve time; environment-dependent. */
+    timing: {
+        /** Milliseconds spent solving. */
+        solveMs: number;
+    };
+}
+export interface Part2D {
+    /** Optional label, echoed on every placement. Defaults to `Part <1-based row index>`. */
+    name?: string;
+    /** Part width. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    w: number;
+    /** Part height. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    h: number;
+    /** How many identical copies. Expanded server-side into individual pieces; the sum across all rows must not exceed 2000. */
+    qty?: number;
+    /** May the part be turned 90°? Set false for print-direction parts. For grain, prefer `grain` — it says WHICH side the grain runs along, so the part is turned to match the sheet instead of being frozen in the orientation you happened to send. */
+    rotatable?: boolean;
+    /** Grain direction: the side of the part the grain runs along (`w` or `h`). On a sheet whose stock row has a `grain`, the part is placed with its grain along the sheet's, turned 90° when it has to be (`rotated: true` on the placement) — `rotatable` is then ignored for it. With `material`, only boards of the part's own material count. No grained stock → no effect, and `warnings` says so. In a matched set a member's own `grain` is not used: the set's `grain` decides, and a `grain:` line in `matchedSets[].warnings` names the members it overrides. */
+    grain?: "w" | "h";
+    /** DEPRECATED — still accepted and still working exactly as before. Parts sharing a group are kept on one sheet. If a group is too large for one sheet the members are split and a string in `warnings` names the group. It only keeps them on ONE SHEET: it does not place them next to each other, so it gives no continuous grain across them. For fronts whose figure must run on (a drawer front over two doors) use `matchedSets`. @deprecated */
+    grainGroup?: string;
+    /** Must-cut. Wins board space over non-priority parts when stock is capped — only meaningful together with `options.respectStock`. */
+    priority?: boolean;
+    /** Per-edge banding. Each side names the banding TYPE as a free-string reference (e.g. `"ABS oak 22×1"`); an absent or empty side is not banded. Library-independent — send your own ERP reference codes and the `edgeBanding` response block groups the metreage by that exact string. Metadata only: it never changes placement, it is summarised post-hoc into linear metres. 2D only. */
+    edgeBanding?: {
+        /** Type reference for the top edge (runs the part width). */
+        top?: string;
+        /** Type reference for the right edge (runs the part height). */
+        right?: string;
+        /** Type reference for the bottom edge (runs the part width). */
+        bottom?: string;
+        /** Type reference for the left edge (runs the part height). */
+        left?: string;
+    };
+    /** Material identity — a HARD placement constraint. A part of material X is cut ONLY from stock of material X (unlike `edgeBanding`, this changes the layout). Free string, library-independent: send your own ERP code. Absent = the "unspecified" partition (matches only material-less stock). With no part or stock carrying `material`, the whole solve is byte-identical to before. */
+    material?: string;
+    /** Opaque JSON object (any keys) echoed back VERBATIM on the matching output (a part's meta on every placed piece of it; a stock row's meta on every sheet/rod cut from it). Attach ERP article numbers, order-line ids, customer refs to reconcile the cut plan with your system. Never parsed, never affects placement. Part meta follows its request row: the meta of each row lands on exactly its qty of placed pieces, even when rows share a name; stock meta by stock-row order. */
+    meta?: Record<string, unknown>;
+    /** The row's id, so a `matchedSets` layout can name it. Any JSON value is accepted here. Only an id a set REFERS TO is checked: it must be a non-empty string of printable characters, at most 64 long, or a safe integer (`7` and `"7"` are the same id), and it must be on exactly one part. Every other id is ignored, whatever it holds (a float, an object, null, repeated, long, empty): always without a non-empty `matchedSets`, and on the rows no set names with one — so an ERP article number is safe to send. */
+    id?: unknown;
+}
+/** Parts cut out of ONE piece of board, side by side or one above the other, exactly one kerf apart, so the figure of the veneer runs on across them (a drawer front over two doors). The set travels through the optimizer as one rectangle — the block — and comes back as its members. Every refusal is a 400 before the quota is reserved; a size mismatch is a warning (`matchedSets[].warnings`), not an error. At most 24 members per set; a part can be in one set only. Engines `heuristic` and `balanced` (which does not rank `priority`, so under `respectStock` a set can lose its place there); `max` refuses a request with sets (400 `details.unsupported`). */
+export interface MatchedSet {
+    /** Unique among the sets; at most 64 characters. Echoed on every member placement and in `matchedSets[]` of the response (as a string). */
+    id: string | number;
+    /** Optional label, echoed in the response rollup. Printable characters only. */
+    name?: string;
+    /** How many instances (three identical cabinets → 3). The parts' `qty` must cover every instance. */
+    qty?: number;
+    /** The SET's grain: along the block's width (`w`) or height (`h`); it decides the direction of every member (their own `grain` is not used inside the block). Absent/null = no grain: the block may turn when every member is `rotatable`. */
+    grain?: "w" | "h" | null;
+    /** When the block fits no stock sheet: `split` places the members one by one (with a warning), `unplaced` lists them in `unplaced`. */
+    onMiss?: "split" | "unplaced";
+    /** The gap between the members ON THE CABINET (default: the kerf). The `align` check measures the lines with it; on the sheet the members still stand one kerf apart, and when the kerf is wider a `gap:` warning says so. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    installGap?: number;
+    layout: MatchedSetLayout;
+}
+/** Where each member sits, as lines of `parts[].id` values. `rows`: each line is a row of members side by side, the rows stacked top to bottom (`[["DF"], ["DOOR", "DOOR"]]` = a drawer front over two doors). `cols`: each line is a column of members one above the other, the columns side by side. A part may appear more than once in one set. Positions are numbered in reading order: top to bottom, left to right. */
+export interface MatchedSetLayout {
+    /** `rows`: each line is a row of members side by side, the rows stacked top to bottom. `cols`: each line is a column, the columns side by side. */
+    dir: "rows" | "cols";
+    /** The members, as `parts[].id` values — `[["DF"], ["DOOR", "DOOR"]]` is a drawer front over two doors. */
+    lines: Array<Array<string | number>>;
+}
+export interface Stock2D {
+    /** Sheet width. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    w: number;
+    /** Sheet height. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    h: number;
+    /** How many sheets of this format are available. A HARD cap only when `options.respectStock` is true; otherwise the format is treated as unlimited. The sum across all rows must not exceed 5000. */
+    qty?: number;
+    /** Price per sheet. Drives `metrics.totalPrice` and `options.minimizeCost`. */
+    price?: number;
+    /** A stock unit of material X serves only material-X parts. Free string; see the part `material`. */
+    material?: string;
+    /** "Use this stock up first" — a soft preference ranked BELOW sheet/rod count. Steers which format is spent first without spending more of it. */
+    priority?: boolean;
+    /** Grain direction of this sheet: the side the grain runs along (`w` or `h`). Absent = no grain (MDF, melamine): parts without a `grain` rotate freely on it, while a part WITH a `grain` keeps the orientation the grained rows give it (send `material` to keep grained and plain boards apart). Echoed on every `sheets[]` entry cut from this row. Rows whose grain runs different ways may be mixed; `options.trim` and a forced `options.firstCut` still apply to each sheet in its own row's orientation. */
+    grain?: "w" | "h";
+    /** Opaque JSON object (any keys) echoed back VERBATIM on the matching output (a part's meta on every placed piece of it; a stock row's meta on every sheet/rod cut from it). Attach ERP article numbers, order-line ids, customer refs to reconcile the cut plan with your system. Never parsed, never affects placement. Part meta follows its request row: the meta of each row lands on exactly its qty of placed pieces, even when rows share a name; stock meta by stock-row order. */
+    meta?: Record<string, unknown>;
+}
+/** Per-side edge trim removed before nesting. Asymmetric on purpose: a damaged long edge may need more than the others, and a symmetric trim would then give a wrong plan, not merely a worse one. `left` shifts placements right, `top` shifts them down. The sides are those of each sheet as sent — also on a `grain` row whose grain runs the other way. */
+export interface Trim2D {
+    /** Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    left?: number;
+    /** Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    right?: number;
+    /** Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    top?: number;
+    /** Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    bottom?: number;
+}
+export interface Options2D {
+    /** Blade width. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    kerf?: number;
+    /** Accept a cut that overshoots by up to this much, i.e. allow parts to encroach on the kerf. Turns "two 501 mm parts do not fit a 1000 mm board" into one board. */
+    tolerance?: number;
+    trim?: Trim2D;
+    /** Force the orientation of the first cut across the board. `auto` searches both and also enables two extra strategy families that are not direction-aware. Applies to each sheet as sent, also on a `grain` row whose grain runs the other way. */
+    firstCut?: "auto" | "horizontal" | "vertical";
+    /** Rank candidate layouts by total stock price instead of sheet count. Needs `price` on the stock rows to mean anything. */
+    minimizeCost?: boolean;
+    /** Treat each stock row's `qty` as a hard cap. Parts that then do not fit come back in `unplaced` instead of on an extra invented sheet. */
+    respectStock?: boolean;
+    /** Output filter only: report a leftover rectangle only if its SHORT side is at least this. Does not change the layout. */
+    minOffcut?: number;
+    /** Panel-saw stage limit — a count of machine PHASES (axis changes), not raw cut-tree depth. A real kitchen job is commonly 9 cuts deep but only 3 stages. An unsatisfiable limit still returns the best plan plus a string in `warnings`; it is never an error. */
+    maxCutStages?: number | null;
+    /** Prefer layouts that turn fewer parts, at a possible small yield cost. */
+    minimizeRotations?: boolean;
+    /** Search depth, trading solve time against yield. `balanced` (the default) runs the full multi-strategy best-of. `fast` skips the two expensive refinements — the per-board area-combination search and the tail right-sizing that moves the last boards onto a smaller stock size: markedly faster on large jobs (hundreds of parts) for a small yield cost, while staying guillotine-valid and never denser than `balanced` — its candidate set is a strict subset. On small jobs the two are usually identical. Applies to engine `heuristic`; the `balanced` engine (MaxRects) ignores it. */
+    effort?: "fast" | "balanced";
+    /** A boolean. With `matchedSets` and the `svg` export: draw the dashed frame and the "SET A" badge of every set instance, in ONE separate group (`<g id="matched-sets" data-role="annotation">`) a laser or CNC import can drop in one move. `false` leaves that group out (the position codes in the part labels stay). Read only in a request with sets — there a value other than `true`, `false` or `null` is a 400; without sets the field is ignored, whatever it holds. */
+    setOutlines?: boolean;
+}
+export interface Optimize2DRequest {
+    parts: Array<Part2D>;
+    stock: Array<Stock2D>;
+    options?: Options2D;
+    /** Which optimizer to run. `heuristic` is the guillotine multi-strategy packer: highest yield, every layout edge-to-edge saw-cuttable, always a full `cutPlan`. `balanced` is a MaxRects free-nesting packer: much faster on large jobs for a small yield cost, but its layouts are often not guillotine (`guillotineValid: false`, `cutPlan: null`), and it does not model `tolerance`, `minimizeCost`, `grainGroup`, `maxCutStages` or `minimizeRotations` — set one of those and a string in `warnings` tells you it was ignored. `max` is the ASYNCHRONOUS tree-search tier (2D only): it reaches the proven optimum on far more jobs at the cost of seconds-to-a-minute per solve, so instead of a plan it returns **202** with a `jobId` — poll `GET /v1/jobs/{id}` for the result. Still deterministic and guillotine-valid. Where the tier is not enabled on a deployment, `engine: "max"` fails closed with **503**. **What `max` models.** It packs ONE stock format at full sheet size with unlimited supply and a fixed 3-stage guillotine pattern. Anything that would make the returned plan physically WRONG is therefore REFUSED with **400** at submission — before a call is reserved and before you wait for the solve: a second `stock` row, `options.trim`, `options.respectStock`, any `material`, any `grainGroup`, a non-empty `matchedSets` (an empty one is fine). Options that only make the plan less tuned are accepted and listed in `warnings`: `tolerance`, `minimizeCost`, `maxCutStages` (fixed at 3), `minimizeRotations`, `firstCut`, `effort`. A `max` result reports no `offcuts`. Send those jobs to `heuristic`. The default never changes silently. */
+    engine?: "heuristic" | "balanced" | "max";
+    /** Three kinds of token. NARROWING (`cutPlan`, `offcuts`): omit the field entirely to get both; a present array keeps only the narrowing tokens it lists (an empty array drops both). ADDITIVE EXPORT (`svg`, `csv`, `dxf`): each adds an inline export STRING to the response (`svg` a standalone 2D layout — 2D only, a warning is returned for 1D/wood; `dxf` an R12/AC1009 drawing; `csv` a cut list, RFC 4180 quoted (a part name with a comma or a quote stays one field) and formula-injection-guarded (a name beginning with `=`, `+`, `-`, `@`, TAB or CR is prefixed with an apostrophe so a spreadsheet reads it as text, not a formula — CWE-1236). 2D DATA (`labels`, `planHash`, `pdf`, `labelsPdf`): `labels` adds per-piece label data (`labels[]`, see `Label2D`), `planHash` a 64-hex fingerprint of the plan (the same plan always gives the same hash), `pdf` the cutting-plan PDF and `labelsPdf` the label PDF, both base64-encoded and drawn by the same code as the CutOptim app. These four are 2D only: a 1D or wood request returns a `warnings` entry instead. `pdf` renders at most 500 parts (total quantity); a larger 2D request with `pdf` is a 413 `too_large` with `details.path: "include"`. Export and data tokens do not affect narrowing, so `["svg"]` adds svg and — listing no narrowing token — drops cutPlan/offcuts; use `["cutPlan","offcuts","svg"]` to keep everything. */
+    include?: Array<"cutPlan" | "offcuts" | "svg" | "csv" | "dxf" | "labels" | "planHash" | "pdf" | "labelsPdf">;
+    /** Matched sets (grain matching): groups of parts cut side by side from one piece of board. Send a NON-EMPTY ARRAY of sets (at most 50); members are named by `parts[].id`. Only a non-empty array switches the feature on: absent, `null`, `[]` — and any value that is not an array — is a request without sets, answered exactly as before (no error). With sets the response adds `sheets[].parts[].matchedSet` on every member and a `matchedSets` rollup; `csv` gains `Set` and `Position` columns at the end, `svg` the `matched-sets` frame group, `dxf` the position code on LABELS; `pdf` and `labelsPdf` draw the members as ordinary parts for now (a `warnings` line says so; the set marks are in `sheets[].parts[].matchedSet`, `csv` and `svg`). Engine `max` refuses a non-empty array (400 `details.unsupported`); an empty one is fine. 2D only: the 1D, wood and nest endpoints ignore this field and `parts[].id`. */
+    matchedSets?: Array<MatchedSet>;
+}
+/** A linear part. There is no `rotatable` or `grainGroup` in 1D. */
+export interface Part1D {
+    /** Optional label. Defaults to `Part <1-based row index>`. */
+    name?: string;
+    /** Cut length. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    length: number;
+    /** How many copies. The sum across all rows must not exceed 2000. */
+    qty?: number;
+    /** Must-cut; wins stock when `options.respectStock` caps it. */
+    priority?: boolean;
+    /** Material identity — a HARD placement constraint. A part of material X is cut ONLY from stock of material X (unlike `edgeBanding`, this changes the layout). Free string, library-independent: send your own ERP code. Absent = the "unspecified" partition (matches only material-less stock). With no part or stock carrying `material`, the whole solve is byte-identical to before. */
+    material?: string;
+    /** Opaque JSON object (any keys) echoed back VERBATIM on the matching output (a part's meta on every placed piece of it; a stock row's meta on every sheet/rod cut from it). Attach ERP article numbers, order-line ids, customer refs to reconcile the cut plan with your system. Never parsed, never affects placement. Part meta follows its request row: the meta of each row lands on exactly its qty of placed pieces, even when rows share a name; stock meta by stock-row order. */
+    meta?: Record<string, unknown>;
+}
+export interface Stock1D {
+    /** Bar length. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    length: number;
+    /** Bars available. A hard cap only with `options.respectStock`. */
+    qty?: number;
+    /** Price per bar. */
+    price?: number;
+    /** A stock unit of material X serves only material-X parts. Free string; see the part `material`. */
+    material?: string;
+    /** "Use this stock up first" — a soft preference ranked BELOW sheet/rod count. Steers which format is spent first without spending more of it. */
+    priority?: boolean;
+    /** Opaque JSON object (any keys) echoed back VERBATIM on the matching output (a part's meta on every placed piece of it; a stock row's meta on every sheet/rod cut from it). Attach ERP article numbers, order-line ids, customer refs to reconcile the cut plan with your system. Never parsed, never affects placement. Part meta follows its request row: the meta of each row lands on exactly its qty of placed pieces, even when rows share a name; stock meta by stock-row order. */
+    meta?: Record<string, unknown>;
+}
+/** A bar has two ends, not four edges. `start` is the leading trim (it shifts the first part along the bar, so the first `pos` equals `start`); `end` is the trailing trim. */
+export interface Trim1D {
+    /** Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    start?: number;
+    /** Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    end?: number;
+}
+/** The 1D option set is deliberately smaller: there is no `firstCut`, `maxCutStages` or `minimizeRotations`, because none of them means anything on a bar. */
+export interface Options1D {
+    /** Blade width. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    kerf?: number;
+    /** Accept cuts overshooting by up to this much. Pieces that only fitted thanks to it are counted in `metrics.toleranceAcceptedCount` and noted in `warnings`. */
+    tolerance?: number;
+    trim?: Trim1D;
+    /** Rank by total bar price. */
+    minimizeCost?: boolean;
+    /** Treat `qty` as a hard cap. */
+    respectStock?: boolean;
+    /** Output filter: report a leftover only if it is at least this long. */
+    minOffcut?: number;
+}
+export interface Optimize1DRequest {
+    parts: Array<Part1D>;
+    stock: Array<Stock1D>;
+    options?: Options1D;
+    /** `max` is not offered here: it is a 2D (and, separately, nesting) tier, and `engine: "max"` on this path is a **400** before a call is charged. In 1D `balanced` resolves to the same packer as `heuristic` — the linear packer is already a best-of-multiple-strategies search, so there is no separate balanced mode. The value is accepted and echoed back so a single client can send one engine id for both endpoints. */
+    engine?: "heuristic" | "balanced";
+    /** Three kinds of token. NARROWING (`cutPlan`, `offcuts`): omit the field entirely to get both; a present array keeps only the narrowing tokens it lists (an empty array drops both). ADDITIVE EXPORT (`svg`, `csv`, `dxf`): each adds an inline export STRING to the response (`svg` a standalone 2D layout — 2D only, a warning is returned for 1D/wood; `dxf` an R12/AC1009 drawing; `csv` a cut list, RFC 4180 quoted (a part name with a comma or a quote stays one field) and formula-injection-guarded (a name beginning with `=`, `+`, `-`, `@`, TAB or CR is prefixed with an apostrophe so a spreadsheet reads it as text, not a formula — CWE-1236). 2D DATA (`labels`, `planHash`, `pdf`, `labelsPdf`): `labels` adds per-piece label data (`labels[]`, see `Label2D`), `planHash` a 64-hex fingerprint of the plan (the same plan always gives the same hash), `pdf` the cutting-plan PDF and `labelsPdf` the label PDF, both base64-encoded and drawn by the same code as the CutOptim app. These four are 2D only: a 1D or wood request returns a `warnings` entry instead. `pdf` renders at most 500 parts (total quantity); a larger 2D request with `pdf` is a 413 `too_large` with `details.path: "include"`. Export and data tokens do not affect narrowing, so `["svg"]` adds svg and — listing no narrowing token — drops cutPlan/offcuts; use `["cutPlan","offcuts","svg"]` to keep everything. */
+    include?: Array<"cutPlan" | "offcuts" | "svg" | "csv" | "dxf" | "labels" | "planHash" | "pdf" | "labelsPdf">;
+}
+/** A timber part. Same as a 1D part plus the CROSS-SECTION, which decides which stock it can come out of at all. */
+export interface PartWood {
+    /** Optional label. Defaults to `Part <1-based row index>`. */
+    name?: string;
+    /** One side of the cross-section. ORDER DOES NOT MATTER — 50×100 and 100×50 are the same bar turned over and land in the same section. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    sw: number;
+    /** The other side of the cross-section. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    sh: number;
+    /** Cut length. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    length: number;
+    /** How many copies. The sum across all rows must not exceed 2000. */
+    qty?: number;
+    /** Must-cut; wins stock when `options.respectStock` caps it. Applied WITHIN the part's own cross-section, since another section's bars could not have yielded it anyway. */
+    priority?: boolean;
+    /** Material identity — composes WITH the cross-section: two materials at the same 50×50 become two sections (a 50×50 Pine-Treated part cannot come from a 50×50 Pine-Untreated bar). Free string, library-independent. Absent = today's section-only grouping. */
+    material?: string;
+    /** Opaque JSON object (any keys) echoed back VERBATIM on the matching output (a part's meta on every placed piece of it; a stock row's meta on every sheet/rod cut from it). Attach ERP article numbers, order-line ids, customer refs to reconcile the cut plan with your system. Never parsed, never affects placement. Part meta follows its request row: the meta of each row lands on exactly its qty of placed pieces, even when rows share a name; stock meta by stock-row order. */
+    meta?: Record<string, unknown>;
+}
+export interface StockWood {
+    /** Optional stock label, echoed back as `sections[].stockName` so a plan can name the material an operator has to fetch. */
+    name?: string;
+    /** One side of the cross-section (either order). Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    sw: number;
+    /** The other side of the cross-section. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    sh: number;
+    /** Bar length. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    length: number;
+    /** Bars available. A hard cap only with `options.respectStock`. */
+    qty?: number;
+    /** Price per bar. */
+    price?: number;
+    /** A stock unit of material X serves only material-X parts. Free string; see the part `material`. */
+    material?: string;
+    /** "Use this stock up first" — a soft preference ranked BELOW sheet/rod count. Steers which format is spent first without spending more of it. */
+    priority?: boolean;
+    /** Opaque JSON object (any keys) echoed back VERBATIM on the matching output (a part's meta on every placed piece of it; a stock row's meta on every sheet/rod cut from it). Attach ERP article numbers, order-line ids, customer refs to reconcile the cut plan with your system. Never parsed, never affects placement. Part meta follows its request row: the meta of each row lands on exactly its qty of placed pieces, even when rows share a name; stock meta by stock-row order. */
+    meta?: Record<string, unknown>;
+}
+/** Identical to `Options1D` — a cross-section changes what fits, not how a bar is cut. */
+export interface OptionsWood {
+    /** Blade width. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    kerf?: number;
+    /** Accept cuts overshooting by up to this much. Counted in `metrics.toleranceAcceptedCount` and noted in `warnings`. */
+    tolerance?: number;
+    trim?: Trim1D;
+    /** Rank by total bar price. */
+    minimizeCost?: boolean;
+    /** Treat `qty` as a hard cap. Applied PER CROSS-SECTION. */
+    respectStock?: boolean;
+    /** Output filter: report a leftover only if it is at least this long. */
+    minOffcut?: number;
+}
+export interface OptimizeWoodRequest {
+    parts: Array<PartWood>;
+    /** At most 50 rows. Since every cross-section needs at least one stock row, this is also the practical ceiling on cross-sections in a single job; a wider catalogue should be split into several requests. */
+    stock: Array<StockWood>;
+    options?: OptionsWood;
+    /** As in 1D, `max` is not offered here (a **400** before a call is charged). `balanced` resolves to the same packer as `heuristic`: within a section a timber job is a length problem, and free nesting has nothing to offer it. The value is accepted, echoed back, and a warning states which packer actually ran. */
+    engine?: "heuristic" | "balanced";
+    /** Three kinds of token. NARROWING (`cutPlan`, `offcuts`): omit the field entirely to get both; a present array keeps only the narrowing tokens it lists (an empty array drops both). ADDITIVE EXPORT (`svg`, `csv`, `dxf`): each adds an inline export STRING to the response (`svg` a standalone 2D layout — 2D only, a warning is returned for 1D/wood; `dxf` an R12/AC1009 drawing; `csv` a cut list, RFC 4180 quoted (a part name with a comma or a quote stays one field) and formula-injection-guarded (a name beginning with `=`, `+`, `-`, `@`, TAB or CR is prefixed with an apostrophe so a spreadsheet reads it as text, not a formula — CWE-1236). 2D DATA (`labels`, `planHash`, `pdf`, `labelsPdf`): `labels` adds per-piece label data (`labels[]`, see `Label2D`), `planHash` a 64-hex fingerprint of the plan (the same plan always gives the same hash), `pdf` the cutting-plan PDF and `labelsPdf` the label PDF, both base64-encoded and drawn by the same code as the CutOptim app. These four are 2D only: a 1D or wood request returns a `warnings` entry instead. `pdf` renders at most 500 parts (total quantity); a larger 2D request with `pdf` is a 413 `too_large` with `details.path: "include"`. Export and data tokens do not affect narrowing, so `["svg"]` adds svg and — listing no narrowing token — drops cutPlan/offcuts; use `["cutPlan","offcuts","svg"]` to keep everything. */
+    include?: Array<"cutPlan" | "offcuts" | "svg" | "csv" | "dxf" | "labels" | "planHash" | "pdf" | "labelsPdf">;
+}
+/** One blade movement, in physically executable order (parent before children: you cannot crosscut a strip before you have ripped it off). */
+export interface CutStep {
+    /** 0-based index into `sheets` (2D) or `rods` (1D). Named `sheet` in both. */
+    sheet: number;
+    /** 1-based order within THIS sheet/rod. It RESTARTS at 1 on every sheet — it is not a running number across the whole job. */
+    step: number;
+    /** `h` = a horizontal cut line: the blade travels along x and separates top from bottom. `v` = a vertical cut line: the blade travels along y and separates left from right. In 1D `axis` is always `v`. */
+    axis: "h" | "v";
+    /** The blade's LOW-COORDINATE edge, not its centre line: the `y` value for `h`, the `x` value for `v`. The kerf occupies `pos` to `pos + kerf`, i.e. it advances in the direction the coordinate GROWS — downward for `h`, rightward for `v` (see the coordinate system in `info.description`). The material on the low side of the line — above it for `h`, to its left for `v` — is the piece that cut frees. In 1D `pos` is the offset along the bar at which that part is freed, measured from the bar end that `trim.start` trims. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    pos: number;
+    /** How far the blade travels for this cut — the extent of the REGION it crosses, not the whole board (the industry convention). Always `0` in 1D: a bar crosscut has no travel distance to report. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    length: number;
+    /** 1-based machine pass. Starts at 1 and increments ONLY when the axis flips relative to the parent cut, so ripping a board into six strips is one stage and crosscutting them is the next. This is the panel-saw sense of "3-stage cutting", not tree depth, and it is what `options.maxCutStages` constrains. */
+    stage: number;
+}
+/** A part on a board. `x`/`y` is its top-left corner measured from the top-left corner of the sheet, `x` growing right and `y` growing downward. */
+export interface PlacedPart2D {
+    /** The requested `name`, or the generated default `Part <1-based row index>`. */
+    name: string;
+    /** Distance from the sheet's left edge. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    x: number;
+    /** Distance from the sheet's top edge. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    y: number;
+    /** PLACED width — already swapped with the requested height when `rotated` is true. No client-side swap needed. */
+    w: number;
+    /** PLACED height. See `w`. */
+    h: number;
+    /** True if the part was turned 90° from the requested `w`×`h` — also when its `grain` made the turn necessary. Informational: `w`/`h` here already reflect it. */
+    rotated: boolean;
+    /** Opaque JSON object (any keys) echoed back VERBATIM on the matching output (a part's meta on every placed piece of it; a stock row's meta on every sheet/rod cut from it). Attach ERP article numbers, order-line ids, customer refs to reconcile the cut plan with your system. Never parsed, never affects placement. Part meta follows its request row: the meta of each row lands on exactly its qty of placed pieces, even when rows share a name; stock meta by stock-row order. */
+    meta?: Record<string, unknown>;
+    matchedSet?: PlacedMatchedSet;
+}
+/** Present ONLY on a placed member of a matched set (never in a request without `matchedSets`): which set and instance it belongs to and where in it. `position` counts the members in reading order on the cabinet front — top to bottom, left to right — from 1; with the set's `letter` it is the code the `csv` `Position` column and the `svg` labels print (A1, A2 …). */
+export interface PlacedMatchedSet {
+    /** The set's `id`, as a string. */
+    id: string;
+    /** Which instance of the set (1 … `qty`). */
+    instance: number;
+    /** The member's place in reading order, from 1. */
+    position: number;
+    /** Where it sits, when that is unambiguous (a row or column of 2–3 plain members). Absent otherwise. */
+    hint?: "left" | "middle" | "right" | "top" | "bottom";
+}
+/** One requested matched set: what became of its instances. Present ONLY in a request with sets. */
+export interface MatchedSetSummary {
+    /** The set's `id`, as a string. */
+    id: string;
+    /** A, B … in request order — the letter of the `csv` `Set` column and the `svg` frame badge. */
+    letter: string;
+    /** The set's `name`, when one was sent. */
+    name?: string;
+    /** Instances asked for (`qty`). */
+    requested: number;
+    /** Instances cut as ONE block, members side by side on a sheet. */
+    asBlock: number;
+    /** Instances whose block fit no stock sheet, so the members were placed one by one (`onMiss: "split"`) — or, in a material-aware job with NO stock of the set's material, went to `unmatchedMaterials` like every part of that material. */
+    split: number;
+    /** Instances whose members are listed in `unplaced` (`onMiss: "unplaced"`, or no room left on the sheets) — or in `unmatchedMaterials` when the job has no stock of the set's material. */
+    unplaced: number;
+    /** The block in the set's own frame: the members plus one kerf between them. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    block: {
+        w: number;
+        h: number;
+    };
+    /** One line per problem, each starting with its code: `align:` (the lines are not flush), `gap:` (the kerf is wider than `installGap`; both judged at 1/64 of your unit or a quarter kerf, whichever is smaller), `grain:` (the set's grain overrides the own grain of the members it names), `split:` / `unplaced:` (the block did not go on a sheet), `unmatched:` (no stock of the set's material), `priority:` (it may lose its place under `respectStock`), `grainGroup:` (the members are in different grainGroups). Empty when all is well. */
+    warnings: Array<string>;
+}
+/** A leftover rectangle, in the same coordinate system as the placements. */
+export interface Rect {
+    /** Distance of the leftover's top-left corner from the sheet's left edge. */
+    x: number;
+    /** Distance of the leftover's top-left corner from the sheet's top edge. */
+    y: number;
+    /** Width of the leftover. */
+    w: number;
+    /** Height of the leftover. */
+    h: number;
+}
+export interface Sheet {
+    /** FULL sheet width as supplied in `stock`, trim included — not the usable width. */
+    w: number;
+    /** FULL sheet height, trim included. */
+    h: number;
+    /** The `price` of the stock row this sheet came from, or `null` if none was given. */
+    price: number | null;
+    /** Placements on this sheet. */
+    parts: Array<PlacedPart2D>;
+    /** Usable leftovers, filtered by `options.minOffcut`. ABSENT (not empty) when `include` excludes `offcuts`. */
+    offcuts?: Array<Rect>;
+    /** The material this sheet (and every part/offcut on it) was cut from. Absent when the job carries no material. */
+    material?: string;
+    /** The stock row's `grain`, echoed: which side of this sheet the grain runs along; every grained part on it lies with its grain along that side. Absent when the row has none. */
+    grain?: "w" | "h";
+    /** Opaque JSON object (any keys) echoed back VERBATIM on the matching output (a part's meta on every placed piece of it; a stock row's meta on every sheet/rod cut from it). Attach ERP article numbers, order-line ids, customer refs to reconcile the cut plan with your system. Never parsed, never affects placement. Part meta follows its request row: the meta of each row lands on exactly its qty of placed pieces, even when rows share a name; stock meta by stock-row order. */
+    meta?: Record<string, unknown>;
+}
+/** Aggregate numbers for the whole job. */
+export interface Metrics2D {
+    /** Sheets used. Equals `sheets.length`. */
+    sheetCount: number;
+    /** Placed part area ÷ total FULL sheet area × 100, rounded to 2 decimals. Trim and kerf count as waste, which is why a trimmed job scores lower than a bare area sum. */
+    yieldPct: number;
+    /** Pieces placed, after `qty` expansion. */
+    placed: number;
+    /** Pieces requested, after `qty` expansion. */
+    total: number;
+    /** Collinear cuts merged: same axis, same coordinate, same stage count once. Physically "how many fence settings the operator makes". Deliberately NOT claimed to equal any competitor's count — only measured to land in the same range. */
+    cutLines: number;
+    /** Every cut, one per strip crossed — how many separate passes the saw makes. */
+    sawPasses: number;
+    /** Total distance sawn, summed over every cut, rounded to 3 decimals. Convention-independent: merging collinear cuts does not shorten the material. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    cutLength: number;
+    /** Sum of the used sheets’ prices, rounded to 2 decimals. `0` when no stock row carried a `price`. */
+    totalPrice: number;
+}
+/** Parts that did not fit, aggregated back by name + dimensions. */
+export interface Unplaced2D {
+    /** The part name. */
+    name: string;
+    /** As requested. */
+    w: number;
+    /** As requested. */
+    h: number;
+    /** How many of this part are unplaced. */
+    qty: number;
+}
+export interface Timing {
+    /** Wall-clock milliseconds spent inside the packer, rounded to 2 decimals. Excludes parsing, authorization and queueing. */
+    solveMs: number;
+}
+export interface EdgeBandingByType {
+    /** The caller-supplied type reference this metreage is grouped under. */
+    reference: string;
+    /** Linear metres of this reference, rounded to 3 decimals. See `EdgeBanding` for the millimetre assumption. */
+    meters: number;
+}
+export interface EdgeBandingByPart {
+    /** The part label, or `Part <1-based row>` when the request omitted a name. */
+    name: string;
+    /** Total banded metres for this part row, already multiplied by `qty`, rounded to 3 decimals. */
+    meters: number;
+    /** This part's metreage split by reference. */
+    byType: Array<EdgeBandingByType>;
+}
+export interface LabelEdge {
+    /** The banding type reference exactly as sent in `edgeBanding`. */
+    reference: string;
+    /** Length of this edge on one piece: the entered `w` for top/bottom, the entered `h` for left/right. */
+    length: number;
+}
+/** Label data for one placed piece. `w`/`h` are the ENTERED size, `rotated` says the piece was turned 90 degrees on the sheet, `x`/`y` equal the placed position in `sheets[sheet].parts`. `edges` are in the entered orientation and list only banded sides. */
+export interface Label2D {
+    /** Index into `sheets`. */
+    sheet: number;
+    /** The part name, as on the placed piece in `sheets[sheet].parts`. */
+    name: string;
+    /** 1-based row of the request `parts` array this piece came from. */
+    partNo: number;
+    /** The ENTERED width — not swapped when the piece was rotated on the sheet. */
+    w: number;
+    /** The ENTERED height — not swapped when the piece was rotated on the sheet. */
+    h: number;
+    /** True when the piece was turned 90 degrees on the sheet. */
+    rotated: boolean;
+    /** Placed position on the sheet, the same as the piece in `sheets[sheet].parts`. */
+    x: number;
+    /** Placed position on the sheet, the same as the piece in `sheets[sheet].parts`. */
+    y: number;
+    /** Material of the sheet it was cut from; absent when unspecified. */
+    material?: string;
+    /** The part's own grain axis as entered; absent when none. */
+    grain?: "w" | "h";
+    /** Banded sides only, in the entered orientation (a `LabelEdge` each); absent when the part has no banding. */
+    edges?: {
+        top?: LabelEdge;
+        right?: LabelEdge;
+        bottom?: LabelEdge;
+        left?: LabelEdge;
+    };
+    /** Opaque JSON object (any keys) echoed back VERBATIM on the matching output (a part's meta on every placed piece of it; a stock row's meta on every sheet/rod cut from it). Attach ERP article numbers, order-line ids, customer refs to reconcile the cut plan with your system. Never parsed, never affects placement. Part meta follows its request row: the meta of each row lands on exactly its qty of placed pieces, even when rows share a name; stock meta by stock-row order. */
+    meta?: Record<string, unknown>;
+}
+/** Linear metres of edge banding the order consumes, grouped by the caller-supplied type reference and reported per part AND as an order total. Present ONLY when at least one part requested banding, so a banding-free response omits the key. Exact geometry, no waste margin — the workshop adds its own. ⚠️ The metres ASSUME MILLIMETRE input: top and bottom edges run the part width, left and right run the height, multiplied by qty, divided by 1000. This is the one response figure named for a unit (edge banding is bought by the metre, and the division only means metres in millimetres); in another unit the raw edge length is w/h × qty and these numbers are that divided by 1000. 2D only. */
+export interface EdgeBanding {
+    /** Order-wide total across every banded edge, rounded to 3 decimals. */
+    totalMeters: number;
+    /** Order total split by reference, sorted by reference. */
+    byType: Array<EdgeBandingByType>;
+    /** One entry per requested part row that has any banded edge. */
+    byPart: Array<EdgeBandingByPart>;
+}
+export interface Optimize2DResponse {
+    /** Which engine actually ran. `max` appears only inside the `result` of a finished async job (GET /v1/jobs/{id}), never in a synchronous 200. */
+    engine: "heuristic" | "balanced" | "max";
+    /** Algorithm identity: the package version plus a content hash of the algorithm source. Changes automatically whenever the packer changes, and independently per engine. Pin or compare this if you cache. */
+    engineVersion: string;
+    /** Shape version, matching the `/v1/` in the path. Currently `"1"`. */
+    contractVersion: string;
+    /** Always true. Present so a client can assert the guarantee it relies on. */
+    deterministic: true;
+    /** One entry per sheet used, in cutting order. */
+    sheets: Array<Sheet>;
+    metrics: Metrics2D;
+    /** The sawing plan, ordered. `null` when `guillotineValid` is false — a non-guillotine layout has no edge-to-edge cut sequence, so there is nothing honest to return. ABSENT entirely when `include` excludes `cutPlan`. In 2D `step` restarts per sheet. */
+    cutPlan?: Array<CutStep> | null;
+    /** Parts that did not fit, aggregated by name + size. Empty when everything fitted. */
+    unplaced: Array<Unplaced2D>;
+    /** Human-readable notes about the plan: unplaced parts, an unsatisfiable `maxCutStages`, a grain group split across sheets, a non-guillotine layout, options the chosen engine does not model, or — in a request with `matchedSets` — a set not cut as one block (the detail per set is in `matchedSets[].warnings`) and the `pdf` / `labelsPdf` note below. Free text — do not parse it; branch on `unplaced`, `guillotineValid`, `metrics` and `matchedSets` instead. */
+    warnings: Array<string>;
+    /** True when the layout can be produced with edge-to-edge cuts, i.e. on a panel saw. False is information, not an error: the nesting is denser but a panel saw cannot make it. `heuristic` is always true; `balanced` often is not. */
+    guillotineValid: boolean;
+    edgeBanding?: EdgeBanding;
+    /** Per-material rollup (sheet count, yield, placed, requested total, price). The flat `sheets` stay the primary output — each carries `material`. ABSENT for a material-free job, which stays byte-identical. */
+    materials?: Array<MaterialSummary2D>;
+    /** Demand whose material has NO matching-material stock (distinct from `unplaced` = did not fit; the fix is to declare/buy the material). ABSENT when there is no mismatch. */
+    unmatchedMaterials?: Array<UnmatchedMaterial2D>;
+    /** One entry per requested matched set, in request order. ABSENT for a request without sets. */
+    matchedSets?: Array<MatchedSetSummary>;
+    /** Inline SVG of the 2D layout (self-contained, no external references). Present ONLY when `include` contains `svg`. 2D only. With `matchedSets` the part labels carry the position code (A1, A2 …) and a `matched-sets` group draws each set's frame (`options.setOutlines: false` leaves the group out). */
+    svg?: string;
+    /** Inline CSV cut list. Present ONLY when `include` contains `csv`. With `matchedSets` two columns, `Set` and `Position`, are appended at the end of every row. */
+    csv?: string;
+    /** Inline DXF (R12/AC1009) on layers STOCK/PARTS/LABELS. Present ONLY when `include` contains `dxf`. With `matchedSets` the LABELS text of a member carries its position code. */
+    dxf?: string;
+    /** Per-piece label data, one entry per placed piece in plan order. Present ONLY when `include` contains `labels`. 2D only. */
+    labels?: Array<Label2D>;
+    /** sha256 hex fingerprint (64 hex characters) of the canonical plan: the same plan always gives the same hash. Present ONLY when `include` contains `planHash`. 2D only. */
+    planHash?: string;
+    /** Worksheet (cutting-plan) PDF of this plan, base64, drawn by the same code as the CutOptim app. Present ONLY when `include` contains `pdf`; at most 500 parts (total quantity), else 413 `too_large`. 2D only. With `matchedSets` the members are drawn as ordinary parts, with no set frame or position code, and `warnings` says so — the set marks are in `sheets[].parts[].matchedSet`, `csv` and `svg`. */
+    pdf?: string;
+    /** Label PDF of this plan, base64. Present ONLY when `include` contains `labelsPdf`. 2D only. With `matchedSets` the members get ordinary labels, with no position code, and `warnings` says so. */
+    labelsPdf?: string;
+    timing: Timing;
+}
+/** One material's totals across the sheets cut from it. */
+export interface MaterialSummary2D {
+    /** The tag exactly as you sent it. Free text, matched exactly. */
+    material: string;
+    /** Sheets cut from this material. */
+    sheetCount: number;
+    /** Used area ÷ total area of THIS material's sheets, %. */
+    yieldPct: number;
+    /** Parts of this material placed. */
+    placed: number;
+    /** Parts of this material requested (Σ qty). */
+    total: number;
+    /** Sum of the prices of the sheets used for this material. */
+    totalPrice: number;
+}
+/** Demand of a material for which the job supplied ZERO stock of that material. */
+export interface UnmatchedMaterial2D {
+    /** The tag that has no stock of its own anywhere in the request. */
+    material: string;
+    /** The demand rows in that material, in the 2D unplaced shape: name, w, h, qty. */
+    parts: Array<Unplaced2D>;
+}
+export interface PlacedPart1D {
+    /** The requested name, or the generated default. */
+    name: string;
+    /** Offset of the part’s NEAR end from the bar end that `trim.start` trims. The first part therefore starts at `trim.start`, and each subsequent `pos` adds one kerf. Unit-agnostic: pick one unit (mm, inch, …) for every length in the request and every length in the response is in that same unit. Nothing is converted server-side. */
+    pos: number;
+    /** The part length, as requested. */
+    length: number;
+    /** Opaque JSON object (any keys) echoed back VERBATIM on the matching output (a part's meta on every placed piece of it; a stock row's meta on every sheet/rod cut from it). Attach ERP article numbers, order-line ids, customer refs to reconcile the cut plan with your system. Never parsed, never affects placement. Part meta follows its request row: the meta of each row lands on exactly its qty of placed pieces, even when rows share a name; stock meta by stock-row order. */
+    meta?: Record<string, unknown>;
+}
+export interface Rod {
+    /** FULL bar length as supplied in `stock`. */
+    length: number;
+    /** Price of the stock row, or `null`. */
+    price: number | null;
+    /** USABLE off-cut left on this bar, rounded to 3 decimals: the kerf of the cut that frees it from the last piece is already deducted, so it is the reclaimable length, not the raw gap. Reported even when it is below `options.minOffcut` — `minOffcut` filters `offcuts`, not this. */
+    remaining: number;
+    /** In cutting order along the bar. */
+    parts: Array<PlacedPart1D>;
+    /** At most one entry: `[remaining]` when it is greater than 0 and at least `options.minOffcut`, otherwise `[]`. ABSENT when `include` excludes `offcuts`. */
+    offcuts?: Array<number>;
+    /** The material this rod was cut from. Absent when the job carries no material. */
+    material?: string;
+    /** Opaque JSON object (any keys) echoed back VERBATIM on the matching output (a part's meta on every placed piece of it; a stock row's meta on every sheet/rod cut from it). Attach ERP article numbers, order-line ids, customer refs to reconcile the cut plan with your system. Never parsed, never affects placement. Part meta follows its request row: the meta of each row lands on exactly its qty of placed pieces, even when rows share a name; stock meta by stock-row order. */
+    meta?: Record<string, unknown>;
+}
+export interface Metrics1D {
+    /** Bars used. Equals `rods.length`. */
+    rodCount: number;
+    /** Placed length ÷ total FULL bar length × 100, rounded to 2 decimals. Trim and kerf count as waste. */
+    yieldPct: number;
+    /** Pieces placed, after `qty` expansion. */
+    placed: number;
+    /** Pieces requested, after `qty` expansion. */
+    total: number;
+    /** Total crosscuts across all used bars — one per placed piece, since each piece is freed by a cut at its far end. There is no length to report for a bar cut, which is why 1D has no `cutLength`. */
+    cuts: number;
+    /** Sum of used bar prices, rounded to 2 decimals. */
+    totalPrice: number;
+    /** How many pieces fitted only because `options.tolerance` allowed an overshoot. */
+    toleranceAcceptedCount: number;
+}
+export interface Unplaced1D {
+    /** The part name. */
+    name: string;
+    /** As requested. */
+    length: number;
+    /** How many could not be placed. */
+    qty: number;
+}
+export interface Optimize1DResponse {
+    engine: "heuristic" | "balanced";
+    engineVersion: string;
+    contractVersion: string;
+    deterministic: true;
+    rods: Array<Rod>;
+    metrics: Metrics1D;
+    /** One step per placed piece. `sheet` is the ROD index and `step` restarts at 1 on each rod; `axis` is always `v`, `length` always 0 and `stage` always 1. ABSENT when `include` excludes `cutPlan`. Unlike 2D it is never `null` in practice, because a linear plan is always producible. */
+    cutPlan?: Array<CutStep> | null;
+    unplaced: Array<Unplaced1D>;
+    warnings: Array<string>;
+    /** Per-material rollup (rod count, yield, placed, requested total, price). Each rod carries `material`. ABSENT for a material-free job. */
+    materials?: Array<MaterialSummary1D>;
+    /** Demand whose material has NO matching-material stock (distinct from `unplaced`). ABSENT when there is no mismatch. */
+    unmatchedMaterials?: Array<UnmatchedMaterial1D>;
+    /** Inline CSV cut list. Present ONLY when `include` contains `csv`. */
+    csv?: string;
+    /** Inline DXF (R12/AC1009). Present ONLY when `include` contains `dxf`. (`svg` is 2D only — a warning is returned instead.) */
+    dxf?: string;
+    timing: Timing;
+}
+/** One material's totals across the rods cut from it. */
+export interface MaterialSummary1D {
+    /** The tag exactly as you sent it. Free text, matched exactly. */
+    material: string;
+    /** Bars cut from this material. */
+    rodCount: number;
+    /** Placed length ÷ total bar length of THIS material's rods, %. */
+    yieldPct: number;
+    /** Parts of this material placed. */
+    placed: number;
+    /** Parts of this material requested (Σ qty). */
+    total: number;
+    /** Sum of the prices of the bars used for this material. */
+    totalPrice: number;
+}
+/** Demand of a material for which the job supplied ZERO stock of that material. */
+export interface UnmatchedMaterial1D {
+    /** The tag that has no stock of its own anywhere in the request. */
+    material: string;
+    /** The demand rows in that material, in the 1D unplaced shape: name, length, qty. */
+    parts: Array<Unplaced1D>;
+}
+/** A `CutStep` that also names its cross-section. ⚠️ `sheet` is the rod index WITHIN that section, not a job-wide rod counter — pair `section` + `sheet` to locate the bar. */
+export type WoodCutStep = (CutStep);
+/** One cross-section's own totals — no need to re-derive them from `rods`. */
+export interface MetricsSection {
+    /** Bars used in this section. */
+    rodCount: number;
+    /** Placed length ÷ full bar length × 100 FOR THIS SECTION, 2 decimals. */
+    yieldPct: number;
+    /** Pieces of this section placed, after `qty` expansion. */
+    placed: number;
+    /** Pieces of this section requested, after `qty` expansion. */
+    total: number;
+    /** Crosscuts in this section — one per placed piece. */
+    cuts: number;
+    /** Sum of this section's used bar prices, 2 decimals. */
+    totalPrice: number;
+}
+export interface WoodSection {
+    /** Normalised key `<short>x<long>`, e.g. `50x100` — short side first, so 50×100 and 100×50 are one section. */
+    section: string;
+    /** Short side of the cross-section (normalised). */
+    sw: number;
+    /** Long side of the cross-section (normalised). */
+    sh: number;
+    /** Label of the stock row matched to this section, or `null` if none was given. */
+    stockName: string | null;
+    /** The section's material. Two materials at one cross-section are TWO sections. Absent when the job carries no material. */
+    material?: string;
+    /** Identical shape to a 1D rod. */
+    rods: Array<Rod>;
+    metrics: MetricsSection;
+    /** Parts of THIS section that had stock but did not fit in it. */
+    unplaced: Array<Unplaced1D>;
+}
+/** Demand for a cross-section you supplied NO stock for. Deliberately separate from `unplaced`: the fix is to declare or buy the material, not to add length or relax a limit. */
+export interface WoodUnmatched {
+    /** The cross-section key nothing in stock matched. */
+    section: string;
+    /** That cross-section's two sides (normalised: short, long). */
+    sw: number;
+    /** That cross-section's two sides (normalised: short, long). */
+    sh: number;
+    /** Set when the section exists but only in a DIFFERENT material. */
+    material?: string;
+    /** The demand rows in that section, in the 1D unplaced shape: name, length, qty. */
+    parts: Array<Unplaced1D>;
+    /** Total pieces in this section, summed over `parts`. */
+    qty: number;
+}
+/** Job-wide totals across every section. */
+export interface MetricsWood {
+    /** Cross-sections that were solved. Equals `sections.length`; excludes `unmatched` sections. */
+    sectionCount: number;
+    /** Bars used across every section. */
+    rodCount: number;
+    /** Job-wide placed length ÷ full bar length × 100, 2 decimals. Computed over the bars actually used, so an `unmatched` section neither helps nor hurts it. */
+    yieldPct: number;
+    /** Pieces placed across every section. */
+    placed: number;
+    /** Every piece requested — INCLUDING those in `unmatched` sections. */
+    total: number;
+    /** Crosscuts across every used bar. */
+    cuts: number;
+    /** Sum of the used bars’ prices, 2 decimals. */
+    totalPrice: number;
+    /** How many pieces fitted only because `options.tolerance` allowed an overshoot. */
+    toleranceAcceptedCount: number;
+}
+export interface OptimizeWoodResponse {
+    engine: "heuristic" | "balanced";
+    engineVersion: string;
+    contractVersion: string;
+    deterministic: true;
+    /** Replaces `rods` at the top level: one entry per cross-section that had matching stock, in request order — each matched to its own stock and solved on its own. */
+    sections: Array<WoodSection>;
+    unmatched: Array<WoodUnmatched>;
+    metrics: MetricsWood;
+    /** One step per placed piece across all sections — as 1D, except every step also carries `section`, and `sheet` is the rod index WITHIN that section, not a job-wide counter. ABSENT when `include` excludes `cutPlan`. Never `null` in practice — a linear plan is always producible. */
+    cutPlan?: Array<WoodCutStep> | null;
+    /** Did-not-fit parts aggregated across sections that DID have stock. Parts with no stock at all are in `unmatched` instead. */
+    unplaced: Array<Unplaced1D>;
+    warnings: Array<string>;
+    /** Inline CSV cut list. Present ONLY when `include` contains `csv`. */
+    csv?: string;
+    /** Inline DXF (R12/AC1009). Present ONLY when `include` contains `dxf`. (`svg` is 2D only — a warning is returned instead.) */
+    dxf?: string;
+    timing: Timing;
+}
+export interface UsageResponse {
+    /** The tier slug frozen onto the key when it was minted. Re-pricing the product later does not rewrite a live key. */
+    plan: string;
+    /** Calls counted in the current UTC calendar month, across EVERY key on the account — revoked keys included, so revoking a key cannot un-spend what it spent (053) — not just the one you called with. The quota is account-wide. */
+    used: number;
+    /** The monthly cap for the ACCOUNT: the largest monthly quota frozen onto any of its ACTIVE keys (049). All active keys draw on this one allowance; creating more keys does not create more quota. Keys are for separating environments and integrations (and for revoking one without disturbing the rest). */
+    limit: number;
+    /** `limit` − `used`, never negative. */
+    remaining: number;
+    /** First day of next month as `YYYY-MM-DD` — a DATE, not a timestamp. The counter resets at 00:00 UTC on that day. */
+    periodEnd: string;
+    /** Non-secret display prefix of the calling key, so you can tell which key you queried. The key itself is never returned by any endpoint. */
+    keyPrefix: string;
+    /** Shape version. Currently `"1"`. */
+    contractVersion: string;
+    /** Present (`"test"`) only for a TEST key: created in the dashboard, never billed, with its own monthly allowance separate from the live keys. Absent for a live key — a live key gets exactly the body it always got. */
+    env?: "test";
+    /** Present (`"tenant"`) only for a key CutOptim issues to its own first-party service. Absent for every key you create in the dashboard. */
+    keyClass?: "tenant";
+}
+export interface HealthResponse {
+    /** Always `"healthy"` when the process answers. */
+    status: "healthy";
+    /** Always `"cutoptim-engine"`. */
+    service: "cutoptim-engine";
+    /** Shape version. Currently `"1"`. */
+    contractVersion: string;
+    /** The DEFAULT engine's version (`heuristic`), not a per-engine list. */
+    engineVersion: string;
+    /** SYNCHRONOUS engine ids this deployment accepts in `engine`. The asynchronous `max` tier is reported in `maxEngines`, never here — it does not answer in-line. */
+    engines: Array<"heuristic" | "balanced">;
+    /** Optimize paths this deployment serves, so the endpoint set is discoverable without reading the docs — the same role `engines` plays for engine ids. `nest` is listed only where the nesting engine is built in. */
+    modes: Array<"2d" | "1d" | "wood" | "nest">;
+    /** Nesting engine ids this deployment can serve (empty where the nesting engine is not built in). `max` (async, preview) appears only where its binary is built in and the async tier is switched on — like `maxEngines`, built for, not a live worker check (the production API lists both). */
+    nestEngines?: Array<"lbf" | "max">;
+    /** The asynchronous tree-search tier this deployment is BUILT for — `["max"]` where the binary is present and the tier is switched on, `[]` otherwise. ⚠️ Built for is not the same as ready right now: this endpoint deliberately reads no database (a datastore outage must not take health down with it), so it cannot see whether the worker that solves the jobs is alive. A submission can therefore still answer 503 while this list contains `"max"`. An empty list means never; a populated one means normally. */
+    maxEngines?: Array<"max">;
+    /** Whole seconds since process start. */
+    uptimeSec: number;
+}
+export type Optimize2dBody = Optimize2DRequest;
+export type Optimize2dResult = Optimize2DResponse | {
+    /** Poll GET /v1/jobs/{id} with this id. */
+    jobId: string;
+    /** Always `queued` at submission. */
+    status: "queued";
+    mode: "2d";
+    engine: "max";
+    /** Suggested delay before the first poll. */
+    pollAfterMs: number;
+    quota?: {
+        reserved?: number;
+        used?: number;
+        limit?: number;
+    };
+};
+export type Optimize1dBody = Optimize1DRequest;
+export type Optimize1dResult = Optimize1DResponse;
+export type OptimizeWoodBody = OptimizeWoodRequest;
+export type OptimizeWoodResult = OptimizeWoodResponse;
+export type OptimizeNestBody = OptimizeNestRequest;
+export type OptimizeNestResult = OptimizeNestResponse | {
+    /** Poll GET /v1/jobs/{id} with this id. */
+    jobId: string;
+    /** Always `queued` at submission. */
+    status: "queued";
+    mode: "nest";
+    engine: "max";
+    /** Suggested delay before the first poll (the search runs for its time budget). */
+    pollAfterMs: number;
+    quota?: {
+        reserved?: number;
+        used?: number;
+        limit?: number;
+    };
+};
+export type Validate2DBody = Optimize2DRequest;
+export type Validate2DResult = ValidateResponse;
+export type Validate1DBody = Optimize1DRequest;
+export type Validate1DResult = ValidateResponse;
+export type ValidateWoodBody = OptimizeWoodRequest;
+export type ValidateWoodResult = ValidateResponse;
+export type ValidateNestBody = OptimizeNestRequest;
+export type ValidateNestResult = ValidateResponse;
+export type GetJobResult = {
+    jobId: string;
+    status: "queued" | "running" | "succeeded" | "failed";
+    /** Which optimize path the job came from; decides the shape of `result`. */
+    mode: "2d" | "nest";
+    engine: "max";
+    /** Present only when `status` is `succeeded`: an `Optimize2DResponse` for `mode: "2d"`, an `OptimizeNestResponse` for `mode: "nest"`. */
+    result?: Optimize2DResponse | OptimizeNestResponse;
+    /** Present only when `status` is `failed`. */
+    error?: string;
+    /** When the job was submitted. */
+    createdAt?: string;
+    /** `null` while `queued` or `running`. */
+    finishedAt?: string | null;
+};
+export type ImportNestBody = NestImportRequest;
+export type ImportNestResult = NestImportResponse;
+export type GetUsageResult = UsageResponse;
+export type GetHealthResult = HealthResponse;