Turning intent into transactions

The reason this is one tool call and not a free-text rewrite is trust. A lawyer must be able to see, and reject, exactly what the agent changed. So the DSL is built so that every edit is anchored to real text, lands as a reviewable suggestion, and fails loudly when the document has moved under it.

The DSL is a discriminated union on type. Click through each command to see the JSON Lawrence emits, the ProseMirror operation the planner produces, and whether it lands as a tracked suggestion or a direct edit. The first six are tracked changes; the last two (set_block, list_op) apply directly.

The whole grammar is a Zod discriminated union in matter-document-edit-schemas.ts. Every command mixes in a shared targeting core and a required explanation (the human-readable reason, shown to the lawyer and used for audit). Here is the union:

The shared targeting core

Mixed into edit, insert, delete, format, set_block and list_op (the id-addressed refine / withdraw skip it):

The request envelope (MatterDocumentEditPayloadSchema) wraps the commands: content_version_id (nullish; the optimistic-concurrency token from the read), optional section_node_id (scope the edit to a sub-section), commands (1 to 50, MAX_EDIT_COMMANDS), and personId (the acting lawyer, force-injected server-side, see the pipeline section). The constrained sub-enums keep the agent inside the OOXML schema:

• InlineMarkKind: bold, italic, underline, strike, subscript, superscript, code, textStyle, highlight, link.
• BlockKind: paragraph, heading, blockquote, codeBlock.
• BlockAttrs (.strict()): level (1-6), textAlign (left/center/right/justify, no start/end, this is DOCX), indentLeft/Right/FirstLine, lineSpacing, spaceBefore/After, styleId.
• ListOpKind: convert, wrap_bullet, wrap_ordered, unwrap. numId is deliberately never exposed.
• FormatAttrs (.strict()): fontFamily, fontSize, color, textDecorationLine, highlightColor, href, target. href is refined to ^(https?://|mailto:).

Here is the thing that surprises people reading Lawrence's system prompt: the command grammar isn't in it. The prompt carries only the policy: edits land as tracked suggestions, the status codes are routing instructions to recover from rather than errors to escalate, read immediately before editing, batch up to 50 commands, use refine / withdraw on your own marks instead of stacking a competing edit. Then it points at the tool itself: "the runtime tool description carries the full payload schema, consult it before constructing a call." The DSL is self-describing.

The authoritative grammar is injected into the edit tool's own description at call time. edit.py's _build_tool_description pulls the per-surface documentation from MatterDocumentContentSurface.get_documentation(), the command payloads plus a STATUS HANDLING block, generated from the same definitions this page documents. So the model reads an up-to-date spec from the tool schema on every call, and it cannot drift from the code the way a hand-maintained prompt would. In practice Lawrence learns to edit from four layers, narrowing from general policy to the specific live signal:

Lawrence cannot send ProseMirror positions: it has never seen the document as a position tree, only as Markdown or a block map. So targeting is a translation problem. A command says "block doc[2]:paragraph, the 1st occurrence of £12,500", and the resolver turns that into a concrete {from, to} ProseMirror range. Three helpers do it, and all three must agree byte-for-byte with content-service:

• computeBlockId reproduces the same block id the getContentMap read handed out: the node's own attrs.id, or a positional fallback doc[<index>]:<type>.
• computeTextHash is sha256 of the block's whitespace-normalised text. If the command carries expected_block_hash and it no longer matches, the block changed under the agent and the command returns block_hash_mismatch rather than editing the wrong thing.
• resolveFindWithinBlock builds a per-character map from the block's normalised text back to source ProseMirror positions, finds the requested occurrence of find (optionally disambiguated by context_before/after), and maps the match back to gap-based PM positions.

The default is a tracked change. When Lawrence edits prose, the planner does not mutate the text in place: it wraps the change in a diffSuggestion mark, a ProseMirror mark carrying {id, originalText, suggestedText, author: "Lawrence", source, date, formatChange, comment}. In the editor the lawyer sees each as a green insertion or a red strikethrough attributed to "Lawrence" with a timestamp, and an accept/reject card in the margin; a batch of up to 50 commands lands as one revision, one card per command. A deletion is a diffSuggestion with an empty suggestedText; a format change carries a formatChange instead of text. Six of the eight commands work this way.

Two commands cannot, today. set_block and list_op change block structure (a paragraph becomes a heading, a paragraph becomes a list item), and the diffSuggestion mark only models inline deltas. There is no inline mark that means "this used to be a paragraph". So they apply directly, with diff_suggestion_id: null, and cannot be rejected the way an inline suggestion can. The tracked equivalent (an OOXML w:pPrChange) is tracked as future work in LEX-380.

A whole batch of commands becomes one ProseMirror transaction and one Yjs update. The resolver fetches current state, gates on the version, plans every command, applies them to a single transaction (remapping positions as earlier edits shift later ones), writes the mutated doc back into the Yjs fragment, and ships the encoded delta. Step through it:

Every command returns its own result, so a batch can be partly applied. The status vocabulary is precise on purpose: each value tells the agent exactly how to recover. The whole point of failing with ambiguous or block_hash_mismatch rather than guessing is that a wrong edit to a legal document is worse than no edit.

Recovery is the model's job, not the framework's. There is no automatic retry on the agents side: the per-command results are surfaced to Lawrence verbatim, and the tool description tells it what to do (on stale, re-read and re-issue with a fresh content_version_id; on overlap_conflict, refine or withdraw the existing mark instead). The only programmatic retry anywhere is the single epoch-race retry inside the lawrence-api resolver. This keeps the agent in the loop and auditable rather than silently hammering a document.

Creating a document is simpler than editing one, because there's no concurrency to defend. create takes one of two strict shapes, and the generic /write verb is deliberately blocked for documents so that all changes flow through the reviewable edit path.

personId (and actorIdentityId for task/keydate creates) is auto-injected from the agent's context on the Python side, so the LLM never chooses who it is acting as. Both create shapes return { path, id }.

The honest edges of the system, so the map matches the territory: