@spec write(Smith.Assembly.Result.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Writes an assembly bundle and publishes its checked records to current.json.

result must be an evaluated Smith.Assembly.Result. root is created as needed. Returns {:ok, report} after every manufactured part passes mesh checks and every requested STEP passes a round trip.

Options

Mesh deflections must exceed 1.0e-7. Per-part names are normalized as in Smith.Assembly.fetch/2; unknown names or duplicate normalized keys fail. Paths accept lists such as [:left, :base] or slash strings such as "left/base". A single name still addresses a top-level leaf. Metadata tuples become JSON arrays. Generated assembly, part, and exploded-offset fields override colliding per-part metadata keys.

Print/display placement comes from assembly member options, not this option list. Part bundles follow Smith.Export.write/3, with installed preview orientation. Top-level names remain <assembly>-<part>. Nested paths join normalized segments with __, as in fixture-left__base. Normalized segments contain no underscores, so this encoding is unambiguous.

Files and report

The assembly directory is root/name/revision/export_id/. It contains assembly.brep and assembly.json, plus assembly.step when requested. References get references-DO-NOT-PRINT.step when STEP is requested and references exist. printables.zip contains the selected STL/3MF files for every manufactured part; STEP-only exports have no ZIP.

The returned report contains :name, :revision, :export_id, :assembly_step, :references_step, :print_pack, :report, :formats, :metadata, :parts, :references, :tree, :joints, and :connections. It also includes :step_relative_volume_error and :references_step_relative_volume_error. Unrequested paths/checks are nil. Part records follow Smith.Export.write/3 without the display mesh, plus :assembly, :part, and :installed. Reference records contain name and revision. Part identities and reference names use slash paths. File paths retain the form of the supplied root.

:tree is a list of nodes in insertion order. Each has normalized :name, :path segments, :kind, effective :installed, :revision, and local :options, plus a resolved world :pose frame. Subassembly nodes also have :children, :joints, and :connections. Display/exploded offsets in part reports accumulate world vectors from all ancestors. Print options remain on leaves and act on their final world geometry.

Joint records contain normalized name, member path relative to their containing assembly, and final world frame. Connection records contain normalized :from and :to joint paths, motion :kind, coordinate :values, and :limits. These describe the evaluated pose; STEP contains geometry without joint semantics.

Checks and failures

Every member and subassembly shape must agree with its recorded revision. Print meshes are checked even for STEP-only exports. Each emitted STEP is reimported and checked for native validity, solid count, and relative volume error. The combined STEP is an unfused compound, without named product-tree instances or materials. 3MF contains geometry, not slicer settings.

Passing an unevaluated assembly, a part result, or a non-string root returns {:error, :invalid_argument}. Other errors include :invalid_options, :invalid_metadata, revision and geometry errors, file-system errors, and {:export_failed, part_name, reason} for a failed part bundle. New files may remain after failure; the previous manifest is preserved. Successful replacement removes retired parts from the current assembly while preserving unrelated manifest records. See Smith.Export.mesh/3 for the scope and limits of mesh verification.