How the pipeline works

Two rules run through every layer of the engine:

• Honesty — a feature is only claimed as built after its validators PASS; an unknown op / check / joint name is a load error, never a silent skip.
• The CAD boundary — import artifact_forge_ng never loads the CAD kernel. cadquery is an optional extra imported lazily by the compile step only; everything up to and including form validation is stdlib + pydantic + PyYAML.

The pipeline

product.yaml
  → catalog load (fail-fast binding of every name)
  → parameter resolve (units, expr, clamps, declaration order)
  → capability report (requested / supported / built / missing)
  → Form IR (exact line/arc profiles, semantic regions — NO CadQuery)
  → form validators (golden gate: CAD is not touched until these pass)
  → compile_part (CadQuery: profile extrusion, weld, blends, holes, fields)
  → geometry validators (topology / region / manufacturing probes)
  → contract + score (critical FAIL → grade F; the score can't mask it)
  → honesty report + STL/STEP

The pre-CAD half is shared by forge validate and forge build; the assembly pipeline runs each inline part through exactly the same code path.

Layer map

Layer	Responsibility
core	The Finding result shape, the scalar value grammar ("20mm", expr(...)), units, fastener tables.
product	Typed pydantic models of the grammar, parameter resolution, the capability resolver (requested vs supported vs built).
catalog	YAML → validated models with fail-fast name binding; merges built-in data, pack data dirs and the local catalog.
form	The Form IR: exact 2D section profiles, typed 3D features, semantic regions, form.* checks, recipe ops. CAD-free by architectural rule — enforced by a test.
validators	The KNOWN_CHECKS registry (importable without cadquery) plus geometry probes (loaded lazily).
compiler / cad	The CAD boundary. compile_part turns a PartForm into a solid — it never invents positions; every hole, cut and field comes from the IR.
assembly	Joint registry, deterministic pose math (no solver), IR joint checks without CAD, cross-part fit probes at build.
repair / review	Deterministic semantic repair (findings → YAML patches) and the review layer (honesty report, score with the critical-FAIL gate).
web	The local Product Cockpit. The UI shows what the pipeline produced — errors are structured findings, never a traceback.

The registry pattern

Three registries decouple catalog YAML from engine code. Declarations are importable without cadquery, implementations self-register at import time, and every name a YAML document uses binds fail-fast at catalog load:

Registry	Bound by
KNOWN_CHECKS	every validators:, forbidden_forms:, contract: and verified_by: entry
RECIPE_OPS	every op invocation in a form.type: recipe archetype
JOINT_TYPES	every joint in an assembly YAML

Recipe ops bind fail-fast twice over: the op name must exist, and every validator the op declares must appear in the archetype’s own validators: list — a builder can never ship geometry its checks won’t measure.

The Form IR

PartForm is the complete intermediate representation of one part — everything the CAD compiler consumes and everything the validators measure:

• Section profile — a closed loop of tagged line/arc segments in exact 2D coordinates. Mouth gaps and lip lengths are read from segment parameters, not from a mesh, so form validation needs no CAD kernel.
• Typed features — holes, bores, cut boxes, channels, ribs, pins, plates, perforation fields (already filtered against every keepout — countable, checkable, no guessing).
• Semantic regions — named regions the archetype declares, with roles and keepout semantics. The engineering views on registry pages are rendered straight from this data.
• Frame keys and datums — the inter-part contract. Joints pose part B by landing its datum on part A’s datum; the compatibility matrix (forge compat) is derived from declared interfaces, never hand-written.
• print_orientation — validators always measure in the part frame; only the exported STL/STEP are rotated, so a constant-section extrusion printed on its side has zero overhangs by construction.

Domain packs

A pack is an installed distribution that plugs archetypes, recipe ops, checks and joints into the same registries through one entry point in the artifact_forge_ng.packs group. Discovery is deterministic (sorted by name), idempotent, and fail-fast on collisions — a pack that overwrites an existing registration raises unless it explicitly declares the override. A broken pack is loud, never skipped. See Pack authoring.