Add a canonical source-backed generation workflow (edit script, execute, verify, checkpoint)

[pzfreo]

Summary

Generation agents need a first-class workflow in which a complete parametric source file remains canonical while build123d-mcp supplies execution, validation, measurement, rendering, snapshots, repair diagnostics, and gated export.

Today the common MCP path encourages incremental execute() snippets against live session objects. That is efficient and safe for local changes, but global form corrections become awkward: replacing a body profile, bend construction, shell strategy, or blade loft means reconstructing substantial session state. Agents therefore tend to preserve an early valid approximation after a risky refinement fails.

A source-backed loop would combine direct Python's easy global rewrites with MCP's much stronger verification and validity guarantees.

Evidence

A same-model/same-effort CADGenBench comparison used Claude Opus 5 xhigh with build123d-mcp 0.3.81 versus the official baseline prompt with direct build123d/Python:

Metric	no MCP	MCP
Overall score	0.627	0.639
Generation	0.631	0.596
Editing	0.621	0.706
Validity	75/81	80/81

For 43 generation fixtures with retained paired usage, no MCP also consumed 23.2% more API-equivalent cost, 38.4% more output tokens, 40.0% more runtime, and 27.4% more turns. MCP is materially more efficient, but direct source editing occasionally enabled much better complex-form reconstruction.

The generation gap is dominated by six fixtures: 102, 106, 116, 126, 145, and 150. Together they contribute more than the entire aggregate no-MCP generation advantage. Trace examples:

• 106: no MCP rewrote failed sheet-metal fillets as true quarter-annulus bend solids; MCP retained a simpler valid formed approximation (0.819 vs 0.533).
• 116: no MCP globally refined the main outline/R35 transition after an overlay; MCP's large fillet attempts failed and it retained the checkpoint (0.555 vs 0.172).
• 145: no MCP revised the whole blade profile into an S-curve while retaining its prior script and STEP; MCP kept a simpler valid blade representation (0.567 vs 0.267).
• 150: no MCP repeatedly rebuilt a large chassis profile and feature field from a canonical script (0.777 vs 0.203).

Reports:

• no MCP: https://huggingai4engineering-cadgenbench.hf.space/reports/pzfreo_opus5-xhigh-official-baseline-prompt-nom_20260811-034944.html
• MCP: https://huggingai4engineering-cadgenbench.hf.space/reports/pzfreo_build123d-mcp-v0381-claude-opus-5-xhigh-_20260807-101147.html

Proposal

Add an explicit source-backed execution path, for example execute_file(path, entry_object=..., checkpoint=...), or equivalent parameters on execute().

The workflow should:

1. Treat one Python file as the reproducible source of truth.
2. Execute it in a fresh or explicitly selected namespace so stale live objects cannot silently affect the result.
3. Register a named resulting shape in the MCP session.
4. Return stdout/stderr, timing, bbox/topology/volume summary, and the exact source hash.
5. Optionally validate and promote the result to a snapshot only on success.
6. Preserve the prior valid candidate when execution or validation fails.
7. Allow render_view, measure, recognizers, comparison, repair diagnostics, and export to operate on the registered result normally.
8. Record source hash/path in snapshots and export metadata so the final STEP can be traced to its generating source.

A companion skill/workflow should recommend:

• create model.py for the first complete candidate;
• make substantial revisions by editing the canonical file rather than layering many stateful snippets;
• execute into a candidate name;
• validate/render/measure through MCP;
• promote only better, valid candidates;
• keep incremental execute() for exploration and small local fixes.

Why this belongs in MCP

Agents can approximate this with shell execution or exec(open(...).read()), but those routes lose one or more of: sandbox policy, clean namespace semantics, structured failure output, result registration, snapshot provenance, source hashing, and atomic preservation of the prior valid candidate. A first-class tool makes the safe path the easy path.

This complements rather than duplicates:

• Raise CADGenBench Shape+Interface fidelity: fix export/render friction + close the model↔drawing loop #304 drawing/model comparison: supplies the fidelity signal used after each source rebuild.
• feat: sheet-metal bend/fold primitive (panels + bend lines → constant-thickness folded solid) #318 sheet-metal primitive: supplies a better construction primitive.
• Add a fidelity evidence loop: hypothesis checks, best-candidate scoring, and edit-locality gates #439 fidelity evidence loop: ranks/promotes candidates.
• Consolidate repair/edit guidance surfaces around a canonical source #413 guidance consolidation: can route the workflow from a canonical skill.

Acceptance criteria

• An agent can execute model.py, register its resulting solid, and use all existing MCP inspection/export tools on it.
• A syntax error, exception, timeout, invalid result, or missing result object leaves the previous valid candidate and snapshot intact.
• Re-running an edited source file does not inherit undeclared geometry objects from the prior execution.
• Tool output includes the executed source hash and registered object name.
• Snapshot/export provenance identifies the source hash that produced the geometry.
• Tests cover successful rebuild, failed rebuild with rollback, clean namespace behavior, and deterministic re-execution.
• A focused replay on fixtures 106, 116, or 145 demonstrates at least one successful global form correction without sacrificing the prior valid candidate.