Review drawing proposals¶
An agent or a local program can prepare a molecular scene without editing the open document. Commands… → Review drawing proposal… accepts either a proposal JSON object or a review receipt returned by the API. Choose Prepare review, inspect the before/after drawings and verified changes, then Apply proposal or Discard and close. Agent notes are displayed as untrusted plain text, separately from chemistry validation.
A proposal contains canvas (candidate KET), scope and optional notes.
It cannot supply document provenance, jobs, results or trusted species records.
The service derives species and reactions using the existing chemistry services.
{"canvas": {"root": {"nodes": []}}, "scope": {"whole_drawing": true}, "notes": "Propose an empty scene"}
Use whole-drawing scope only when the entire scene is intended to change.
Otherwise scope.nodes lists changed top-level KET keys, scope.root_slots
lists changed zero-based root-node slots, and scope.species and
scope.reactions identify existing records permitted to change. Slots and IDs
belong to the exact reviewed snapshot. Out-of-scope changes, missing targets,
ambiguous references and unsupported molecular fragments are refused. New
species are derived; existing species and reaction changes are shown in the
review. Proposals that discard jobs or stored publication highlights are
refused even with whole-drawing scope. Resolve those records explicitly first.
Transactions and history¶
A server-owned receipt binds the session document, source revision/full-document digest and validated candidate. Applying uses that stored candidate. Editing a proposal requires another review. Source changes require another review too. Apply, Undo and Redo are atomic and advance the revision once. Identical retries with the same key and request return the original application receipt; different content under that key is refused. A replay reports its original revision, not an obsolete document to display. Fetch the current document separately.
Undo restores complete document content, including species labels and IDs, reaction metadata and placement. Audit history remains and records the reversal. The browser records one native step for a proposal, and retains complete source snapshots for subsequent native drawing edits so Undo/Redo can traverse them. Those native edits use the same bounded preparation and receipt service. Changes adopted through another panel or from another session invalidate this reviewed history; a reload starts a fresh history. Expired receipts refuse reversal rather than reconstructing incomplete metadata from the canvas.
Receipts are session-local, expire after 30 minutes, and end on document close or server restart. There are at most 64 receipts and 128 MiB of retained serialized review/snapshot data per server process. Capacity exhaustion refuses another review; live history is not silently evicted. An unused review can be discarded. Applied receipts remain until expiry and support up to 128 transactions each. There is no persistence or exactly-once guarantee across server restarts.
Bounds and cancellation¶
Each source/candidate is limited to 4 MiB and 1,000 drawn atoms. A proposal may change at most 100 scene objects; notes are limited to 4,000 characters. Existing finite-number and JSON-depth checks apply. Preparation runs in isolated workers, at most two concurrently, with a maximum 30-second deadline and 16 MiB result bound. Refusals never commit partial edits.
SDK cancellation kills and reaps its worker. Closing or changing a browser review invalidates pending results. A disconnected HTTP preparation may finish within its deadline; unused receipts still have bounded capacity and lifetime. During an explicit Apply, the dialog waits for the transaction result. No external provider, image recognition, network upload or model execution is included.
SDK and other interfaces¶
from vibesketcher.document.drafts import digest, prepare
from vibesketcher.document.draft_session import DraftSession
# document is an existing Document; proposal is the JSON object described above.
preview = prepare(document, proposal) # read-only; optional cancelled() and timeout
session = DraftSession()
entry = session.store.add(document)
review = session.review(
entry.id, proposal, revision=document.revision, source_digest=digest(document)
)
result = session.transact(
entry.id,
review["receipt"],
"apply",
key="review-1",
revision=document.revision,
source_digest=digest(document),
)
current = session.store.get(entry.id).document
session.transact(
entry.id,
review["receipt"],
"undo",
key="undo-1",
revision=current.revision,
source_digest=digest(current),
)
DraftRefused reports validation/resource failures; DraftConflict reports
stale, expired or mismatched transactions. inspect returns a copy of the review;
discard removes an unused review. A DraftSession can share a server Store.
CLI: vibe-sketcher draft preview SOURCE.vsk proposal.json performs offline
inspection only. draft request review --server URL --document ID --proposal proposal.json creates a live receipt. The inspect/discard actions require
--receipt. apply/undo/redo additionally require explicit --key,
--revision and --source-digest. Keep those values identical on a retry.
REST routes under /api/documents/{id}/drafts:
GET /source: current revision and full-document digest.POSTwith{revision, source_digest, proposal}: prepare a review receipt.GET /{receipt}: inspect;DELETE /{receipt}: discard an unused review.POST /{receipt}/transactionswith{revision, source_digest, key, action}: explicitapply,undoorredo; optionalclientrecords the interface andactor(agentby default, orhuman) records the caller. Native browser edits and browser history reversals identify the human caller.
Invalid proposals/bounds give 422, missing documents 404, and stale/expired or
mismatched receipts 409. MCP drawing_draft exposes the same source, review,
inspect, discard, apply, undo and redo actions. Existing direct tools
remain available. The separate draft envelope is vibesketcher.draft/1; no
persistent document schema fields or new dependencies are added.