Observed editor v2¶

Set PATCHDIFF_MCP_PROFILE=observed_v2 to delegate structural editing through five tools. The editor lists or selects scopes and commits edits against an explicit snapshot. A trusted host initializes targets, handles SAVE and replay, and exports content through a separate full connection.

The five tools route to the existing observation and submission services. They use the same transaction formats, runtime, database schema and replay path as other connections. See the profile catalog for the other tool sets.

All five tools carry _meta: {"antigravity/alwaysLoad": true} on modern connections. This is a host hint; selective loading by a particular IDE has not been established. Budget for all five declarations unless actual host evidence shows otherwise.

Explicit snapshots and route boundaries¶

Selection returns snapshot with exactly target_file_id, expected_target_version, expected_current_hash, and observation_bundle_id. patchdiff_commit_bundle accepts that same object without renaming fields and requires intent, client_request_id and groups; each group pairs a returned observation ID with its ordered operations. A one-scope edit uses one selection and one group, with the same mandatory request key. The schemas retain both match and span forms, disambiguators, insertion guards, source, retry lineage and correlation options.

Pass the selected snapshot object directly to the commit tool. The editor still chooses the structures, writes the exact operations and binds each group to its scope ID. Read or search when needed to resolve uncertainty.

Normalization only selects the named route and unwraps supplied fields. It does not refill guards, reinterpret coordinates, normalize UUID spelling, derive operations, or infer authority. Unknown envelope fields and unrouteable snapshots fail explicitly. Known-target malformed operational values still reach the shared service's audited admission path. Tools/list schemas guide construction; they are not a prevalidation layer that bypasses service audit or keyed recovery.

The existing target lock, both explicit guards, current-cycle observation checks, scope boundaries, ordered simulation, all-or-nothing commit, append-only audit, request fingerprints and deterministic replay remain authoritative. Exact keyed recovery precedes fresh guard and consumed-observation checks. The same normalized request sent through the underlying observed tool can recover across facades; changing its raw values changes its identity under the existing fingerprint rules.

Commit receipts¶

New-profile commit results distinguish:

• transaction.before / transaction.after: original transaction versions/hashes, taken from the service result, including on recovery.
• current: target version/hash at this invocation. A recovered transaction's after version can be lower than current.
• transaction.pdcp_log_id, request key, deduplication flag and operation/group counts: existing durable result metadata.
• scopes, warnings: items plus total and truncated flags. Scope summaries confirm each participating group ID and its accepted operation count without reparsing. Per-change span/hash facts remain in the append-only log and manifest ledger for trusted verification, keeping the editor receipt compact (~800 bytes) and well under the presentation cap.
• validity and diagnostics: validation evidence, not task correctness. Task and semantic correctness remain not_evaluated.

The entire logical commit/error JSON is capped at 8,192 UTF-8 bytes when serialized compactly, including metadata, diagnostics and all collections. presentation.truncated and omitted_fields disclose omissions; collection totals remain available. Oversized invalid identity echoes become null with byte/hash omission metadata, never a shortened string pretending to be an authentic ID. This cap is a server presentation choice, not a measured host limit. Observation and text/search results keep the existing service bounds and paging semantics.

Receipts do not invent final-text snippets from intermediate spans or echo a proposed replacement as independently verified text. Additional reads can resolve task uncertainty; host-owned behavioral/full-byte verification remains separate. Both detailed and compact startup response modes use this same v2 receipt.

Definitive tool failures set isError: true, retaining their domain/audit data. Accepted transactions with advisory warnings remain successful. Infrastructure exceptions return status: outcome_unknown; they do not certify rejection or absence of a commit. Exact keyed retries use the original arguments and key. Other profiles keep their previous error-envelope behavior.

MCP negotiation and startup¶

The adapter supports 2024-11-05, 2025-06-18 and 2025-11-25. It uses a supported requested revision, offers 2025-11-25 for an unsupported revision, and defaults to 2024-11-05 when the client omits it. Invalid initialization is rejected. A connection keeps its negotiated revision.

On 2025-06-18 and 2025-11-25 connections, declarations include outputSchema and annotations. Results carry the same logical JSON in text and structuredContent so hosts can use either channel. The 2024-11-05 connection uses the text channel. The 8 KiB cap applies to logical commit or error JSON. Wire bytes also include envelope escaping and, on newer connections, the second result channel.

Annotations are hints, not enforcement. Read/search/catalog/page are read-only; issuing observations writes authority rows. Submissions are destructive and are not unconditionally idempotent: request-key conflict retries can add audit rows.

Set these on the actual editing MCP process:

PATCHDIFF_MCP_PROFILE=observed_v2
PATCHDIFF_STRICT_OBSERVATION_MODE=1
PATCHDIFF_WAYMARK_MODE=resident

Use the same executable/database/Node configuration as the tested deployment. Trusted initialization, SAVE, replay and export use a separate full-profile connection. The five-tool editor catalog excludes lifecycle calls and the mixed and unobserved mutation routes. The host must keep its operator connection, oracle and privileged data outside the editing agent's tool/context access.

For a live comparison, keep the ordinary task and target mapping; do not add coaching to skip schema discovery, force a particular edit form, or stop checking. Only the owner launches model canaries. Gate 2 and merge authorization are unchanged.

Evidence and costs¶

More specific tools reduce within-tool route alternatives while increasing the number of available tool names. Snapshot nesting adds bytes but removes field translation. Output schemas and receipts also cost context/result bytes. No model latency or correctness benefit is established by static catalog measurements or backend tests. Report the full available catalog, actual host loading if known, text/structured/wire sizes and ordinary-use correctness separately.

Relevant primary specifications: MCP tools 2025-11-25, MCP lifecycle, MCP annotations, and Antigravity changelog. These establish available interface mechanisms, not PatchDIFF performance gains or the installed IDE's exact rendering of schemas and dual-channel results.

Deterministic regression (real stdio + live Postgres, zero model invocations):

python backend/tests/verification/structural_batch/verify.py --editor-v2 --host-finalize --output /tmp/five-file-v2-fresh

This authenticates the unchanged five fixtures and archived regression operations, checks full-byte/behavioral equivalence and trusted scalar finalization. Archived operations/oracle data must never be supplied to a live editing agent.