# The change report and the engagement sheet ## The change report Every `create_draft` and `update_draft` answers with a change report: one build, no pictures. It starts with a summary line ("Needs a fix: …" or "Passes the quick check"), then the report as JSON. It is at most 16 KiB; a longer one is shortened and says what it left out. - `draft_id`: the draft. - `revision`: this revision's number; every update_draft saves the next one. - `content_hash`: the hash of the design as saved. - `scope`: `quick` (one wall, the defaults) after create_draft and update_draft. - `status`: `passed` or `failed`: failed while any error is left. - `errors`: how many errors. - `warnings`: how many warnings. They don't fail the check; read them anyway. - `truncated`: null when the report is whole; otherwise what was left out to keep it short. - `issues`: every problem: new errors first, then old errors, new warnings, old warnings. Each has `rule`, `code`, `level`, `path` (where in the design), `message`, `settings` (the settings involved), `fix` (`say`, and a `patch` when the fix is certain) and `change` (`new` or `still-present`). - `issues_omitted`: issues left out of the list to keep it short. - `fixed`: the issues the last revision had and this one doesn't. - `fixed_omitted`: fixed issues left out. - `fit`: one row per wall: `verdict` (`fits`, `wont-fit` or `unknown`), the `reason`, `bite_mm` (how deep the mount reaches behind the lip), `pocket_clear_mm`, `key_interference_mm` (how much the locked key grips) and `basis` (where the wall's numbers behind the verdict came from; see the engagement sheet below). null when fit per wall wasn't checked. - `anatomy`: per part: its `material` slot, the `bricks` and `shapes` it is made of, how it prints (`orient` or `in_place_with`) and its size. - `measure`: per part its size, volume, `grams` printed solid (`pla` and `petg`), triangles and overhang, `bed_ok` (every print job fits the bed) and each brick's readouts, plus `print_time_s` (every print job's time added up, from the reference slice in PrusaSlicer) once this exact content has been sliced cleanly on a studio with a slicer; null when the draft didn't build. Slicing never holds up a check: a passing full check starts the slice and answers at once, and the print time and grams arrive after it, on the next report. The thinnest wall is slow to find, so only `inspect_draft`'s measure has it, as an upper bound: "at most N mm". - `parts_omitted`: parts left out of anatomy and measure to keep it short. - `load`: the calculated load, information and never a failure: `walls` (per wall, `defaults_kg` and `weakest_kg` with `weakest_at`), `weakest_kg` overall and what is `limiting` it, `assumptions` (the print it was calculated for; `reference` when it is the reference print), `rough` (your own shapes carry it), `listed_as` (the catalog's calculated class) and a `note`. The change report's covers the defaults on its wall; null when nothing was built. - `diff`: what changed since the last revision: `changed` (JSON Pointers; arrays compare index by index, so read a list of shifted indexes as "this array changed") and the measured changes with units. null on revision 1. - `similar_warning`: a published design this draft is close to, if any: make a preset or a remix of it instead. - `test_fit`: which test piece to print first on a new wall or printer. - `next`: what to do now: `inspect` (true when a picture is worth taking), `why` and `action`. What to do with it: - An error: apply its fix. When it has a `patch`, send that patch with `update_draft`. - A warning: read it. Most say something real about one wall or one corner. - `fixed`: confirms your last change worked. - `fit` says won't fit on a wall: that wall isn't claimed. Change nothing, unless it is the draft's own wall: then the quick check fails there, and you need a mount that takes it (see [rules-and-fixes.md](rules-and-fixes.md)). - `load` is information, never a failure: the calculated capacity per wall, the weakest figure, what limits it and the print it assumes. When holding matters, strengthen what `limiting` names and compare (see [catalog.md](catalog.md)). - `similar_warning`: make a preset of that design, or remix it, instead of publishing a near copy. - `next` has `inspect` true: call `inspect_draft` to see the change. ### An example Revision 2 of the `multi-slot-lock` example, after its peg was made 80 mm long (revision 1 had 40 mm). Both revisions come from the real quick check on VEVOR PVC slatwall: the longer peg calculates under light's 2 kg, which the report says as a warning, and the measure shows what grew. ```text Passes the quick check, with 1 warning: Calculated capacity: 1.05 kg at its weakest (printed in PLA with 2 walls and 15 % infill; an estimate, not tested): the design's own shapes, with the item at their worst point, limited by the design's own material where it is cut 6 mm out from the wall (a 64 mm² section), at its defaults on the "vevor" wall. That is under the 2 kg at the top of "Light · under 2 kg". Its listed versions (the defaults and presets) read 1.05 kg, so the listing calculates "light". { "draft_id": "example-draft", "revision": 2, "content_hash": "a354b6f1e7898db22ca5bfd77abbf3c7a7c84612bb8b26b8d1f84f7b68b594e7", "scope": "quick", "status": "passed", "errors": 0, "warnings": 1, "truncated": null, "issues": [ { "rule": "R9", "code": "load-under-light", "level": "warn", "path": "load", "message": "Calculated capacity: 1.05 kg at its weakest (printed in PLA with 2 walls and 15 % infill; an estimate, not tested): the design's own shapes, with the item at their worst point, limited by the design's own material where it is cut 6 mm out from the wall (a 64 mm² section), at its defaults on the \"vevor\" wall. That is under the 2 kg at the top of \"Light · under 2 kg\". Its listed versions (the defaults and presets) read 1.05 kg, so the listing calculates \"light\".", "settings": [], "wall": "vevor", "fix": { "say": "If strength matters for what it holds: make the part that carries the load thicker, wider or shorter. The item is taken at the worst point of the design's own shapes, so a load_point can't raise this number; a stronger shape can." }, "change": "new" } ], "issues_omitted": 0, "fixed": [], "fixed_omitted": 0, "fit": [ { "wall": "vevor", "verdict": "fits", "bite_mm": 4.4, "pocket_clear_mm": 1.26, "key_interference_mm": 0.22, "basis": "assumed", "says": "Fits your VEVOR PVC slatwall · some wall sizes assumed" } ], "anatomy": [ { "part": "board", "material": "body", "material_label": "Body", "bricks": [ "multi-slot-lock@1" ], "shapes": [ "board", "peg" ], "orient": "on-side", "in_place_with": null, "size_mm": [ 97.1, 170.1, 85.4 ] }, { "part": "key_1", "material": "mechanism", "material_label": "Locks", "bricks": [ "multi-slot-lock@1" ], "shapes": [], "orient": null, "in_place_with": "board", "size_mm": [ 22.3, 9.8, 22.9 ] }, { "part": "key_2", "material": "mechanism", "material_label": "Locks", "bricks": [ "multi-slot-lock@1" ], "shapes": [], "orient": null, "in_place_with": "board", "size_mm": [ 22.3, 9.8, 22.9 ] } ], "measure": { "wall": "vevor", "parts": [ { "name": "board", "material": "body", "size_mm": [ 97.1, 170.1, 85.4 ], "volume_mm3": 98028, "grams": { "pla": 121.6, "petg": 124.5 }, "triangles": 2134, "overhang": { "area_mm2": 731, "share": 0.021 } }, { "name": "key_1", "material": "mechanism", "size_mm": [ 22.3, 9.8, 22.9 ], "volume_mm3": 1972, "grams": { "pla": 2.5, "petg": 2.5 }, "triangles": 2712, "overhang": { "area_mm2": 151, "share": 0.125 } }, { "name": "key_2", "material": "mechanism", "size_mm": [ 22.3, 9.8, 22.9 ], "volume_mm3": 1972, "grams": { "pla": 2.5, "petg": 2.5 }, "triangles": 2712, "overhang": { "area_mm2": 151, "share": 0.125 } } ], "bed_ok": true, "readouts": { "lock": { "slots": 2, "width": 25.4 } } }, "parts_omitted": 0, "load": { "label": "calculated, not tested", "assumptions": { "material": "PLA", "walls": 2, "infill_pct": 15, "layer_height_mm": 0.2, "reference": true }, "walls": [ { "wall": "vevor", "defaults_kg": 1.05, "weakest_kg": 1.05, "weakest_at": "defaults" } ], "weakest_kg": 1.05, "limiting": "the design's own shapes, with the item at their worst point, limited by the design's own material where it is cut 6 mm out from the wall (a 64 mm² section)", "rough": true, "listed_as": { "class": "light", "kg": 1.05 }, "note": "Calculated for the print assumptions shown, not tested: feedback for improving the design, not a guarantee. A low figure is never a reason a design is refused." }, "diff": { "from_revision": 1, "to_revision": 2, "changed": [ "/settings/peg/default" ], "changed_omitted": 0, "measure": { "board.grams.petg": "+3.3 g", "board.grams.pla": "+3.2 g", "board.overhang.area_mm2": "+320 mm²", "board.overhang.share": "+0.9 pp", "board.size_mm[0]": "+40.0 mm", "board.volume_mm3": "+2560 mm³" } }, "similar_warning": null, "test_fit": "Print the calibration kit's slot gauge and lock test on your wall first (about 15 min).", "next": { "inspect": true, "why": "The board's size changed by 40.0 mm.", "action": "Act on the warnings above (each says how to fix it), then run validate_draft with scope full. To see the new shape now, call inspect_draft." } } ``` ## The engagement sheet `inspect_draft` with "engagement" draws how the part sits in each wall's slot, cut through the key's axis, one picture for every wall, and returns its numbers as one row per wall: - `wall`: the wall's id. - `name`: the wall's name. - `verdict`: `fits`, `wont-fit` or `unknown`. - `reason`: why it won't fit, in the rule's words, when it doesn't. - `basis`: where the wall's numbers behind the verdict came from. Only measured or published numbers can make a fit finding an error (won't fit). A finding that rests on inferred, patent, assumed or user numbers, or on a number the wall doesn't give, is a warning: it names the field and asks for a slot-gauge print. A brick's own slot or lip range refuses a wall whatever the basis. - `slot_mm`: the wall's slot opening. - `part_mm`: the part's height across the slot: the key turned to unlocked when there is one. - `bite_mm`: how deep the mount reaches behind the lip. - `pocket_clear_mm`: the room left in the pocket behind the lip. - `key_interference_mm`: how much the locked key grips the slot's edges. - `key`: the key's moments, for display: `unlocked_mm`, `peak_mm` (the click) and `peak_deg` (where the click is). - `why`: a won't-fit or unknown verdict in a few words; null when it fits. - `says`: the one fit statement on this wall, word for word as the site says it to people (the verdict, what it rests on, whether it may be hard to hook on): tell the person this. - `notes`: the errors and warnings behind the verdict, a designed squeeze named as intended, and what the row assumes. Read the spans on the sheet as the extent of the slab the cut takes through the part, not as a radius on the cut plane. The verdicts come from the fit check; the picture shows where. `inspect_draft` can also return "views", "engagement", "states", "measure", "load", "similar" and "reports". Ask only for what you need; every part at once is large.