14. Preflight — the intake gate

kerfmaster pin list · Preflight — how files come in

rulingmixedd10deferred d14A decision by Aristide or Jordan. True because it was decided; it can be superseded, but it cannot be stale.

Content last changed 2026-08-21 — computed from the item itself, not typed.

Contract — Intake stage

This contract states a decision, not an implementation.

takes customer-file

makes identified-file

fails if A file entering preprocessing that failed a check, or passed one we never ran.

Contract last changed 2026-08-06 — computed, not typed. Dated separately from the text above, so neither date can speak for the other.

1 open question blocks this pin

Q4 "Strokes only, no fills" -- is that a hard rule we reject a file on, or a preference we heal around when a fill turns up?
Aristide — Three outcomes, and a fill has not been assigned to one of them.

⚠ Known defects

This item's subject has known defects in the code. Recorded and deliberately NOT fixed — recording a defect is not a licence to fix it. Source: cadmaster/defects.json → cadmaster/KNOWN_DEFECTS.md, not this page — the text below is generated from the register so the two can never disagree.

D10 — The vector board posts G-code before it decides PASS or FAIL
build_vec_board.py writes the fitted DXF, the geometry .nc, the production .nc, the slug CSV and the rapids CSV at lines 59-79. It computes the PASS/FAIL banner at lines 246-252, nearly two hundred lines later. A FAIL therefore leaves a full set of posted G-code on disk beside the failure notice.
Cost today: A failed file yields a plausible-looking .nc, with nothing to stop someone running it.
Verified: 2026-08-03 at 36a55a3. Directory listed; the FAIL string read out of its index.html.
D14 — The DXF parser reads BLOCK-definition geometry at block-local coordinates, ignores the INSERT that places it, and reports nothing skipped (DEFERRED)
dxf_io.parse walks the whole group-code stream and dispatches on six entity types -- POLYLINE, LWPOLYLINE, LINE, ARC, CIRCLE, SPLINE (dxf_io.py:113-244). It does not track SECTION, so a LINE sitting in the BLOCKS section is picked up exactly as if it were in ENTITIES, at its block-local coordinates. The INSERT that positions, scales and rotates that block is not an entity it knows, so it falls through the loop's trailing `i += 1` and is discarded. Every other entity type does the same: ELLIPSE, HATCH, SOLID, TEXT, MTEXT, DIMENSION, LEADER, 3DFACE, POINT, ATTRIB. There is no count of what was skipped and no warning.
Cost today: None measurable on any file cut so far -- every DXF we hold uses LWPOLYLINE only. The exposure is entirely on files we have not yet been given, which is precisely what the input survey exists to find out.
Verified: 2026-08-04. Probe written and run (cadmaster/probe_entities.py). CONTROL: the novi customer file parses unchanged at 91 polylines / 0 lines / 0 arcs / 0 circles / 0 splines, so this is a gap in coverage, not a regression. Entity list read off the code's own branches, not assumed. NOT YET RAISED WITH ARISTIDE OR JORDAN, and no fix attempted -- the phase rule says define first, and the first question is which of these entity types actually arrive from their customers, which only they can answer. DEFERRED by Jordan 2026-08-04, in his words: "Write it down as out of scope for now, but let's revisit this as part of our beta testing once the interface has been written." So this is closed to work and open on the record -- nobody should now go and fix it, and it must not be re-raised from the numbers. The revisit trigger is beta testing with real customer files arriving through an interface, which is also the only way to learn which of these entity types actually turn up. Written up for a reader on pin 14f, including a plainer explanation of the block/INSERT example, which Jordan reported was not clear the first time.

Raised by Aristide, 2026-08-01: "It needs to pass the test before we even submit it into the preprocessing for production. In the old Desktop publishing world they called it preflight?"

Yes — and it is exactly the right word to borrow. Preflight came out of prepress in the early 1990s (from the pilot's checklist), and it is a mature, proven idea: before a job goes anywhere near a press, an automated checker confirms the file actually contains everything needed to print it. The lineage is worth knowing because the problems rhyme with ours — Markzware FlightCheck, Enfocus PitStop, Adobe's own Preflight tool in Acrobat, and above all PDF/X (ISO 15930), a standard whose entire purpose is that a file either conforms or it does not. Missing fonts, missing images, wrong colour space, no bleed — caught at intake, not on the press.

Our press is a laser and our missing font is scale. Same shape of problem, same answer.

The principle

Preflight is a gate, not advice. A file that fails does not enter the pipeline in a degraded state, does not get a best guess applied, and does not get healed "as far as we can". It stops, and the customer is asked one clear question. Everything downstream — heal, QC, bridges, leads, tabs, cut order, nest, post — is allowed to assume the input is sane, because preflight is the thing that guarantees it.

This also protects us commercially. A scrapped sheet of stainless because somebody guessed the scale costs more than every preflight check we will ever run.

Three outcomes, never two

BLOCKED — we cannot proceed and cannot guess. Missing or contradictory scale, undecodable file, no vector content at all, exceeds the 80"×160" bed. Customer gets a plain-English question. Nothing enters preprocessing.
PASS WITH NOTES — we can proceed, and here is what we changed or noticed: curves re-fitted, gaps closed under the auto-close threshold, sub-kerf specks dropped, holes too small to meet pierce standoff. All listed, none silent.
PASS — clean file, nothing to say.

A binary pass/fail is wrong for this. Most real files are neither perfect nor unusable, and the middle case is where the customer learns something.

Deliverable

The preflight report is the comparison board (see Delivery), not a separate document — original art as the grey base layer, our reading of it on top, findings listed underneath. The customer sees what we saw. That is worth more than any wording.

Related: 14a delivery rules, 14b the scale gate, 14c the check list, 14d the uploader, 14e education.

⚑ Build state, 2026-08-21 (piece 3 of the customer-surface order, Aristide: “go”): the gate now RUNS as one flow — preflight.py. One entry point, preflight.run(), built to be called by the uploader (14d) when it exists; the CLI only renders the dict it returns (data in JSON, generator separate from presentation). The three outcomes are enforced as ruled: BLOCKED returns ONE customer question (blockers ranked; the rest ride in internal notes), PASS WITH NOTES lists everything noticed or to-be-changed, PASS says nothing. A BLOCKED file gets no estimate (14b: no scale, no quote). Measured: novi sign 0.06 s, TL-1016-82 (4,700 prims, splines) 1.4 s — inside 14d’s “seconds, while the customer is still on the page”.