Editing

Read the baseline

Revisioned document sessions

Read the session contract for fields and bounds, and use vextor vxl session schema for closed executable schemas. The public lifecycle recipe provides all ten local CLI commands and the hosted REST routes.

Local CLI actions: open, replace, set-overrides, undo, redo, status, cancel, entities, preview, publish.

Hosted REST actions: open, replace, set_overrides, undo, redo, status, cancel, entities, preview, publish.

The CLI uses set-overrides, the wire uses set_overrides.

Replace and overrides

Keep authoring complete VXL documents using the gated loop. Open with standard padded base64 of the checked authored document, schema_version:1, the complete overrides and optional immutable timeout/TTL. Retain session_ref and read status for canonical document, overrides, revision, build refs and report/packet descriptors. Preserve questions and assumptions in edits. Each edit uses current base_revision and a fresh printable idempotency key; an equal retry reuses its key and body. Replace sends a whole document and whole overrides map; set-overrides replaces the whole map and {} clears it. Never send operation batches or display numbers as selectors; repair authored geometric predicates and expected counts.

# both roots must already exist.
vextor vxl session open open.json --session-root PRIVATE --generation-root PUBLIC --cell-manifest CELL --idempotency-key KEY
# status.json contains {}.
vextor vxl session status SESSION status.json --session-root PRIVATE
# replacement includes schema_version, base_revision, document, overrides.
vextor vxl session replace SESSION replace.json --session-root PRIVATE --idempotency-key EDIT_KEY

Undo and redo

HOLD and RELEASE accept source; FAILED/check refusal/cancellation preserve the previous source and overrides. Read the revision packet and follow the same repair/stop rules; count session rebuild attempts, including an undo that must rebuild, toward the existing four-build cap. Undo restores the preceding accepted source at a higher revision; local redo restores the next undone source at a further revision (empty_redo if none remains). Entities queries measure retained STEP with explicit evidence; preview reads fixed captured PNGs unless a schema-2 diagnostic is requested.

Variants

Use variants[] for named finite override sets and when only for structure selected by finite-domain parameters. See the language card. Set-overrides replaces the whole map; {} clears it.

Compact replies

Use --compact (wire compact:true) on replace, set-overrides, undo, redo or publish. The reply projects the retained report: outcome, label, changed steps, all nonpassing requirements, first diagnostic, nullable measures delta and full report reference. Equal semantic key/body retries may request full or compact without rebuilding. Compact does not truncate failures, perform measurements or upgrade HOLD to RELEASE.

Entities and pages

Use --filter with AND predicates (kind, carrier, normal_near, within_aabb_mm), --limit (1–1024) and the returned --cursor for continuation. within_aabb_mm tests face centroids, not whole-entity containment. Exact edge centroids are unavailable; there is no step-provenance filter. Display numbers are observations, never authored selectors. Keep revision, build, terminal, topology and filter fixed across pages; inspect complete and next_cursor. Delivered mesh triangle pages are diagnostic-only. Use vextor commands --with-entries to find real CLI/REST adapters; entries do not grant backend admission. See the session contract.

Diagnostic preview

Diagnostic preview: session preview uses schema 2. Add --azimuth, --elevation, --section OX,OY,OZ:NX,NY,NZ[:negative], repeatable --ghost/--solid, or entity highlight flags (--highlight-terminal, --highlight-faces, --highlight-edges, --topology-digest) to render delivered meshes at --size up to 2048. --target and --span set the orthographic framing. vextor vxl render GENERATION_DIR --terminal T --section 0,0,5:0,0,1 --output section.png renders a finished generation. These images are diagnostic-only, never verification evidence; sections have no exact caps.

Recovery and publish

Publish only the current build/ref at its current revision when the user's request calls for delivery. Publishing HOLD is allowed, retains its label and keeps it out of the release index. Publish does not close the session or increment revision. No idle native worker is retained; source and authenticated outcomes survive restart. Status distinguishes idle, building, publishing, recovering and expired. After a hosted precommit interruption, last_request.state is interrupted and current is unchanged; retrying its key replays that outcome, while a fresh key may rebuild. A durable committed source or commit journal is reconciled without modeling again. Unknown publication requires install reconciliation. Keep HOLD files labelled in private previews and published deliveries. Hosted calls require vxl_session; cancellation also requires request_cancel, and private file reads require artifact_read. Do not claim RELEASE from missing measurements.

Deliver a native document

After a successful accepted build, run vextor vxl export-native RUN/generations/NAME --output model.vextor using the native OCCT package for exact intake. It cold-authenticates the generation, retains canonical VXL, overrides and original assets with generation provenance, imports exact terminals as exact STEP parts and mesh terminals as native meshes, then saves/reopens the existing native format. Cold export with part export --format step|stl|3mf for exact parts or mesh export for a single mesh. Multiple exact parts require the returned --part-id; multiple meshes use mesh export --mesh-id UUID. Native mesh-chain editing currently requires a single mesh root.

For session history, publish every accepted revision and pass all generation directories in oldest-to-newest order (up to 33) before --output history.vextor. Each generation becomes one native revision; failed builds are omitted. A final generation alone cannot recover earlier session revisions. Native bodies remain editable imported snapshots; keep the VXL recipe for parametric feature edits. This does not recover a native VXL feature tree, assembly constraints, or retained multires detail layers. See the VXL reference.

Examples

• when_variants
• provisional_open_question