File format 17 for qualified piece names and sheet metal rim names (#700)

0.8.0 shipped format 16. Lineage names of a piece qualified by the faces around it, and sheet face names of a rim (rim.<edge>) or a bend end (rim.bend0/1), now come under format 17. Format 16 designs need no transformation, and the version stamp makes 0.8.0 ask for an update.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

crates/doc/src/format.rs

@@ -72,19 +72,22 @@
 //!   Sketch face anchors can name a flat face by its exact history name (a `lineage`
 //!   certificate: the target's `name`, e.g. a cut wall `F5:side:l1` or a pattern copy
 //!   `F4:[email protected]`), where no construction certificate names it alone. Anchors with
-//!   construction certificates resolve as before. A `lineage` name can also be a piece's own,
-//!   qualified by the faces around it (`F2:top#[F2:side:l4,F4:side:l4]`), where Offset Face
-//!   moved one piece of a face off the others' plane; never a numbered piece. Sheet face names
-//!   can also name a rim, the sheet's thickness along a panel's straight edge
-//!   (`sheet:<body>:<panel>:rim.<edge>`, the edge a base sketch line's id, `edge<k>`, or a
-//!   flange's `far`, `side0` or `side1`), or a flat end of a bend (`rim.bend0`, `rim.bend1`).
+//!   construction certificates resolve as before.
+//! - 17: a `lineage` face name can be a piece's own, qualified by the faces around it
+//!   (`F2:top#[F2:side:l4,F4:side:l4]`), where Offset Face moved one piece of a face off the
+//!   others' plane; never a numbered piece. Sheet face names can also name a rim, the sheet's
+//!   thickness along a panel's straight edge (`sheet:<body>:<panel>:rim.<edge>`, the edge a base
+//!   sketch line's id, `edge<k>`, or a flange's `far`, `side0` or `side1`), or a flat end of a
+//!   bend (`rim.bend0`, `rim.bend1`). Version 16 designs need no transformation; the version
+//!   stamp makes 0.8.0 (which reads up to 16) ask for an update instead of meeting names it
+//!   can't resolve.
 
 use serde_json::Value;
 
 use crate::{DocError, Document, Result};
 
 /// The format this build writes.
-pub const FORMAT: u32 = 16;
+pub const FORMAT: u32 = 17;
 
 pub fn format_string(n: u32) -> String {
     format!("solidcraft/{n}")
@@ -101,7 +104,7 @@ pub fn version_of(s: &str) -> Option<u32> {
 
 /// JSON-level upgrades: entry `i` turns format `i + 1` into `i + 2`.
 type JsonStep = fn(&mut Value) -> Result<()>;
-const JSON_STEPS: [JsonStep; 15] = [
+const JSON_STEPS: [JsonStep; 16] = [
     |_| Ok(()),
     v2_to_v3,
     v3_to_v4,
@@ -117,6 +120,7 @@ const JSON_STEPS: [JsonStep; 15] = [
     v13_to_v14,
     |_| Ok(()),
     |_| Ok(()),
+    |_| Ok(()),
 ];
 
 /// Stored face and edge names were worked out from geometry before format 14; they get the

crates/engine/src/cmd/component_properties_tests.rs

@@ -241,7 +241,7 @@ fn user_defined_material_survives_save_and_reopen() {
     run(&mut s, "material.create", json!({"name": "Leather", "density_g_cm3": 0.86, "appearance": "Rubber - Black"}));
     run(&mut s, "material.assign", json!({"bodies": ["Tab"], "material": "Leather"}));
     run(&mut s, "file.save", json!({"path": path}));
-    assert!(s.doc.to_json().contains("\"solidcraft/16\""));
+    assert!(s.doc.to_json().contains("\"solidcraft/17\""));
 
     run(&mut s, "file.new", json!({}));
     run(&mut s, "doc.open", json!({"path": path}));

docs/book/src/guide/files.md

@@ -58,7 +58,7 @@ is available. Missing or incompatible pictures use the usual thumbnail generatio
 The default `cache: false` omits the portable thumbnail too.
 The repository's `docs/design-container.md` describes limits and encoding details.
 
-Current designs use format 16, including physical materials defined in the design, the font of sketch text, sheet metal corner relief shapes, sketch face anchors on cylinder caps, sketch axis
+Current designs use format 17, including face anchors on a piece of a face by its own name, sheet metal rims and bend ends, physical materials defined in the design, the font of sketch text, sheet metal corner relief shapes, sketch face anchors on cylinder caps, sketch axis
 links, persistent
 names from exact face history, exact planar shell-face anchors, persistent analytic offset boundary roles and
 association profile references, durable sketch face anchors, periodic fit splines and versioned

docs/design-container.md

@@ -7,7 +7,7 @@ self-contained input/output format. `io::write_design` keeps its JSON contract;
 `io::write_design_container` is the fallible container writer.
 
 Packages have `container.json` with `{"format":"solidcraft-container/1"}` and
-`document.json` with the versioned parametric document (currently `solidcraft/16`).
+`document.json` with the versioned parametric document (currently `solidcraft/17`).
 The independent versions let document migrations evolve without changing blob encodings.
 Existing serialized document fields are retained automatically, without a second copy
 of the document schema or a deep clone of embedded payloads.

docs/face-attachments.md

@@ -89,7 +89,9 @@ those pending positions; undo restores the previous attachment and placement sta
 
 File format 11 introduced these optional attachments, which format 12 also preserves. Format 16
 adds the `lineage` certificate (older readers ask for an update rather than meeting an unknown
-kind); anchors saved with construction certificates resolve as before. Existing designs with face references
+kind); anchors saved with construction certificates resolve as before. Format 17 adds piece
+names qualified by the faces around them and the sheet metal rim and bend-end names; 0.8.0
+asks for an update when it opens a format 17 design. Existing designs with face references
 without an attachment retain their legacy geometry and lookup behavior when opened; they
 are not silently upgraded. Redefining such a sketch onto a supported selected face creates
 the stronger attachment. Unsupported legacy geometry can instead be retained on an explicit