Add persistent sketch-constraint system (ocs_gcs port) and named-parameters handoff docs

Ports FreeCAD's planegcs 2D geometric constraint solver to Rust as a new
crates/ocs_gcs workspace member, and wires it into the document/scene model
as a persistent SketchConstraintSet: Coincident, Horizontal/Vertical,
Parallel/Perpendicular, Equal, Tangent, Distance, Angle and Radius
constraints that re-solve live (including mid-drag, not just on release),
render glyphs and a DOF badge, flag conflicts with a one-click resolver
pill, and round-trip through save/load via an XRecord blob.

Also includes docs/command_reference.md (a statically generated reference
of every registered command and its prompt sequence) and
docs/named_parameters_design.md + docs/backlog.md, which hand off the next
queued feature (a named-parameter/expression table) and consolidate every
deliberate scope-down and open gap found along the way, so a fresh session
has a complete starting point.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

src/scene/sketch_persist.rs

@@ -0,0 +1,248 @@
+//! Save/load integration for [`super::sketch_constraints::SketchConstraintSet`]
+//! — design doc §5.2/§8 stage 4, the "lazy" persistence model that section
+//! recommends: constraint sets live only in `Scene::sketch_constraints`
+//! in-memory (§8 stage 3) and are materialized into `document.objects` as
+//! XRecords only around a save, and read back out right after a load. The
+//! XRecord round-trip mechanism itself (`CadDocument::ensure_xrecord`/
+//! `xrecord`/`xrecord_mut`) was proven in stage 2
+//! (`tests/sketch_constraints_xrecord_roundtrip.rs`) — this module is just
+//! the app-level wiring: which owner handles to check, and when.
+//!
+//! One named XRecord (keyed [`XRECORD_KEY`]) hangs off each scope's own
+//! owner handle's extension dictionary — model space's `BlockRecord` handle,
+//! or a `SketchScope::Block`'s handle — rather than a single shared
+//! dictionary, since [`super::sketch_constraints::SketchScope::owner_handle`]
+//! already gives that handle directly and `ensure_xrecord`/`xrecord` are
+//! themselves per-owner.
+
+use super::sketch_constraints::SketchConstraintSet;
+use super::Scene;
+
+const XRECORD_KEY: &str = "OCS_SKETCH_CONSTRAINTS";
+
+/// Prefixed onto every serialized blob so a future schema change can be
+/// detected and gracefully skipped (dropping just that one scope's
+/// constraints, not the whole load) rather than silently misreading bytes
+/// or panicking — design doc §5.2's explicit call-out, and §7's flagged
+/// "no migration path designed yet": bumping this is the signal a real
+/// migration is needed, not a substitute for one.
+const FORMAT_VERSION: u8 = 1;
+
+fn encode(set: &SketchConstraintSet) -> Option<Vec<u8>> {
+    let mut bytes = vec![FORMAT_VERSION];
+    bytes.extend(bincode::serialize(set).ok()?);
+    Some(bytes)
+}
+
+fn decode(bytes: &[u8]) -> Option<SketchConstraintSet> {
+    let (&version, body) = bytes.split_first()?;
+    if version != FORMAT_VERSION {
+        return None;
+    }
+    bincode::deserialize(body).ok()
+}
+
+impl Scene {
+    /// Writes every current `sketch_constraints` entry into its scope's
+    /// owner-handle XRecord, ready for whatever save call happens next to
+    /// serialize `self.document` as-is. Called right before a native/web
+    /// save (`OpenCADStudio::prepare_native_save` and the wasm save path)
+    /// — see those call sites' doc comments for why "right before save"
+    /// rather than keeping the XRecord resident and live-updated (design
+    /// doc §5.2's "live" model, deferred: it would also let constraint-set
+    /// edits ride the ordinary object-delta undo path per §5.1(b), but this
+    /// lazy model was the doc's own recommended first step).
+    ///
+    /// A scope with an empty constraint set is skipped rather than writing
+    /// an empty XRecord — an unconstrained drawing (the common case) should
+    /// not gain persisted-but-empty bookkeeping on every save.
+    pub(crate) fn materialize_sketch_constraints_for_save(&mut self) {
+        for index in 0..self.sketch_constraints.len() {
+            let set = &self.sketch_constraints[index];
+            if set.constraints.is_empty() {
+                continue;
+            }
+            let owner = set.scope.owner_handle(&self.document);
+            if owner.is_null() {
+                continue;
+            }
+            let Some(bytes) = encode(set) else { continue };
+            self.document.ensure_xrecord(owner, XRECORD_KEY);
+            if let Some(record) = self.document.xrecord_mut(owner, XRECORD_KEY) {
+                // Overwrite, not append: a resave must replace the prior
+                // blob, not accumulate one more Chunk entry every time.
+                record.entries.clear();
+                record.entries.push(acadrust::objects::XRecordEntry::new(
+                    310,
+                    acadrust::objects::XRecordValue::Chunk(bytes),
+                ));
+            }
+        }
+    }
+
+    /// Populates `sketch_constraints` from every `OCS_SKETCH_CONSTRAINTS`
+    /// XRecord found in the just-loaded `self.document` — called right
+    /// after a document open installs its `CadDocument` into this `Scene`
+    /// (`OpenCADStudio::on_file_opened` and the automation `"open"`/`"new"`
+    /// ops). Every `BlockRecord` (model space, paper space, and named
+    /// block definitions) is a candidate owner; most will have no such
+    /// XRecord and are skipped cheaply. Replaces whatever was already in
+    /// `sketch_constraints` (a fresh/empty `Vec` for a real open; `"new"`'s
+    /// blank document has nothing to find anyway).
+    pub(crate) fn load_sketch_constraints_from_document(&mut self) {
+        self.sketch_constraints.clear();
+        let owners: Vec<acadrust::Handle> =
+            self.document.block_records.iter().map(|record| record.handle).collect();
+        for owner in owners {
+            let Some(record) = self.document.xrecord(owner, XRECORD_KEY) else { continue };
+            let Some(bytes) = record.entries.iter().find_map(|entry| match &entry.value {
+                acadrust::objects::XRecordValue::Chunk(bytes) => Some(bytes.clone()),
+                _ => None,
+            }) else {
+                continue;
+            };
+            if let Some(set) = decode(&bytes) {
+                self.sketch_constraints.push(set);
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::sketch_constraints::{ConstraintKind, SketchRef, SketchScope};
+    use super::*;
+    use acadrust::entities::EntityType;
+    use acadrust::types::Vector3;
+
+    #[test]
+    fn a_model_space_constraint_set_survives_materialize_and_reload() {
+        let mut scene = Scene::new();
+        let a = scene.add_entity(EntityType::Line(acadrust::entities::Line::from_points(
+            Vector3::new(0.0, 0.0, 0.0),
+            Vector3::new(10.0, 0.0, 0.0),
+        )));
+        scene.sketch_constraint_set_mut(SketchScope::ModelSpace).add(
+            ConstraintKind::Horizontal,
+            vec![SketchRef::whole(a)],
+            None,
+        );
+
+        scene.materialize_sketch_constraints_for_save();
+        // Simulate the load-time side of a save/reload round trip: drop the
+        // in-memory sets (a fresh open starts with none) and repopulate
+        // purely from what materialize just wrote into `document.objects`.
+        scene.sketch_constraints.clear();
+        scene.load_sketch_constraints_from_document();
+
+        let set = scene.sketch_constraint_set(SketchScope::ModelSpace).expect("constraint set should have been reloaded");
+        assert_eq!(set.constraints.len(), 1);
+        assert_eq!(set.constraints[0].kind, ConstraintKind::Horizontal);
+        assert_eq!(set.constraints[0].refs, vec![SketchRef::whole(a)]);
+    }
+
+    /// The above test only proves `materialize`/`load` agree with each
+    /// other on the same in-memory `CadDocument` — it never actually
+    /// serializes anything. This drives a real `save_to_bytes`/`load_bytes`
+    /// round trip (the same primitives `OpenCADStudio::on_file_opened`'s
+    /// native save/open path uses), through both supported formats, closing
+    /// the gap stage 2's spike proved for the raw XRecord mechanism up to
+    /// this stage's actual app-level wiring.
+    fn full_bytes_roundtrip(ext: &str) -> SketchConstraintSet {
+        let mut scene = Scene::new();
+        let a = scene.add_entity(EntityType::Line(acadrust::entities::Line::from_points(
+            Vector3::new(0.0, 0.0, 0.0),
+            Vector3::new(10.0, 5.0, 0.0),
+        )));
+        let b = scene.add_entity(EntityType::Line(acadrust::entities::Line::from_points(
+            Vector3::new(10.0, 5.0, 0.0),
+            Vector3::new(20.0, 5.0, 0.0),
+        )));
+        scene.sketch_constraint_set_mut(SketchScope::ModelSpace).add(
+            ConstraintKind::Coincident,
+            vec![SketchRef::point(a, 1), SketchRef::point(b, 0)],
+            None,
+        );
+        scene.sketch_constraint_set_mut(SketchScope::ModelSpace).add(ConstraintKind::Distance, vec![SketchRef::whole(b)], Some(12.5));
+
+        scene.materialize_sketch_constraints_for_save();
+        let bytes = crate::io::save_to_bytes(&scene.document, ext, scene.document.version)
+            .unwrap_or_else(|e| panic!("save to {ext} bytes: {e}"));
+        let mut reloaded_scene = Scene::new();
+        reloaded_scene.document = crate::io::load_bytes(&format!("stage4_roundtrip.{ext}"), bytes)
+            .unwrap_or_else(|e| panic!("reload {ext} bytes: {e}"));
+        reloaded_scene.load_sketch_constraints_from_document();
+
+        reloaded_scene.sketch_constraint_set(SketchScope::ModelSpace).cloned().unwrap_or_else(|| {
+            panic!("no ModelSpace constraint set survived the {ext} save/load round trip")
+        })
+    }
+
+    #[test]
+    fn a_constraint_set_survives_a_real_dxf_save_and_load_round_trip() {
+        let restored = full_bytes_roundtrip("dxf");
+        assert_eq!(restored.constraints.len(), 2);
+        assert_eq!(restored.constraints[0].kind, ConstraintKind::Coincident);
+        assert_eq!(restored.constraints[1].kind, ConstraintKind::Distance);
+        assert_eq!(restored.constraints[1].driving_param, Some(12.5));
+    }
+
+    #[test]
+    fn a_constraint_set_survives_a_real_dwg_save_and_load_round_trip() {
+        let restored = full_bytes_roundtrip("dwg");
+        assert_eq!(restored.constraints.len(), 2);
+        assert_eq!(restored.constraints[0].kind, ConstraintKind::Coincident);
+        assert_eq!(restored.constraints[1].kind, ConstraintKind::Distance);
+        assert_eq!(restored.constraints[1].driving_param, Some(12.5));
+    }
+
+    #[test]
+    fn a_block_scoped_constraint_set_survives_materialize_and_reload() {
+        let mut scene = Scene::new();
+        let a = scene.add_entity(EntityType::Line(acadrust::entities::Line::from_points(
+            Vector3::new(0.0, 0.0, 0.0),
+            Vector3::new(1.0, 0.0, 0.0),
+        )));
+        // `create_block_from_entities` returns the placed INSERT's handle,
+        // not the BlockRecord's own handle — `SketchScope::Block` needs the
+        // latter (it's what `BlockEditSession::br_handle` and
+        // `SketchScope::owner_handle` both mean by "a block definition's
+        // handle"), so look it up from the table by name instead of using
+        // the return value directly.
+        let _insert_handle = scene
+            .create_block_from_entities(&[a], "OCS_STAGE4_TEST_BLOCK", &acadrust::types::Transform::identity(), &acadrust::types::Transform::identity())
+            .expect("create a block definition to own the constraint set");
+        let br_handle = scene.document.block_records.get("OCS_STAGE4_TEST_BLOCK").expect("block record should exist").handle;
+        scene.sketch_constraint_set_mut(SketchScope::Block(br_handle)).add(ConstraintKind::Vertical, vec![SketchRef::whole(a)], None);
+
+        scene.materialize_sketch_constraints_for_save();
+        scene.sketch_constraints.clear();
+        scene.load_sketch_constraints_from_document();
+
+        let set = scene
+            .sketch_constraint_set(SketchScope::Block(br_handle))
+            .expect("block-scoped constraint set should have been reloaded");
+        assert_eq!(set.constraints.len(), 1);
+        assert_eq!(set.constraints[0].kind, ConstraintKind::Vertical);
+    }
+
+    #[test]
+    fn an_empty_constraint_set_is_not_materialized() {
+        // A scope touched (e.g. `sketch_constraint_set_mut` called once,
+        // then every constraint removed) but left with zero constraints
+        // should not persist an empty XRecord.
+        let mut scene = Scene::new();
+        let _ = scene.sketch_constraint_set_mut(SketchScope::ModelSpace);
+        scene.materialize_sketch_constraints_for_save();
+
+        let owner = scene.document.header.model_space_block_handle;
+        assert!(scene.document.xrecord(owner, XRECORD_KEY).is_none(), "an empty constraint set should not create an XRecord");
+    }
+
+    #[test]
+    fn decode_rejects_a_mismatched_format_version() {
+        let mut bytes = vec![FORMAT_VERSION.wrapping_add(1)];
+        bytes.extend(bincode::serialize(&SketchConstraintSet::new(SketchScope::ModelSpace)).unwrap());
+        assert!(decode(&bytes).is_none(), "a future/unknown format version must be rejected, not misread");
+    }
+}